Como produzir mensagens com o Assistente ECHO (v10.10)?

A criação de mensagens para o utilizador final pode ser realizada na execução de tarefas ou através da API da plataforma "PSO.Bot.CriaMensagem" (PEX) ou "Plataforma.Bot.CriaMensagem" (integrações externas).

As possibilidades de implementação de mensagens personalizadas do Assistente são variadas, desde tutoriais de utilização do produto para os utilizadores (uma vez que estas mensagens poderão ser criadas por PEX e surgir em qualquer ponto do ERP) até à apresentação de tabelas e/ou gráficos com informações relevantes, provenientes de tarefas assíncronas.

O integrador tem total liberdade para adaptar e melhorar a perceção da inteligência do produto, indicando ao utilizador sugestões sobre as tarefas seguintes do seu workflow de trabalho ou informação esclarecedora de suporte à decisão, resultante do cruzamento de dados de várias tabelas do ERP, dados externos ou até da própria infraestrutura Cloud da PRIMAVERA.

Criar mensagens

Para criar mensagens durante a execução de uma tarefa assíncrona, deverá utilizar o seguinte código:

BotMessage companyMessage = this.InitializeNewMessage(instance, EmptyUserCodePlaceHolder, messageText);
companyMessage.CompanyId = enterprise.Code;

O parâmetro "EmptyUserCodePlaceHolder" será utilizado (e substituído) posteriormente no handler "CreateUserBotMessagesHandler", na construção de mensagens personificadas para os utilizadores.

O idioma de apresentação do texto da mensagem depende do idioma do utilizador dentro do ERP.

Para implementar as mensagens tendo em conta o idioma, siga os seguintes passos:

1. Adicionar uma resource ao projeto para cada idioma disponível com o texto da respetiva tradução;
2. Invocar a seguinte função, substituindo "RES_Text" pelo nome da resource criada;

string messageText = Entities.Helpers.Functions.GetAllAvailableCulturesForResource(Properties.Resources.ResourceManager, "RES_Text", param1, param2, ...);

O texto resultante será uma string json com a mensagem estruturada. Se necessário, poderá indicar nos parâmetros os literais que devem preencher os identificadores "{0}, {1}, {...}" para compor a string.

Implementar uma ação na mensagem

Para exemplificar, consideremos uma das tarefas atualmente disponíveis no ECHO - a atualização de clientes a partir das informações nos serviços PRIMAVERA.

A mensagem presente na resource de texto deve seguir estes modelos: "Os dados do cliente {0} foram alterados. Deseja atualizar esses dados na ficha de cliente? {1} | {2}. Saiba mais {3}.", deixando claro onde serão criadas as ações.

A primeira ação destina-se a suportar um drilld own para o cliente apresentado. Por exemplo, se o nome do cliente for "ALCAD", a mensagem mostra o nome do cliente em vez do "{0}" e permite clicar para abrir a ficha de clientes.

Código da ação:

new BotMessageAction() 
{ 
	ActionIndex = 0, 
	ActionType = BotMessageActionType.Drilldown, 
	ActionParameters = "GCP|1|GCP_MOSTRAMANUTENCAO|Manutencao=mnuTabClientes|Entidade=ALCAD", 
	Text = "ALCAD" 
},

A segunda e terceira ações destinam-se a executar tarefas, ou seja, a própria mensagem gerada por uma tarefa pode desencadear outra tarefa. A primeira ação implementa a opção Sim que confirma a intenção do utilizador de atualizar os dados da entidade "ALCAD".

Código da ação:

new BotMessageAction() 
{ 
	ActionIndex = 1, 
	ActionType = BotMessageActionType.ScheduleUserTask, 
	TaskParameters = new BotMessageActionTaskParameters() 
	{ 
		CancelIfAnyRelatedActionHasExecuted = true, 
		RelatedActionsIndexes = new Collection() { "3" }, 
		TopicId = this.TopicId, 
		TaskId = "ExecuteEntityUpdate", 
		PipelineId = SyncEntityPipelineName, 
		ExecutionParameters = "Company=DEMO|Customers=ALCAD" 
	}, 
	Text = Entities.Helpers.Functions.GetAllAvailableCulturesForResource(Properties.Resources.ResourceManager, YesResource, null) 
},

As opções "CancelIfAnyRelatedActionHasExecuted" e "RelatedActionsIndexes" destinam-se a cancelar a ação se for executada outra ação relacionada, o que significa que se o utilizador ou outros utilizadores já tiverem clicado em "Sim para todos", a ação não terá qualquer resultado, uma vez que a ação relacionada é mais abrangente que a atual.

A quarta ação refere-se à abertura de uma nova página no Bot, onde pode ver detalhes da mensagem.

Código da ação:

new BotMessageAction() 
{ 
	ActionIndex = 3, 
	ActionType = BotMessageActionType.ResultsPage, 
	ActionParameters = string.Empty, 
	Text = Entities.Helpers.Functions.GetAllAvailableCulturesForResource(Properties.Resources.ResourceManager, HereResource, null) 
},

Todas as ações devem ser adicionadas à mensagem criada anteriormente da seguinte forma:

