¿Cómo producir mensajes con el Asistente ECHO?

En este artículo nos centraremos en las posibilidades de crear mensajes para el usuario final.

Estos mensajes pueden crearse durante la ejecución de la tarea o a través de la API de la plataforma "PSO.Bot.CriaMensagem" (PEX) o "Plataforma.Bot.CriaMensagem" (integraciones externas).

Las posibilidades de implementación de mensajes personalizados del asistente van desde tutoriales de uso de productos para los usuarios (ya que estos mensajes pueden ser creados por PEX y aparecer en cualquier parte del ERP) hasta la presentación de tablas y/o gráficos con información relevante de tareas asíncronas.

El integrador tiene total libertad para adaptar y mejorar la percepción de la inteligencia del producto, sorprendiendo al usuario con sugerencias sobre las próximas tareas de su flujo de trabajo, o iluminando la información de apoyo a la toma de decisiones resultante del cruce de datos de varias tablas del ERP, datos externos o incluso la propia infraestructura en la nube de PRIMAVERA.

Crear mensajes

Para crear mensajes durante la ejecución de una tarea asíncrona, utilice el código siguiente:

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

El idioma de visualización del texto del mensaje depende del idioma del usuario dentro del ERP.

Para implementar los mensajes teniendo en cuenta el idioma, siga estos pasos:

1. Añada un resource al proyecto para cada idioma disponible con el texto de la respectiva traducción.
2. Invoque la siguiente función, sustituyendo "RES_Text" por el nombre del resource creado.

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

El texto resultante será un string json con el mensaje estructurado. Si es necesario, puede indicar en los parámetros los literales que deben rellenar los identificadores "{0}, {1}, {...}" para formar el string.

Implementar una acción en el mensaje

Para ejemplificar, consideremos una de las tareas disponibles actualmente en Echo: la actualización de clientes basada en la información de los servicios PRIMAVERA.

El mensaje en el resource de texto debe seguir estos modelos: "Los datos del cliente {0} han sido modificados. ¿Desea actualizar estos datos en la ficha de cliente? {1} | {2}. Más información{3}.", dejando claro dónde se crearán las acciones.

• La primera acción se destina a soportar un drilldown del cliente presentado. Por ejemplo, si el nombre del cliente es "ALCAD", el mensaje muestra el nombre del cliente en lugar de "{0}" y permite hacer clic para abrir la ficha del cliente. El código para implementar esta acción es el siguiente:

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

• La segunda y tercera acciones están destinadas a ejecutar tareas, es decir, el propio mensaje generado por una tarea puede desencadenar otra tarea. La primera acción implementa la opción "Sí", que confirma la intención del usuario de actualizar los datos de la entidad "ALCAD". El código de esta acción es:

 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)
                },

Las opciones "CancelIfAnyRelatedActionHasExecuted" y "RelatedActionsIndexes" tienen por objeto cancelar la acción si se lleva a cabo otra acción relacionada, lo que significa que si el usuario u otros usuarios ya han hecho clic en "Sim para todos", la acción no tendrá ningún resultado, ya que la acción relacionada es más amplia que la actual.

• La cuarta acción se refiere a la apertura de una nueva página en el Bot, donde se pueden ver los detalles del mensaje. El código de esta acción es:

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

Todas las acciones deben añadirse al mensaje creado previamente de esta forma:

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

companyMessage.Actions = actions;

• La última acción es la definición del texto a colocar en "{3}". Para que funcione, debe definir los resultados que se mostrarán. En nuestro ejemplo, la actualización de datos se refiere al cliente "ALCAD", pero en las fichas pueden encontrarse otros clientes con datos diferentes. En este caso, se mostrará una lista de los clientes afectados por la actualización.

Crear listas de resultados

A continuación demostramos cómo crear listas de resultados y las tres formas diferentes de presentar los resultados: en texto, tablas y gráficos.

1. Rellenar los resultados:

• Con datos de una DataTable (ejemplo sencillo)

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);

• Los propios resultados pueden tener acciones. En este caso, podemos añadirlas al result set de la siguiente manera:

 foreach (List linha in results.ResultSets.First())
 {
    // Add action for the first column (entity, ex: "Sofrio") línea[/av_ction = 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 drilldown 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 como alternativa, é possível introduzir ações nas mensagens, conforme explicado.

Nota: Passar ações através do motor deve ser feito 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.