Use tokens

PPM uses variables to facilitate the creation of general objects that can be used in a variety of contexts. These variables are called tokens.

Types of tokens

PPM uses the following types of tokens:

  • Standard tokens come with the product.

  • Custom tokens are generated to suit specific needs.

    You can reference the fields of the following entities as custom tokens:

    • Object types

    • Request types and request header types

    • Report types

    • User data

    • Workflow parameters

Many standard tokens are available to provide information related to the system. For example, PPM has a token that represents the users currently logged onto the system.

Back to top

Where to use tokens

You can use tokens in the following entity windows:

  • Object type commands

  • Request type commands

  • Validation commands and SQL statements

  • Report type commands

  • Executions and notifications for a workflow

  • Workflow step commands

  • Notifications in a report submissions

  • Special command commands

  • Notifications for tasks and time management

  • Notes for request details

Back to top

Token evaluation

Tokens are evaluated at the point when PPM must know their context-specific values. At the time of evaluation, the token evaluation engine gathers information from the current context and tries to derive the value for the token. Values can only be derived for specific, known contexts. The current context is defined as the current package, package line, request, work plan, workflow step, or source and destination environments.

The token evaluation engine takes as many passes as necessary to evaluate all tokens, so one token can be nested within another token. During each pass, if the evaluation engine finds a valid token, it replaces that token with its derived value. Invalid tokens are ignored. For example, if the token name is misspelled or no context is available.

For example, an object type command has the following Bourne-shell script segment as one of its command steps:

if [ ! -f [PKGL.P.P_SUB_PATH]/[PKGL.P.P_BASE_FILENAME].fmx ];
then exit 1; fi

When the command is executed, [PKGL.P.P_SUB_PATH] = Forms and [PKGL.P.P_BASE_FILENAME] = obj_maint. After token evaluation, this command step reduces to:

if [ ! -f Forms/obj_maint.fmx ]; then exit 1; fi

As another example, a user data field is generated for all users called MANAGER. You could find the email address of the manager of the person who generated a request by using the following token:

[USR="[USR="[REQ.CREATED_BY_USERNAME]".VUD.MANAGER]".EMAIL_ADDRESS]

The token evaluation engine first evaluates the innermost token ([REQ.CREATED_BY_USERNAME]), then the next token ([USR="<name>".VUD.MANAGER]), and finally evaluates the outermost token, which provides the email address.

Tokens are evaluated at different points based on the token type. Tokens used in object type parameters and commands are evaluated during command execution. Tokens in a validation SQL statement are evaluated just before that statement is executed (such as generating a new package line). Tokens in an email notification are evaluated when a notification is generated.

Back to top

About Token Builder

From each of the entity windows listed in Where to use tokens, you can open the Token Builder window (Figure 4-2. Token Builder window) to create a token. The tokens available in the token builder are limited to those that you can build for that entity. For example, if you open the token builder from the Request Type Workbench, package tokens are excluded.

Figure 4-2. Token Builder window

The folders displayed in the left pane of the Token Builder window contain groups of tokens that correspond to entities defined in PPM. For instance, the Packages folder contains tokens that reference various package attributes. If you select the Packages folder, the available package tokens are listed in the right pane.

Some entities (folders) have sub-entities (sub-folders) that can be referenced by tokens. To view a list of sub-entities for an entity, click the plus character (+) next to the entity. Each sub-entity also has tokens, and you can reference any sub-entity tokens, as well as the parent entity tokens. For example, the package line entity is a sub-entity of the package entity.

As you select entity folders and corresponding tokens in the list, a character string is constructed in the Token field at the bottom of the Token Builder window. This is the formatted string used to reference the token. You can either copy and paste the character string, or type it where it is required.

For information on using the token builder, see Use the Token Builder.

Back to top

See also: