Messages

Introduction to messages

Error messages, warnings or informational error messages are also modelled in the Software Factory, with the possibility to define a translation, severity and location. This applies to messages that you add to your functionality (code templates) and messages caused by database errors, such as constraint errors.

Example of a message as it may appear in an application

Model a message

To model a message:

menu User interface > Messages > tab Form

1. Add a Message id to reference the message from the business logic. This ID is translated in the Translations tab page.

2. Select a Message location to determine how the message should be displayed:

   • Pop-up.

   • Panel

     • Windows GUI The message is displayed at the bottom of the screen.

     • Universal GUI The message is displayed in a snack bar at the bottom of the screen.
       

     • To clear the panel, send the message clear_panel, to add a separator line to the panel, send the message add_separator.

       warning

       Use clear_panel and add_separator only in code, never as confirmation messages in a task or as messages in a process action.

   • None (suppress) - suppresses database messages.

   • Windows GUI Debug - The message is displayed in the debug window.

3. Select the Severity of the message: Error, Warning, or Information. This determines how the user interfaces and the Indicium application tier handle the action that caused the message. The action is only canceled for errors.

4. To translate database messages, you can use the fields in the group Database message capture. For more information, see Database message.

5. Universal Windows GUI To add a sound to your message, upload an Audio file. The file will be played when a user receives the message. The allowed extensions are .wav and .mp3. You can add sound to pop-ups and panel messages.

Form to create a message

Database messages

When user input violates database integrity rules, such as a duplicate key error, the database returns a technical error. The Software Factory captures these errors and delivers them to the user in a more user-friendly format using translated messages.

To add your own messages for database errors, using regular expressions:

menu User interface > Messages > tab Form > group Database message capture

1. Add an Error code.
2. In the field Regular expression, enter a regular expression that extracts relevant details from the error messages. You can define capturing groups and reuse them as parameters enclosed in curly braces (for example, {group}). Use this feature thoughtfully, as it can make the message more technical.
3. The field Priority is mandatory if you have populated the field Regular expression. It allows you to prioritize one message over another when more are applicable. A lower number indicates a higher priority.

Example of a regular expression for check constraint violations

In the example below, the regular expression extracts the name of the violated check constraint, the database, table, and column.

The INSERT statement conflicted with the CHECK constraint "(?<a>.+)\". the conflict occurred in database "(?<b>.+)", table "(?<c>.+)"(, column '(?<d>.+)')?\.

A message that captures all check constraint errors

tip

To create unique messages for check constraint errors, see Check constraints for tables.

Options for messages in process flows

Messages in the process action Show message can have additional options to give users a choice. The response types for these messages can be affirmative or negative, corresponding to the green or red arrows in the process flows.

Adding multiple affirmative or negative options will result in a different continuation of the process flow. To achieve this, the Status code value of a message option is passed as the Status code output parameter of the process action.

To add options to messages in a process flow:

menu User interface > Messages > tab Message options

1. Select a Message option name.
2. Select the Response type:
   • Affirmative - Affirmative messages get a unique status code of zero or higher (0, 1, 2, 3, etc.).
   • Negative - Negative messages get a unique negative status code (-1, -2, -3, etc.).
3. Optional. Select an Icon to display with the message option.
4. Optional. Change the Sequence no to determine the order of the message options in the dialog.

For example, this configuration in the Software Factory:

will result in this dialog in the GUI:

Translate a message

After modeling a message, you can translate it. Parameters can be defined with 0, 1, 2, etc.

menu User interface > Messages > tab Translations

For more information, see Translations.

Task confirmation message

You can choose a confirmation message to show up when executing a task (see Create a task). To make this message dynamic, you can add one or more parameters to it. To do this, you need to follow a few steps:

1. Add the parameter you want to use to the task.
2. Create a default procedure for the task, to fill the parameter you just configured.
3. Create a message for your task confirmation. In the message translation, add the parameter you created for your task.

Message with a parameter

The result in an application:

Message with a parameter in an application

Message from an SQL template

To send a message from an SQL template, you can use the tsf_send_message procedure:

tsf_send_message [message id], [parameter string], [abort]

Parameter string

This is an optional XML string, in which you can configure what parameters can be used in the translation. It is also possible to use translations of model objects, such as columns or tables.

An example parameter string, which specifies the text Welcome for parameter 0, and the plural translation of column name of the customer table for parameter 1 is shown below.

<text>Welcome</text><col tabid="customer" colid="name" transl="plural"/>

Supported XML elements

The following XML elements with associated attributes can be used:

<text>Text to display</text>
<tab tabid="tab_id" transl="standard, form, grid, plural"></tab>
<col tabid="tab_id" colid="col_id" transl=""></col>
<domelement domid="dom_id" elementid="element_id" transl=""></domelement>
<task taskid="task_id" transl=""></task>
<taskparam taskid="task_id" taskparamid="task_parmtr_id" transl=""></taskparam>
<report reportid="report_id" transl=""></report>
<reportparam reportid="report_id" reportparamid="report_parmtr_id" transl=""></reportparam>

For example, for message duplicate_customer with translation 'Note, 0 already exists as a 1' you can use the following:

exec tsf_send_message 'duplicate_customer', 
  '<text>Thinkwise</text><tab tabid="customer" transl="standard"/>', 1;

This results in 'Note, Thinkwise already exists as a Customer'.

Example of an XML string with two variables

Next is an example of an SQL string that constructs an XML string containing two variables, @var1 and @var2, and then passes it to the specified stored procedure dbo.tsf_send_message:

declare @xml nvarchar(500) = concat(
    (select @var1 for xml path('text')), 
    (select @var2 for xml path('text'))
)

exec dbo.tsf_send_message 'message_with_parameters', @xml, 1

Special characters in the parameter string parameter

warning

In the parameter string parameter, special characters must be escaped. Using select @var for xml path ('text') automatically escapes special characters. See also Example of an XML string with two variables.

For example, to specify the & character, write: <text>This text contains an &amp; character</text>.

The special characters are:

To specify:	Write:
&	&
"	"
'	'
<	&lt;
>	&gt;

Abort

This parameter tells the GUI or Indicium Service Tier what should happen when the message occurs:

• 0 continues the flow in which the message is executed. This results in a database severity level of 9.

• 1 or NULL means that the action should be considered reversed. This will result in a database severity level of 16. This can lead, for example, to a process flow following the red process step, or a record remaining in edit mode for the user to correct the error or cancel editing.

  Because SQL Server does not rollback automatically, a rollback and return must be explicitly executed to abort a transaction. For example:

  exec tsf_send_message 'duplicate_customer', null, 1;
  rollback;
  return;

  When the code above is executed in a try-catch construction, you will directly enter its catch-part.

For Oracle, the following applies:

• 0 results in a dbms_output.put_line.
• 1 or NULL results in a raise_application_error that will abort the transaction.

For DB2, the following applies:

• The parameter Abort is ignored as a transaction and is always aborted when a message is sent.
• In order to still provide informational messages on DB2 in defaults and layouts, these logic concepts have an extra parameter v_message_text that can be set to show in an informational message.