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 both messages that are sent from functionality (code templates) and messages that are caused by the database, such as constraints and checks.

Example of a message as it may appear in an end product.

Modeling messages

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. The Message location indicates 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. Use these messages only in code, never as confirmation messages in a task or as messages in a process action.
   • None (suppress) - suppresses database messages.
   • Debug:
     • Windows GUI and Web GUI: 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. Universal Windows GUI To add a sound to your message, upload an Audio file. The file will be played upon receiving the message. The allowed extensions are .wav and .mp3. You can add sound to popups as well as to panel messages.

Form to create a message

Message options

menu User interface > Messages > tab Message options

It is possible to add options to a message. These options represent the choices a user can make when presented with the message when used in a process flow. For example, this configuration in the Software Factory:

will result in this dialog in the GUI:

An affirmative message option will be given a unique status code of zero or higher, while a negative message option will be given a unique negative status code. These response types and corresponding status codes are directly related to the green and red arrows in the process flow. In some cases, it might be necessary to have multiple affirmative and/or multiple negative message options which have different effects on the continuation of the process flow. To achieve this, the Status code value of a message option will be passed as the Status code output parameter of the process action.

Icons are optional and the sequence number of the message option (#) determines the order of the buttons on the dialog.

Translations

menu User interface > Messages > tab Translations

In the Translations tab, a translation can be specified in which parameters are defined with 0, 1 etcetera.

Modifying database messages using regular expressions

menu User interface > Messages > tab Form

To translate or suppress a database message using a regular expression:

1. Deselect the Hide generated prefilter.

Now, you can also see the existing generated messages containing a regular expression. These messages can be a good starting point for translation.

1. Select a database message that includes a regular expression.

2. Copy this message into a new message.

3. Adjust the message.

4. Adjust the Message location if desired. To suppress the message, select None (suppress).

5. Optionally, you can specify a translation in which parameters are defined.

Task confirmation message

You can choose a confirmation message to show up when executing 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 your end product:

Message with a parameter in the end product

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.