¿Cómo ejecutar tareas con el Asistente ECHO (v10.10)?

Puede ejecutar tareas fuera del proceso del ERP con el Asistente ECHO. Estas tareas pueden programarse automáticamente o mediante operaciones en el ERP.

La ejecución de la tarea permite la creación de mensajes del ECHO, que pueden utilizarse, por ejemplo, para informar al usuario del final de la ejecución. De este modo, es posible que el usuario ejecute una tarea determinada "bajo demanda" como resultado de una acción en el ERP, o de forma automática durante la noche o el fin de semana, por ejemplo.

Este enfoque libera recursos en el ERP e incluso en el lugar de trabajo, ya que las tareas se ejecutan siempre en el servidor.

La ejecución de las tareas en ECHO está limitada por la disponibilidad de recursos en el servidor. En otras palabras, la tarea puede retrasarse automáticamente si el servidor está demasiado limitado en cuanto a recursos de disco, memoria, CPU y SQL Server.

Creación de tareas

Para crear tareas, primero debe crear un tema. En este punto se supone que ya existe un registro en la tabla "Bot.BotTopics" que identifica el nuevo tema.
Debe consultar el artículo "¿Cómo extender el Asistente ECHO (v10.10 SR1)?" para conocer más detalles sobre su generación.

1. En la tabla "Bot.BotTasks", inserte un nuevo registro para una "Task", por ejemplo con el nombre: "TaskExecutionExample";
2. Indique el nombre de la "task" y la "pipeline" que debe ejecutar la task, por ejemplo: "TaskExecutionExamplePipeline" para la "pipeline";
3. Definir la programación si desea que la task se ejecute automáticamente. El archivo SQL de ejemplo del proyecto del tema tiene todas las combinaciones posibles explicadas;
4. Definir el tiempo de validez de los mensajes generados por esta "task";
5. Definir el "scope" del mensaje, es decir, si la "task" se ejecutará una vez por instancia, una vez por combinación de instancia y empresa o una vez por combinación de instancia, empresa y usuarios;
6. Indicar las plataformas soportadas por el tema. Se puede filtrar por línea y tipo de entorno;
7. Crear la "pipeline" y definir la lista de "handlers" que deberá ejecutar, en la columna "PipelineConfig" con el nombre que introdujo al asociar la "task";

• Si desea tener presente en su "handler" información sobre las instancias/empresas/usuarios del ERP, deberá colocar este handler en primer lugar de la pipeline.

  <Handler Id="ErpReadConfigHandler" Order="1" Behavior="Reader" Type="Primavera.Platform.HurakanHandlers.ErpReadConfig" ConfigStr="instanceIdFilter=%%InstanceId%%;userFiltler=%%UserFilter%%;enterpriseFilter=%%EnterpriseFilter%%"/>

• A continuación, coloque su(s) handler(es). Por ejemplo: "TaskExecutionExampleHandler".

  <Handler Id="TaskExecutionExampleHandler" Order="2" Behavior="Reader" Type="Primavera.Bot.DevelopersNetworkTopic.Handlers.TaskExecutionExampleHandler" ConfigStr="topicId=%%TopicId%%;taskId=%%TaskId%%"/>

• Si durante la ejecución de su tarea se generan nuevos mensajes para ECHO, deberá colocar los siguientes handlers para que puedan ser procesados ("CreateUserBotMessagesHandler") y posteriormente guardados ("SaveBotMessagesHandler"):

  <Handler Id="CreateUserBotMessagesHandler" Order="3" Behavior="Reader" Type="Primavera.Hurakan.BotHandlers.CreateUserBotMessages" ConfigStr="/>
  <Handler Id="SaveBotMessagesHandler" Order="4" Behavior="Reader" Type="Primavera.Hurakan.BotHandlers.SaveBotMessages" ConfigStr="/>
  

El punto anterior se adapta a la realidad normal de producir temas y acciones que se integran con el ERP y generan mensajes al final. La lista de "handlers" puede ser totalmente personalizada por el integrador e incluir, por ejemplo, "handlers" que utilicen información de otras fuentes.

En este punto, el Asistente ECO ya "sabe" cómo ejecutar su tarea. Esta tarea puede programarse manualmente, pero también se programará automáticamente, en el calendario definido.
Si elimina el valor de la columna "ScheduleConfig", la tarea solo se programará manualmente a través de la invocación de la función de la plataforma: "PSO.Bot.CriaTarefa" a través de PEX o "Plataforma.Bot.CriaTarefa" a través de un integración externa.

Tarea y "pipeline" creadas en los puntos anteriores (la definición y el detalle de cada columna están presentes en el archivo SQL de ejemplo en GitHub):

INSERT INTO Bot.BotTasks(NaturalKey, DescriptionId, TopicId, Importance, ScheduleConfig, MessageConfig, PlatformsConfig, PipelineConfig, [/av_em], Active, CreatedBy, ModifiedBy, AllowConfigReceivers, ReceiverOption, [Version]) 
VALUES(
	'TaskExecutionExample', 
	'Task_ExecutionExample', 
	@TopicId, 
	1, 
	'{"Active":true,"Execute":"Daily","StartAt":1,"StartTolerance":31}', 
	'{"Scope":"Instance","ExpireDays":365}', 
	'[{"Version":"V100", "platform":"Executive"},{"Version":"V100", "platform":"Professional"}]', 
	'<Pipeline Id="DevelopersNetworkTopicPipeline">
		<Handlers>
			<Handler Id="ErpReadConfigHandler" Order="1" Behavior="Reader" Type="Primavera.Platform.HurakanHandlers.ErpReadConfig" ConfigStr="instanceIdFilter=%%InstanceId%%;userFiltler=%%UserFilter%%;enterpriseFilter=%%EnterpriseFilter%%"/>
			<Handler Id="TaskExecutionExampleHandler" Order="2" Behavior="Reader" Type="Primavera.Bot.DevelopersNetworkTopic.Handlers.TaskExecutionExampleHandler" ConfigStr="topicId=%%TopicId%%;taskId=%%TaskId%%"/>
			<Handler Id="CreateUserBotMessagesHandler" Order="3" Behavior="Reader" Type="Primavera.Hurakan.BotHandlers.CreateUserBotMessages" ConfigStr="/>
			<Handler Id="SaveBotMessagesHandler" Order="4" Behavior="Reader" Type="Primavera.Hurakan.BotHandlers.SaveBotMessages" ConfigStr="/>
		</Handlers>
	</Pipeline>', 
	0, 1, 'MyUser', 'MyUser', 1, -1, 1)

