How to create messages with the Echo Assistant?

In this article, we focus on the possibilities to create messages for the final user.

These messages can be created when executing tasks or using the API of the platform "PSO.Bot.CriaMensagem" (PEX) or "Plataforma.Bot.CriaMensagem" (external integrations).

The possibility to implement customizes Assistant messages ranges from product tutorials to users (since these messages can be created by PEX and display anywhere in the ERP) until the table and/or graphic display with relevant information, from asynchronous tasks.

The integrator has total freedom to adapt and improve the perception of the product intelligence, surprising the user with suggestions on the following tasks of its workflow or enlightening information to support decision-making, by crossing data from several ERP tables, external data or even the own PRIMAVERA Cloud infrastructure.

Create messages

To create messages during the execution of an asynchronous task, use the following code:

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

The message display language depends on the language used on the ERP.

To implement messages considering the language, follow these steps:

1. Add a resource to the project for each available language with the text of the corresponding translation.
2. Invoke the following function, replacing "RES_Text" with the name of the resource created.

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

The resulting text will be a json string with the structured message. If necessary, you can specify in the parameters the literals that must fill in the identifiers "{0}, {1}, {...}" to compose the string.

Implement an action in the message

To exemplify, let's consider one of the tasks currently available in Echo - the client update from the information in the PRIMAVERA services.

The message present in the text resource must follow one of these models: "The details for customer {0} have changed. Do you want to update the customer file data? {1} | {2}. Learn more {3}.", making it clear where the actions will be created.

• The first action is meant to support a drilldown for the presented customer. For example, if the client name is "ALCAD", the message shows the client name instead of "{0}" and allows to click to open the client file. The code to implement this action is the following:

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

• The second and third actions are meant to execute tasks, that is, the message generated by a task can originate another task. The first action implements the option "Yes" that confirms the user purpose to update the "ALCAD" entity data. The code for this action is:

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

The options "CancelIfAnyRelatedActionHasExecuted" and "RelatedActionsIndexes" are meant to cancel the action if another related action is executed, which means that the user or other users pressed "Yes for all", the action will not produce any result, considering that the related action is more comprehensive than the current one.

• The fourth action refers to the opening of a new page in the Bot, where you can see the details of the message. The code for this action is:

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

All actions must be added to the message previously created, this way:

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

companyMessage.Actions = actions;

• The last action is the text definition to place in "{3}". In order for it to work, it is necessary to define the results to be shown. In our example, the data update refers to the client "ALCAD", but other clients can be found with different data in the files. In that case, a list of the clients that will be affected by the update will be presented.

Create result lists

Next, we show you how to create the results lists and the three different ways of presenting the results: text, tables and charts.

1. Fill in the results:

• With data from a DataTable (simple example)

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

// or for 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);

• The results can have actions. In this case, we can add them to the result set the following way:

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

In this example, we use the client value (ALCAD) to create a drilldown link for the client file.

• With data defined by the user:

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. Display the results. The view to display is selected using the object "ViewConfig" from the object "BotMessageResults" created in the previous step.

• Table example:

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

• Example for graphic:

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

• Text example:

results.ViewConfig.Add(
new Entities.Results.LabelView()
{
   Order = 0,
   Text = "Text to present on the label"
});

It is also possible to create Bot messages when using the ERP  from the APIs mentioned in the start of the article.

By the current limitation of the integration with the ERP, these messages cannot have results, but as an alternative, it is possible to insert actions in the messages, as explained.

Note: Moving actions with the engine can be performed using the object "PrimaveraOrderedDictionary", in the "objAccoes" parameter of the function "Plataforma.Bot.CriaMensagem". This object can contain one or more actions of the type "Primavera.Bot.Engine100.ErpViewModel.BotActionDto". If there are no actions, it is possible to move a blank in this parameter.

Thus, it is possible, for example, to schedule tasks in ECHO, in which the assistant requests a confirmation before scheduling the task execution.

The detailed code in this article is available in the PRIMAVERA GitHub page.