MessageSetTextAndID

Edit online

Determines whether a task that encounters an error stops or continues.

Syntax

bool MessageSetTextAndID (String Message, String MessageID)

Parameters

Message: The message with index substitution indicators to be assigned to the MESSAGE variable.

MessageID: The ID to be assigned to the Message to enable client side translation. This parameter is optional. Smart parameters are supported for all parameters.

Returns

Always True.

Level

Any level.

Details

Adds a runtime MESSAGE and a MessageID variable to the bound object of the Document Hierarchy. The message is associated with the current DCO object and is displayed in the Datacap client verify panel when the current object has a failed status of 1. The MessageID allows the message to be displayed translated into the language used by the operator running the client verification panel.

Many actions in the ValidationsAndTextAdjustments library, such as IsFieldCurrency, IsFieldDate, etc., will automatically produce an appropriate translated message when the validation fails. MessageSetTextAndID allows for custom messages and the ability to create custom messages for custom validations that are not part of the Datacap base validations.

If the MessageID is provided, then the ID will be used to find the associated message in the "resources.json" file in the application's DCO directory. For example, if the application name is APT, then the DCO directory is named "dco_APT". The message can be translated and placed into the resources.json file in the DCO subdirectory based on the translated language. For example, dco_APT\de contains the translations in the German language and will be active when the application is run when the operating system is configured for the German locale. Note that the locale used for running rules can be different than the locale used by the end user.

The message replacement happens within the Datacap client application within the verification panel, it is not directly replaced when this action is run. It is while running the verification panel when the end user language is known and the appropriate translated messages and other key-value pairs are retrieved from the resources.json file by the client.

If the the MessageID is not provided, or if it is provided but the associated message cannot be found within the json file, then the text provided in the "Message" parameter will be displayed to the user. If the message is within the json file, it is recommended to duplicate the message in the call to this action as a safety measure to ensure a message is provided in the case where the message is not found.

The English json file in the DCO directory could have a message like this:

"message.V001":"Invoice Number must have a minimum length of 2 or be blank."

In the German json file in the \DE directory, the string can be translated like this:

"message.V001":"Die Rechnungsnummer muss eine Mindestlänge von 2 aufweisen oder leer sein."

If the current windows environment is configured to display the client in German, then the German version of the string will be displayed, otherwise the English version will be displayed from the English file. If the message is not found, then the message provided in the parameter will be displayed.

If a field has a failed status, by default the failed validation can be overridden by the verify operator to successfully submit the batch in spite of the failure. The override functionality can be controlled using the action SetIsOverridable.

This action is similar to the MessageSetText action. The difference is that MessageSetText does not allow the message to be translated and does not allow for substitution variables.

Example
MessageID("The field '{0}' has a value of '{1}'.", "M004")
MessageSetRuntimeParameter("@ID","Text","0")
MessageSetRuntimeParameter("@X","Text","1")

This example will look up the text in the json file that has the identifier "message.M004". If the message exists, it will obtain either the default English version from the _dco directory, or from the translated directory, if it exists and if the message is present for the current UI language. If the message with the ID "message.M004" is not found, then the message provided as the parameter will be displayed to the user.

The subsequent MessageSetRuntimeParameter actions will provide the values for the {} portions of the message. Assuming these actions are called on field "Total" and the value of that field is "1234", the final displayed message will be "The field 'Total' has a value of '1234'."

MESSAGE is a special DCO variable used to display verification failures to the verification operator. Refer the top-level help for more information about this variable and how to provide translated versions of text.