Create Custom Log and Text Messages

Introduction

This document describes how developers can use WebsydianExpress log and text messages in their own business processes.

This offers two things:

1. Writing custom messages to the WebsydianExpress Message Log

2. Retrieving texts based on the language of the language specified for the current session - while inserting parameters in the texts using a replacement process.

Creating custom log messages

Just as the WebsydianExpress runtime can write messages to the message log, Plex developers also have the option to let their own business processes write custom messages to the log.

The messages are stored in the same files as the system messages and they are shown as part of the normal message log business process in the administration interface.

You can translate the base texts for each message type. This translated message text will be used shown in the message log if the session showing the log has the same language as the translation.

Specify inheritance

For each type of message you want to be able to write to the message log, you must create a function that inherits from the Abstract.CreateLogMessage function.

When the function MyCreateMessage is called, a message will be written to the message log.

The content of the message is controlled as described below:

Specify message text

You specify the message that will be written to the message log by entering the text of the message in the source code MyCreateMessage.MessageText.

Specify parameters for the text

In many cases, the information you want to write to the message log will be partly fixed text, which will be the same for all messages having the same type, and partly parameters that can be different from call to call.

As an example: If you want to be able to report that there is a session, where no user is logged in (for instance if your business process needs to register the user who performs a specific action).

In this case, you might want to report the identification of the session.

To add the session as a parameter, do the following:

1. Add the session surrogate as an input field to the function inheriting from Abstract.CreateLogMessage:

Please note that the input parameter must be placed in the input variable named "Input" to be handled by the function.

When you call the function (to create a message), you just specify the current session surrogate as the value for the parameter.

2. Specify where in the text you want to enter the parameter

The replacement is specified in the same way as in the "normal" Plex messages - in this case, the message text might be:

The session &(1:) has no user specified.

This text is specified in the source code MyCreateMessage.MessageText.

If you have more than one parameter - the replacements are &(2:), &(3:) - and so forth.

The sequence of the FNC input FLD triples specifies the sequence used by the replacement process.

Specify the identification of the message type

Each CreateLogMessage function will correspond to a message type. The identification of the message type is the implementation name of the function.

The runtime message type identifications all start with WSE - followed by a number. To avoid problems with the CreateLogMessage functions, you should not use names with this scheme.

Specify severity

To provide an indication of the severity of the message, you can specify one of 4 different severity levels for your messages.

1. Alarm

2. Error

3. Warning

4. Informative

These levels can be used to specify which message to show in the message log.

Currently the runtime does not write any messages with the Alarm severity.

You specify the severity for the message by specifying a function option (One of: WSYAPI/Alarm, WSYAPI/Error, WSYAPI/Warning, WSYAPI/Informative).

The default is Error - so if no option is specified, this is the severity that will be used.

So, if the message should have the severity "Warning" - you specify this the following way:

Specify a category

To make it possible to set up a filter in the message log so that only message from a specific part of the application is shown, you can specify a category for the message.

You do this by entering the name of the category in the _MessageCategory source code scoped by the function inheriting from the Abstract.CreateLogMessage function.

The source code is pre-filled with the text "Application". This means that if you do not change this text, the messages you create will belong to this category.

The runtime uses the categories "System" and "API" - to avoid confusion you should not use these values.

The best way to ensure that the categories you specify for your message are consistent is to create an abstract CreateLogMessage function for each category. For each of these functions, specify the category in the source code. You should always inherit from these functions instead of from the WSYAPI/Abstract.CreateLogMessage function.

So if you for example want to have two different categories: Extranet and Intranet, you can do this as follows:

Specify the categories in the source codes:

MyAbstractIntranetMessage._MessageCategory = Intranet

MyAbstractExtranetMessage._MessageCategory = Extranet

To create a message for the intranet part of your application - specify the following inheritance:

Creating custom text messages

In some cases the business processes need to create and show messages to the user, without writing these messages to the message log.

This in itself is not a problem - just create the text (e.g. using a format message) and write it to the page.

However, if the texts are to be dependent on the language specified for the session, this is not quite as simple. To provide assistance for the developers for this task, it is possible to create texts that will be handled by the same translation as the texts generated by the runtime.

Apart from adding language support to the texts, you can also specify parameters and where you want the values specified for these parameters to be placed in the text.

This section describes how the developers can create their own texts.

