Replacements
Definition
A replacement is a parameter that you can enter in a MIME template at design time. This parameter is 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 (GP). Using the scripting language, you can define replacements for the context parameters of the callable object using the e-mail template provided, 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 at the beginning of the e-mail, and at runtime the system enters 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 (.).
To enable replacement of the parameters, you must use the following syntax:
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 context parameter type is structure, the sub elements of the structure are also referenced by the period (.) separator character.
If the callable object has a context parameter that has a period (. ) in its technical name, the period is referenced in the e-mail template as . .
If the callable object has a context parameter that has a hyphen (- ) in its technical name, the hyphen is referenced in the e-mail template as - .
If the callable object has a structure parameter with a technical name str.Data and a subelement in the structure that has a technical name first.last-Name , you can refer to the subelement in the e-mail template with the string ctxt.str.Data.first.-Name .
This is required for the prevention of errors arising from having the period acting as a separator between the structure and its subelements in the script language and at the same time using it in technical names of parameters. The same applies when using a hyphen acting as a separator of the parameters in the script language and at the same time using it in technical names of parameters.
This holds true for all callable object types that have both input and output parameters. If an input and an output parameter have the same technical names, the GP framework references to the value of the output parameter.
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. You should use the clear function instead of the delete function in GP. |
|
clear(contextname) |
Removes the context parameter. |
Accessing Built-In Parameters
The built-in parameters are available with the prefix sy . 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 current GP process |
|
workitemurl |
The URL of the current work item in your current GP process |
Accessing Built-In Process Roles
The GP process roles are available with the prefix role .
GP Process Roles
| Syntax | Description |
|---|---|
|
initiator |
The initiator of the current GP process |
|
overseer |
The overseer[s] of the current GP process |
|
recipient |
The recipient[s] of the e-mail generated from the e-mail template |
The following parameters can be accessed from the roles above:
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.
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> </html> |
At runtime, the system replaces the parameters with the last name of the applicant.