Collection() actions = new Collection();
actions.Add(new BotMessageAction() {.....});
actions.Add(new BotMessageAction() {.....});
actions.Add(new BotMessageAction() {.....});

companyMessage.Actions = actions;

A última ação é a definição do texto a inserir em "{3}", sendo necessário definir os resultados a apresentar para funcionar. No nosso exemplo, a atualização de dados refere-se ao cliente "ALCAD" mas poderão ser encontrados outros clientes com dados diferentes nas fichas. Nesse caso, será apresentada uma lista de clientes que serão afetados pela atualização.

Criar listas de resultados

De seguida, demonstramos como criar as listas de resultados e três formas diferentes de apresentar os resultados: em texto, tabelas e gráficos.

1. Preencher os resultados:

• Com dados de uma DataTable (exemplo simples)

var results = new BotMessageResults();
results.AddDataTableToResultSet(dataTableComOsDados);
companyMessage.Results = results;

// ou p.ex.

DataTable dt = new DataTable();
dt.Columns.Add("Mês", typeof(string));
dt.Columns.Add("Vendas", typeof(int));
dt.Rows.Add("Janeiro", 32);
dt.Rows.Add("Fevereiro", 45);
dt.Rows.Add("Março", 54);
dt.Rows.Add("Abril", 110);
dt.Rows.Add("Maio", 150);
dt.Rows.Add("Junho", 120);
dt.Rows.Add("Julho", 80);
dt.Rows.Add("Agosto", 10);
dt.Rows.Add("Setembro", 5);
dt.Rows.Add("Outubro", 15);
dt.Rows.Add("Novembro", 25);
dt.Rows.Add("Dezembro", 70);

• Os próprios resultados podem ter ações. Nesse caso, podemos adicioná-las ao result set da seguinte forma:

foreach (List linha in results.ResultSets.First())
{
    // Add action for the first column (entity, ex: "Sofrio")
    linha[1].Action = new BotMessageAction()
    {
         ActionIndex = 0,
         ActionType = BotMessageActionType.Drilldown,
         ActionParameters = string.Concat("GCP|1|GCP_MOSTRAMANUTENCAO|Manutencao=mnuTabClientes|Entidade=" + linha[0].Value),
         Text = linha[1].Value                        
    };              
}

Neste exemplo, usamos o valor do cliente, (ALCAD) para criar um link de drill down para a ficha de clientes.

• Com dados definidos pelo utilizador:

var results = new BotMessageResults();
Collection valuesList = new Collection();

valuesList.Add(new Cell()
{
   Action = null,
   Name = "Janeiro",
   Value = "32"
});

valuesList.Add(new Cell() 
{ 
   Action = null, 
   Name = "Fevereiro", 
   Value = "45" 
});

results.AddValuesListToResultSet(valuesList);
companyMessage.Results = results;

2. Apresentar os resultados. A seleção da view a apresentar é efetuada utilizando o objeto "ViewConfig" do objeto "BotMessageResults" criado no passo anterior.

• Exemplo para tabela:

results.ViewConfig.Add
( 
	new Entities.Results.TableView() 
	{ 
		Order = 0, 
		Columns = new System.Collections.ObjectModel.Collection() 
		{ 
			new Entities.Results.Column() 
			{ 
				Name = string.Empty, 
				Visible = false 
			}, 
			new Entities.Results.Column() 
			{ 
				Name = Entities.Helpers.Functions.GetAllAvailableCulturesForResource(Properties.Resources.ResourceManager, NameResource, null), 
				Visible = true 
			}, 
		}, 
		ResultSet = 0, 
		ShowTitle = true, 
		Title = Entities.Helpers.Functions.GetAllAvailableCulturesForResource(Properties.Resources.ResourceManager, OutdatedDataResource, null) 
	}
);

• Exemplo para gráfico:

results.ViewConfig.Add(new Entities.Results.GraphView()
{
     Columns = new Collection()
     {
        new Column() { Name = "Mês", Visible = true, Axis = "x" },
        new Column() { Name = "Vendas", Visible = true }                    
     },

     Order = 0,
     GraphType = GraphType.Bar,
     ResultSet = 0,
     ShowTitle = true,
     Title = "Vendas"
});

• Exemplo para texto:

results.ViewConfig.Add(
new Entities.Results.LabelView()
{
   Order = 0,
   Text = "Texto a apresentar na label"
});

Também é possível criar mensagens do Bot durante a utilização do ERP  através das APIs referidas no início do artigo.

Por limitação atual da integração com o ERP, estas mensagens não podem ter resultados, mas alternativamente é possível introduzir ações nas mensagens, conforme explicado.

Nota: Passar ações através do motor deve ser efetuado através de um objeto "PrimaveraOrderedDictionary", no parâmetro "objAccoes" da função "Plataforma.Bot.CriaMensagem". Este objeto pode conter uma ou mais ações do tipo "Primavera.Bot.Engine100.ErpViewModel.BotActionDto". Caso não existam ações, é possível passar um nulo neste parâmetro.

Assim, é possível por exemplo agendar tarefas no ECHO, em que o próprio assistente pede uma confirmação antes de agendar a execução da tarefa.

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