How to create messages with the ECHO Assistant (v10.10)?

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 customized Assistant messages ranges from product tutorials for users (since these messages can be created by PEX and displayed anywhere in the ERP) to the presentation of tables and/or graphics with relevant information, originated from asynchronous tasks.

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

Create messages

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

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

The parameter "EmptyUserCodePlaceHolder" will be used (and replaced) later in the handler "CreateUserBotMessagesHandler", when creating custom user messages.

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 string json 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.

Implementing 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.

Action code:

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.

Action code:

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 if the user or other users have clicked on "Yes for all", the action will not produce any result, because 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.

Action code:

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 definition of the text to be inserted in "{3}", and it is necessary to define the results to be presented in order for it to work. 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.

Creating result lists

Next, we show you how to create the result lists and the three different ways of presenting the results: in 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;

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

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

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 customer value, (ALCAD) to create a drill down link to the customer 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 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) 
	}
);

• Chart example:

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 = "Texto a apresentar na label"
});

It is also possible to create Bot messages during the use of the ERP, using the APIs mentioned at 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.