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:

` if( exists(<replacement_parameter>) ) \\optional {  writeln(<replacement_parameter>); } `

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 the technical names lastName and firstName, you can refer to them from an e-mail template using the ctxt.lastName and ctxt.firstName strings.

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 structure with the technical name personalData as a context parameter, and this structure has two subelements with the technical names lastName and firstName, you can refer to them from an e-mail template using the following strings: ctxt.personalData.lastName and ctxt.personalData.firstName.

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 &#46.

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 &#45.

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&#46Data.first&#46&#45Name.

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   `write(ctxt.lastName) set(ctxt.lastName, "Smith"); write(ctxt.lastName)`
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. `clear(ctxt.lastName)`

There are some restrictions when using the scripting language to access context parameters:

■       If the List option is specified for the context parameter, it cannot 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 nontrivial string representation should be avoided.

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

sy.currenttime is replaced by the date when the callable object using the specified e-mail template has been completed.

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.

role.initiator.firstname is replaced by the first name of the process initiator.

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.