Specify inheritance

For each type of message you want to be able to write to the message log, you must create a function that inherits from the Abstract.CreateTextMessage function.

Specify the base text

The base text you want the function to return is entered in the source code MyCreateText.MessageText.

Specifying parameters for the text

In many cases, the text you want the function to return will consist of two parts - a static text, which will be the same for all messages having the same type - and parameters that can be different from call to call.

If you for instance want to inform a user that the entered customer identification is wrong, you can do this in the following manner:

1. Add the customer identification as an input field to the function inheriting from Abstract.CreateTextMessage:

Please note that the input parameter must be placed in the input variable named "Input" to be handled by the function.

2. Specify where in the text you want to enter the parameter

The replacement is specified in the same way as in the "normal" Plex messages - in this case, the message text might be:

The entered customer &(1:) does not exist.

This text is specified in the source code MyCreateText.MessageText.

If you have more than one parameter - the replacements are &(2:), &(3:) - and so forth.

The sequence of the FNC input FLD triples specifies the sequence used by the replacement process.

Specify the identification of the message type

Each CreateTextMessage function will correspond to a message type. The identification of the message type is the implementation name of the function.

The runtime message type identifications all start with WST - followed by a number. To avoid problems with the CreateTextMessage functions, you should not use names with this scheme.

Specifying a category for the text

You have the option to specify a category for your texts. This is mostly meant as aid to the maintenance of message types.

You do this by entering the name of the category in the _MessageCategory source code scoped by the function inheriting from the Abstract.CreateTextMessage function.

The source code is pre-filled with the text "Text". This means that if you do not change this text, the messages you create will belong to this category.

The runtime uses the category "System". To avoid confusion you should not use this value.

The best way to ensure that the categories you specify are applied to your message is to create an abstract CreateTextMessage function for each category, where you specify the category in the source code - and than always inherit from these functions instead of from the WSYAPI/Abstract.CreateTextMessage function.

So if you for example want to have two different categories: Extranet and Intranet, you can do this as follows:

Specify the categories in the source codes:

MyAbstractIntranetText._MessageCategory = Intranet

MyAbstractExtranetText._MessageCategory = Extranet

So to create a text used for the intranet part of your application - specify the following inheritance:

Handling Message Types

Each function that inherits from either WSYAPI/Abstract.CreateLogMessage or WSYAPI/Abstract.CreateTextMessage corresponds to a message type. The message type is created the first time the function is called and is identified by the implementation name of the function.

The message type contains information about whether it is a CreateLogMessage or a CreateTextMessage function that created it, the text that was written in the MessageText source code when the record was created, the category specified in the _MessageCategory source code when the record was created.

All of these data are created automatically when the CreateLogMessage or the CreateText Message function is called.

For the messages and texts used by the system, the message type table is populated as part of the installation of WebsydianExpress.

You can use the message type administration process to alter the base texts for messages/texts, translate the texts (please note that as translation is local to a specific site, the translation will only be used in the site in which it is created), and alter severity or category.

Changing Existing Message Types

In some cases you would like to change an existing message type. This might be because you want to change the text of the message or because you want to add or remove parameters from the message.

If a message of the type you want to change already has been written to the message log, a corresponding message type record will have been created. This record contains the original text that was defined for the message type. This record will used by the message log for showing the messages that belong to the message type.

This means that changing the text in the MessageText sourcecode will not change the text shown in the message log. However, we still recommend that you do change the text, as it then will be correct if you redeploy the message on a new installation.

You can change the text of the existing message type by using the menu item Language Support→Texts and Messages in the administration interface. Changing the "Text" field changes the text that will be shown in the log.

If you want to change the severity of the message type, this can also be done in this function.

If you want to add and remove parameters, you must do so on the function inheriting from Abstract.CreateLogMessage, re-generate and build the function and all the functions calling it. After this you must change the text as described above, so that replacement markers are added if you have added parameters, and removed if you have removed parameters.

Please note that the changes to the text/severity of the message type also will be shown for all the existing messages in the log.

If this is not acceptable, you must create a new message function (or change the implementation name of the existing function) - in this way a new message type will be created when the new function is called - so that the old messages still use the old text, while all new messages use the new one.

The texts created using functions that inherit from Abstract.CreateTextMessage have the same behavior as described for the log messages - and you change them in exactly the same manner.