Como executar tarefas com o Assistente Echo (v10.10)?

É possível executar tarefas fora do processo do ERP com o Assistente ECHO. Estas tarefas poderão ser agendadas automaticamente ou através de operações no ERP.

A execução da tarefa permite a criação de mensagens do ECHO, que podem ser utilizadas, por exemplo, para reportar o final da execução ao utilizador. Desta forma, é possível que o utilizador execute uma determinada tarefa "a pedido" em consequência de uma ação no ERP, ou automaticamente durante a noite ou ao fim de semana, por exemplo.

Esta abordagem liberta recursos do ERP e até do posto de trabalho, dado que as tarefas são sempre executadas no servidor.

A execução de tarefas no ECHO está limitada pela disponibilidade de recursos no servidor. Isto é, a tarefa pode ser atrasada automaticamente, caso o servidor se encontre demasiado limitado em termos de disco, memória, CPU e recursos no SQL Server.

Criar tarefas

Para criar tarefas, é necessário primeiro criar um tópico. Pressupõe-se, neste ponto, que já exista um registo na tabela "Bot.BotTopics" identificando o novo tópico.
Deverá consultar o artigo "Como extender o Assistente Echo (v10.10 SR1)?" para conhecer mais detalhes sobre a sua geração.

1. Na tabela "Bot.BotTasks", inserir um novo registo para uma "Task", por exemplo com o nome: "TaskExecutionExample";
2. Indicar o nome da "task" e a "pipeline" que a task deverá executar, por exemplo: "TaskExecutionExamplePipeline" para a pipeline;
3. Definir a calendarização se pretender que a "task" execute automaticamente. O ficheiro SQL de exemplo, no projeto do tópico, tem todas as combinações possíveis explicadas;
4. Definir o tempo de validade das mensagens geradas por esta "task";
5. Definir o "scope" da mensagem, ou seja, se a "task" executará uma vez por instância, uma vez por combinação de instância e empresa ou uma vez por combinação de instância, empresa e utilizadores;
6. Indicar as plataformas suportadas pelo tópico. É possível filtrar por linha e tipo de ambiente;
7. Criar a "pipeline" e definira lista de "handlers" que deverá executar, na coluna "PipelineConfig" com o nome que indicou ao associar à "task";

• Se pretender ter presente no seu "handler" a informação sobre as instâncias/empresas/utilizadores do ERP, deverá colocar este handler em primeiro lugar da pipeline.

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

• De seguida, colocar o(s) seu(s) handler(s). Por exemplo: "TaskExecutionExampleHandler".

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

• Se durante a execução da sua tarefa, forem geradas novas mensagens para o ECHO, deverá colocar os seguintes "handlers" para que as mesmas sejam tratadas ("CreateUserBotMessagesHandler") e posteriormente gravadas ("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=""/>
  

O ponto anterior está adaptado à realidade normal de produzir tópicos e ações que integram com o ERP e geram mensagens no final. A lista de "handlers" pode ser totalmente customizada pelo integrador e incluir, por exemplo, "handlers" que utilizem informação de outras fontes.

Neste momento, o Assistente ECHO já "sabe" como executar a sua tarefa. Esta tarefa pode ser agendada manualmente, mas também será agendada automaticamente no calendário definido.
Se remover o valor da coluna "ScheduleConfig", a tarefa apenas será agendada manualmente através da invocação da função da plataforma: "PSO.Bot.CriaTarefa" através de PEX ou "Plataforma.Bot.CriaTarefa" através de uma integração externa.

Tarefa e "pipeline" criadas nos pontos anteriores (a definição e detalhe de cada coluna está presente no ficheiro SQL de exemplo no GitHub):

INSERT INTO Bot.BotTasks(NaturalKey, DescriptionId, TopicId, Importance, ScheduleConfig, MessageConfig, PlatformsConfig, PipelineConfig, [System], 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 tarefas

De seguida, deverá proceder à implementação da tarefa:

No projeto do tópico, deverá criar um nova classe com um nome à sua escolha e o sufixo "Handler". Por exemplo: "TaskExecutionExampleHandler.cs".

• A classe tem de ser pública e herdar de "TopicHandlerBase" (Adicionar using Primavera.Hurakan.BotHandlers);
• Efetuar a implementação da classe abstrata (ou seja, o override do método "ProcessMessage");
• Adicionar o "using System.ComponentModel.Composition;" no início do ficheiro;
• Adicionar os "exports" através dos quais o Echo utilizará a Management Extensibility Framework (MEF) da .NET Framework, para localizar a nova classe.

[Export(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.