Implementar tareas

A continuación, debe implementar la tarea:

En el proyecto del tema, debe crear una nueva clase con un nombre de su elección y el sufijo "Handler". Por ejemplo: "TaskExecutionExampleHandler.cs".

• La clase debe ser pública y heredar de "TopicHandlerBase" (Añada using Primavera.Hurakan.BotHandlers);
• Implementar la clase abstracta (es decir, el override del método "ProcessMessage");
• Añadir "using System.ComponentModel.Composition;" al principio del archivo;
• Añadir los "exports" a través de los cuales Echo utilizará el Management Extensibility Framework (MEF) del .NET Framework para localizar la nueva clase.

[/av_rt(typeof(IHandler))]
[Export(typeof())]

• Adicionar o seguinte código no início do método "ProcessMessage:

this.TopicId = "; 
this.TaskId = "; 
this.Initialize(message as IntegrationMessage);

• A partir deste momento, caso tenha colocado o handler de leitura de dados do ERP, terá um objecto "this.Instances" com as instâncias/empresas produtivas/utilizadores que obedecem ao scope da tarefa, ou seja:
  - Se o scope é "Instance", terá uma das instâncias disponíveis com todas as empresas produtivas e utilizadores;
  - Se o scope é "Intance|Enterprise", terá uma das instâncias, uma das suas empresas e todos os utilizadores;
  - Se o scope é "Instance|Enterprise|User", terá apenas uma das combinações possíveis;
• Serão agendadas automaticamente tantas tarefas quantas necessárias para cumprir o "scope" da tarefa em todas as instâncias/empresas produtivas/utilizadores. O scope apenas define a unidade de processamento, para alargar ou acelerar as tarefas dependendo da natureza das mesmas. É uma opção de implementação;
• De seguida, deverá ser criada uma iteração por cada uma das instâncias/empresas/utilizadores, para que o handler se adapte automaticamente à unidade de processamento. Ou seja:

foreach (Instance instance in this.Instances) 
{ 
	foreach (Enterprise enterprise in instance.Enterprises) 
	{ 
		(...) 
		this.BuildConnectionString(instance.ServerSql, instance.LoginSql, instance.PasswordSql, instance.Database); 
		(...) 
	} 
}

Caso pretenda efetuar consultas SQL à base de dados, terá de fazer a inicialização da connection string, como demonstrado acima:

• Depois desta operação, bastará usar o método "this.ExecuteNonQuery" e/ou "this.Fill" para executar uma instrução SQL ou para efetuar uma consulta SQL, respetivamente;
• O restante da implementação da execução da tarefa em si é de implementação livre do cliente.

Se for necessário utilizar o motor do ERP, este está disponível através de reflection e pode ser utilizado da seguinte forma:

using (ErpHelper erpHelper = new ErpHelper()) 
{ 
	// edit a customer and change something... 
	erpHelper.SetErpConnectionString(instance, enterprise.Code);
	
	dynamic customerObject = erpHelper.Erp.Base.Clientes.Edita(customerId); 
	customerObject.Nome = "Nome"; 
	
	erpHelper.Erp.Base.Clientes.Actualiza(customerObject); 
}

A utilização do "ErpHelper" dentro do "using" garante que o padrão de "dispose" é corretamente aplicado, bem como a ligação ao motor é destruída assim que a execução do bloco de código terminar.

Caso seja necessário criar mensagens como consequência da execução, poderá fazê-lo da seguinte forma:

• Criar uma lista de mensagens, no início da função:

protected List<BotMessage> BotMessages { get; set; };

• Criar uma lista de mensagens, por instância, dentro do "foreach" da instância:

List<BotMessage> instanceMessages = new List<BotMessage>();

• Dentro do ciclo de instâncias, executar o seguinte bloco de código para criar uma mensagem da instância:

BotMessage companyMessage = this.InitializeNewMessage(instance, EmptyUserCodePlaceHolder, "A tarefa 'TaskExecutionExample' foi concluída com sucesso.");
companyMessage.CompanyId = enterprise.Code;
instanceMessages.Add(companyMessage);

• No final do ciclo da instância, adicionar as mensagens ao objeto principal:

this.BotMessages.Add(instance.Id, instanceMessages);

• No final da função, adicionar o seguinte código para transferir as mensagens para o handler que efetuará a sua gravação:

return this.BuildIntegrationMessage(this.BotMessages);

Desta forma, é possível efetuar a execução de qualquer tarefa demorada de forma automática, a pedido com integração com os motores do ERP ou com execução direta de código SQL, bem como o report do seu sucesso (ou insucesso) ao utilizador final no ERP.

O código detalhado neste artigo encontra-se disponível na página do GitHub da PRIMAVERA.