Referencing data in Notifications

When sending an email notification to a user or displaying a form feedback it is possible to include information from the executed process instance.

Basic Syntax

The basic syntax to include process instance information is:

{Binding VariableName}

Here the VariableName is a valid workflow variable. Examples are:

  • {Binding FormData["Text"] }
    Retrieve the content of the entry Text from the dictionary FormData. This could for example be a text field in a form used in the workflow

  • {Binding ProcessInstance.Created.Name}
    Get the display name of the person who has started this process instance.

In addition there is the possibility to use extra information in the context of an email notification.
This extra information is referenced with:

{Context Keyword}

The available Keywords are Name, EMail and ErrorMessage.
The Name and EMail keyword provide the respective attributes of the user receiving the particular notification.
The keyword ErrorMessage can be used in the context of a workflow failure notification only. In this situation ErrorMessage contains the error message that stopped the process instance from continuing.

Extended Syntax

While an information might be available in a workflow variable, it might not have a suitable format to be used in an email notification or form feedback. To avoid additional script activities for the sole purpose of data conversion, the extended syntax provides an option to specify desired conversions.

When using the extended syntax the VariableName or Keyword is followed by a comma and the specification of the conversion.

  • {Binding VariableName, Convert=ConverterSpecification}

  • {Context Keyword, Convert=ConverterSpecification}

A converter specification is the name of the converter with optional converter parameters in parenthesis. Multiple converters can be concatenated with a vertical bar ("pipe character").
Examples:

  • {Binding ProcessInstance.Created.Name, Convert=ToHTML}
    Ensure the user name is valid in a HTML context. No options are provided to the convert.

  • {Binding ProcessInstance.Created.Name, Convert=ToHTML()}
    The same as above.

  • {Binding ProcessInstance.Created.Name, Convert=ToHTML(True)}
    Same as above, but an option is provided to not convert spaces.

  • {Binding MyDate, Convert=ToTZ("Europe/Berlin") | Format("dd.mm.yyyy") }
    Concatenation of two converters. The first one takes a datetime object with UTC time zone and converts it to the time zone for Berlin. This time stamp is then formatted to a string comprising day, month and year.

When concatenating converters care has to be taken regarding the supported input and output types. So while it is ok to convert the time zone of a time stamp using ToTz(…​) first and convert the time using Format(…​) to a string next, it will not work the other way around.

Available Converters

No — prevent automated HTML conversion

The automated conversion to valid HTML might not be desired in some cases. For example, if the content of the workflow variable already contains HTML to be inserted in the notification.

Specifying this converter disables the automated HTML conversion.

Input Output Parameter

Object

Object

No parameters

ToHTML — manual HTML conversion

This converter also prevents the automatic HTML conversion and allows you to specify the conversion options to be used.

Input Output Parameter

String

String

  • Ignore white spaces - Bool (optional, default false):
    Do not convert spaces to

     

  • Ignore Line Breaks - Bool (optional, default false):
    Do not convert line breaks to

    <br />

  • Spaces for tab - Int (optional, default 4):
    Number of spaces to replace a tab character with

ToTZ — Time zone conversion for time stamps

Typically all workflow timestamps are set as time zone UTC. When being displayed in the GUI they are converted to the current time zone of the user. To perform this conversion also within notifications, one can use this converter.

When trying to specify a time zone one faces a number of issues. The first thought might be to provide simply the desired time zone abbreviation like UTC or CEST. Unfortunately these are not unique. For example AST denoted the Arabia Standard Time as well as the Atlantic Standard Time. Furthermore these two have different offsets from UTC. As an alternative one might consider country names, but this will fail for any country spanning across more than one time zone. As the IYOPRO Backend is executed on a windows server, one might consider the windows time zone names. However these are fairly long and one might not be sure which one to choose (e.g. W. Central Africa Standard Time versus South Africa Standard Time). Luckily the Unicode project provides a mapping of Region/City texts to windows time zones. See http://unicode.org/cldr/trac/browser/tags/release-30-0-3/common/supplemental/windowsZones.xml for details.
Input Output Parameter

Python datetime or C# DateTime

Python datetime

Conversion form UTC to another time zone:

  • Target location - String:
    Specification of the target location for the conversion e.g. "Europe/Berlin"

Conversion from one time zone to another

  • Source location - String:
    Specification of source location of the conversion e.g. "America/Los Angeles"

  • Target location - String
    Specification of the target location for the conversion e.g. "Europe/Berlin"

Format — Generic object formatting

This converter allows to use the C# string.Format(…​) capability to convert the data. See https://msdn.microsoft.com/de-DE/library/26etazsy(v=vs.110).aspx for details.

The C# string.Format(…​) method is capable of converting multiple values. This is achieved by referencing the values with {0:…​}, {1:…​} etc. In the context of this converter there is however only one value that will be converted. Therefore the converter adds the required “{0:” and “}” automatically.
Input Output Parameter

Object

String

  • Format string - String:
    Depends on the input. For example a float value can be converted to a string with two decimals and a separator for the thousands using the format string

    "#,###.00"

  • Culture - String (optional, default Invariant):
    Key for the culture to be used for the formatting e.g. "de-DE"

Custom conversions by python scripts

With this converter one can implement custom python scripts to perform the required conversion.
Here is an example for a converter to make a string upper case:

def UC(v):
   return unicode(v).upper()

Usage: {Binding Var, Convert=Script("ScriptFileName","UC")}

To allow the Script converter to access the required script file, the file has to be part of the workflow project.
This converter can’t be used in the feedback of a process instance start form, as there is no process instance created yet, when the feedback is displayed.
Input Output Parameter

Object

Object

  • Script file name - String:
    Name of the script file in the project containing the conversion function.

  • Function name - String:
    Name of the conversion function in the script file.