Replacements 
Definition
A replacement is a parameter that you can enter in a MIME template at design time, and gets replaced by a custom value at runtime.
Use
You can use replacements when you want to personalize the e-mails that are sent by Guided Procedures. Using the scripting language, you can define replacements for the context parameters of the callable object using the given e-mail template, the built-in parameters that give system information and the built-in process roles. For example, if you want to address the recipient directly in the e-mail, you can enter a replacement in the beginning of the e-mail, and at runtime the system will enter the relevant name there.
Structure
To access the context parameters, the built-in parameters and the built-in process roles, you have to add prefixes to the parameter names.
The following prefixes are supported:
Prefixes
Syntax |
Description |
ctxt |
Prefix used to access context parameters |
sy |
Prefix used to access built-in parameters |
role |
Prefix used to access GP built-in roles |
The separator character for prefixes is the period (.).
Accessing Context Parameters
The context parameters are available with the ctxt prefix. The technical name of the parameter appended to the prefix gives the corresponding replacement.
If the callable object has two context parameters with technical names: lastNameand firstName, you can refer to them from an e-mail template by the ctxt.lastName and ctxt.firstName strings.
If the context parameter type is structure, the sub-elements of the structure are referenced by the period (.) separator character, as well.
If the callable object has as a context parameter, a structure with the technical name personalData and the structure has two sub-elements with technical names: lastName and firstName, you can refer to them from an e-mail template by the following strings: ctxt.personalData.lastName and ctxt.personalData.firstName.
Context Handling Functions
Syntax |
Description |
|
set(contextname, value) |
Sets the value of a context parameter
|
|
append(contextname, value) |
Reserved, but not used by GP |
|
delete(contextname) |
Removes the context parameter. It is recommended to use the clear function instead of the delete in GP. |
|
clear(contextname) |
Removes the context parameter.
|
There are some restrictions when using the scripting language to access context parameters:
● If the List option is specified for the context parameter, it could not be accessed in the context of an e-mail template.
● The technical names of the context parameters must consist of alphanumeric characters.
● The accessing types with non-trivial string representation should be avoided.
Accessing Built-In Parameters
The built-in parameters are available with the sy prefix. The built-in parameter appended to the prefix gives the corresponding replacement.
Built-In Parameters
Syntax |
Description |
currenttime |
The current time |
processid |
The process identifier of the running GP process |
workitemurl |
The URL of the current work item in your running GP process |
sy.currenttime is replaced by the date when the action, callable object using the given e-mail template, has been completed.
Accessing Built-In Process Roles
The GP process roles are available with the role prefix.
GP Process Roles
Syntax |
Description |
initiator |
The initiator of the running GP process |
overseer |
The overseer[s] of the running GP process |
recipient |
The recipient[s] of the e-mail generated from the e-mail template |
From the roles above the following parameters can be accessed:
Parameters
Syntax |
Description |
firstname |
The first name of the user |
lastname |
The last name of the user |
accountname |
The account name (identifier) of the user |
The parameter appended to the built-in process role appended to the prefix gives the corresponding replacement.
role.initiator.firstname is replaced by the first name of the process initiator.
Integration
To enable the replacement of the parameters, you must use the following syntax.
`
if( exists(<replacement_parameter>) ) \\optional
{
writeln(<replacement_parameter>);
}
`
Example
You can personalize an e-mail that is sent to an approved applicant as follows. It is assumed that the applicant has initiated the process – for example, by completing an application form.
<html>
<head> <title>Approval</title> </head>
<body>
<p> Dear Mr/Ms ` { writeln (role.initiator.lastname) `, </p> <p>Your application has been accepted.</p> <p>Best regards,</p> <p><i>HR Manager</i></p>
</body> |
At runtime the system replaces the parameters with the last name of the applicant.