Use substitution variables

A request template can contain substitution variables that represent system-defined (Dimensions CM) and user-defined attributes. Variables can be single or multivalued.

About substitution

When you browse or print a request, Dimensions CM formats the request using the defined request template. The request is generated with the current attribute values replacing the substitution variables.

You can retrieve a request with the attribute values as they were at any previous point the request was actioned. To do this, use the command-line interface BC command with the /ACTION_NO option. For details, see the Command-Line Reference.

Single-valued Dimensions CM variables

The single-valued variables described in this section are built into Dimensions CM and may be included anywhere in a request template.

The following variables generally retain the same value throughout the life of the request:

Variable	Description
%ch_doc_id%	The request ID, which consists of the product ID, request type, and serial number. For example: PAYROLL_CR_1.
%product%	The ID of the product to which the request belongs.
%base_db%	The base database to which the request belongs.
%dsn%	The database connection string for the Dimensions CM server to which the request belongs.
%hostname%	The name of the machine hosting the Dimensions CM server to which the request belongs.
%type_head%	The description of the request type.
%create_date%	The date when the request was created.
%originator%	The originator's full name.
%department%	The originator's department.
%location%	The originator's site.
%telephone_no%	The originator's phone number.
%originator_id%	The originator's login ID.
%group%	The originator's user group.
%action_date%	The date the request was last actioned.

The following variables change frequently during the life of the request:

Variable	Description
%current_status%	The current lifecycle status of the request.
%lifecycle_phase%	The current phase of the request, which is determined by the current status and any applicable rules.
%action_number%	The number of the current (most recent) action.
%update_date%	The date the request was last updated.
%user_name%	The current user's full name.
%user_department%	The current user's department.
%user_location%	The current user's site.
%user_telephone_no%	The current user's phone number.
%user_group%	The current user's group.
%date%	The current date.
%time%	The current time.

Multivalued Dimensions CM variables

Unlike single-valued variables, multivalued variables are replaced by a list of entries, each of which may occupy several lines.

These multivalued variables are built into Dimensions CM and may be included anywhere in a request template.

For some multivalued variables, column variables are available that enable you to access information in a particular column. This column information can duplicate the information from the multivalued variables, or provide additional information.

Column variables give you greater control over variable formatting. For details, see Substitution variable syntax.

The following table provides descriptions of the multivalued Dimensions CM variables.

Multivalued variable	Description
%action_history%	Lists actions performed on the request. Each entry includes a short description of the action and the action number and date, plus information about the user performing the action (login name, full name, phone number, and department). Column variables: %ah_action_number%: The action number. %ah_date%: The action date in the following format: DD-MMM-YYYY HH:MM:SS. %ah_status%: The state to which this request was actioned. %ah_user_name%: The full username. %ah_user_phone%: The user's phone number. %ah_user_dept%: The user's department. %ah_action_note%: The action note. %ah_user_group%: The action history user group.
%audit_trail_failure%	Lists the details of the audit records for failed authentication attempts on a request.
%audit_trail_success%	Lists the details of the audit records for successful authentication attempts on a request.
%affected_baseline%	Lists baselines related to the request. Each entry includes details about the relationship, the current status of the baseline, and the user who created the relationship. Column variables: %bln_action_number%: Request action number when the relationship was created. %bln_baseline_id%: The related baseline specification. %bln_baseline_type%: The type of the baseline. %bln_brief_desc%: A brief description of the baseline. %bln_creation_method%: How the baseline was originally created: merged, revised, etc. %bln_relationship%: The name of the relationship. %bln_status%: The current status of the baseline. %bln_template%: The template name that was used to create the baseline. %bln_user%: The OS ID of the user who created the relationship. %bln_user_name%: The full username of the user who created the relationship.
%affected_item%	A list of all item revisions related to the request. Each entry includes the full item specification, item library file name, the action number when the relationship was created, the type of relationship, and the full name of the user who created the relationship. Column variables: %ai_action_number%: The action number. %ai_item_id%: The item's identity. %ai_user_name%: The full username. %ai_filename%: The item's file name. %ai_brief_desc%: The item's brief description.
%affected_part%	Lists all design parts related to the request. Each entry includes the full part specification, the design part category, the action number when the relationship was created, and the full name of the user who created the relationship. Column variables: %ap_action_number%: The action number. %ap_part_id%: The part's identity. %ap_user_name%: The full username. %ap_user%: The user. %ap_category%: The design part category. %ap_brief_desc%: The part's brief description.
%parent_doc%	Lists all higher-level requests to which this child request is related. Each entry includes the higher-level request ID, its title (attribute no. 1), the action number when the relationship was created, and the full name of the user who created the relationship. Column variables: %pd_relationship%: The relationship. %pd_doc_id%: The document's identity. %pd_product%: The document's owning product. %pd_status%: The status. %pd_user_name%: The full username. %pd_user%: The user. %pd_brief_desc%: The brief description.
%related_doc%	Lists all lower-level requests currently related to this parent request. Each entry includes the lower-level request ID, its title (attribute no. 1), the action number when the relationship was created, and the full name of the user who created the relationship. Column variables: %rd_action_number%: The action number. %rd_relationship%: The relationship. %rd_doc_id%: The document's identity. %rd_product%: The document's owning product. %rd_status%: The document's status. %rd_user_name%: The full username. %rd_user%: The user. %rd_brief_desc%: The document's brief description.
%update_history%	Lists all modifications other than actioning to the request. Each entry includes a short description of the modification, the action number and date, and information about the user making the modification (the login name, full name, phone, and department). Column variables: %uh_action_number%: The action number. %uh_date%: The date in the following format: DD-MMM-YYYY HH:MM:SS. %uh_user_name%: The full username. %uh_user%: The user. %uh_user_telephone_no%: The user's telephone number. %uh_user_dept%: The user's department. %uh_user_note%: The user's note. %uh_user_group%: The update history user group.
%attribute_update_history%	Lists attribute updates made to the request. Each entry includes the action number and date, information about the user making the modification (login name, full name, phone, and department), details of the attribute, and the value before and after the change. Column variables: %auh_action_number%: The request action number indicating when the update was done. %auh_user_name%: The full username of the user who did the update. %auh_date%: The date the update was done. %auh_user%: The OS name of the user who did the update. %auh_user_telephone_no%: The telephone number of the user who did the update. %auh_user_dept%: The department of the user who did the update. %auh_user_group%: The group of the user who did the update. %auh_user_note%: The user note of the user who did the update. %auh_attrno%: The attribute number for which the change was made. %auh_attr_variable%: The attribute variable for which the change was made. %auh_old_value%: The old attribute value. %auh_new_value%: The new attribute value.
%user_roles%	Lists the primary, secondary, and leader users for every role in the lifecycle.
%description%, %description_end%	The detailed description of the request. These substitution variables must be included on separate, successive lines in a request template.
%action%, %action_text%, %action_end%	These variables define a subtemplate for action descriptions. The subtemplate is part of the request template and contains a list of all recorded action descriptions. This subtemplate starts with the variable %action% and ends with the variable %action_end%, both on separate lines. Between these variables, the variable %action_text% must be included on a separate line, to define where the text of the action description is displayed. In the subtemplate, you can also use the column variables as well as other substitution variables, including user-defined variables. Note: This subtemplate is required for add action description operations to be recorded in the database, regardless of whether you want the data to show up in a browse template. The action descriptions are stored separately. If you add variables to the template, they do not affect the action descriptions previously entered (the action description substitution variables are not substituted). Column variables: %user_name%: The full name of the user entering the action description. %user_department%: The user's department. %user_location%: The user's site. %user_telephone_no%: The user's phone number. %date%: The date of the action description was entered. %time%: The time of the action description was entered.
%chdoc_attachments%	Lists files that are attached to the request.
%primary_user%	Lists users who currently have the request in their inbox and have the primary role capability.
%secondary_user%	Lists users who currently have the request in their inbox and have the secondary role capability.
%leader_user%	Lists users who currently have the request in their inbox and have the leader role capability.

User-defined variables

User-defined variables correspond to the user-defined attributes that are set up for a request type. You can define single-valued attributes, as well as multivalued attributes in list or table form.

For details about formatting multivalued attributes in tables, see Substitution variable syntax.

Use the following variables to signify a user-defined attribute:

User-defined variable	Description
%<variable-name>%	<variable-name> is the name of the user-defined attribute that you want to substitute.
%PRODUCT_<variable-name>%	<variable-name> is the name of the user-defined product attribute that you want to substitute.
%<variable-name>_PROMPT%	<variable-name> is the name of the user-defined attribute that you want to substitute. PROMPT indicates that you want to display the value of the attribute's Prompt field.
%<variable-name>_BLOCKNAME%	<Variable-name> is the name of the user-defined attribute that you want to substitute. BLOCKNAME indicates that you want to display the value of the attribute's block name. This substitution applies to block attributes only.

The following example demonstrates each type of variable. The first row uses the attributes' block name to label the table of attributes. The second row uses the attribute prompt names to label the column headings. The third row substitutes the actual values of the attributes.

%CUSTOMER_PROMPT% ----------------- %CUSTOMER% %CUSTOMERS_BLOCKNAME% --------------------- %PHONE_PROMPT% -------------- %PHONE% %PRIORITY_PROMPT% ----------------- %PRIORITY%

Block attributes

To define block attributes in a table, specify the block name as the table heading, as displayed in the earlier example (%CUSTOMERS_BLOCKNAME%). Each attribute you want to include in the table must have the same block name.

Next, define each attribute name and value as a column heading and column. Make sure that the order of the attributes follows the order of the columns specified in the block attribute, from left to right.

Note: If you update the block attribute name or values, you need to update the block in the template.

Display multivalued variables

To define a variable for a user-defined or system-defined multivalued attribute, you use the substitution variables or %<variable-name>%, as described earlier in this topic. The values of the attribute are displayed in a list, with each value on a new line.

For example:

Attribute name -------------- Value 1 Value 2 ... Value n

You can also display multivalued attributes as a table. For example:

Attr name 1 ------------- Value 1 Value 2 ... Value n Table Heading -------------- Attr name 2 ------------- first value second value ... nth value Attr name 3 ------------- alpha beta ... nu

Substitution variable syntax

When referencing Dimensions CM or user-defined variables, use substitution variable syntax for greater control over formatting.

The substitution variable syntax organizes the attributes into columns, as an alternative to applying manual formatting, such as spacing or tabs.

The syntax is:

%<variable-name>:<c>:<w>:<s>%

where:

Option	Description
<c>	An integer specifying where the column starts from the left of the template, in characters.
<w>	An integer specifying the column width in characters. Enter a positive number to add padding to the right of the field. This ensures that if data doesn't fill the field, and the text written to the right of the field always starts at the next column position. To eliminate padding, specify the column width as a negative number. Text following this field is then displayed in the next column following the last character of data.
<s>	A single character (uppercase or lowercase) that specifies the column alignment. The available characters are: L: Left-justified. Data is aligned with the left-hand edge of the column. Excess data is truncated at the column boundary. R: Right-justified. Data is aligned with the right-hand edge of the column. Excess data is truncated at the right-hand column boundary. C: Centered. Data is centered within the column. Excess data is truncated at the right-hand column boundary. W: Wrapped. Data is aligned with the left-hand edge of the column. Excess data is wrapped onto successive lines.

Option

Description

<c>

An integer specifying where the column starts from the left of the template, in characters.

<w>

An integer specifying the column width in characters. Enter a positive number to add padding to the right of the field. This ensures that if data doesn't fill the field, and the text written to the right of the field always starts at the next column position.

To eliminate padding, specify the column width as a negative number. Text following this field is then displayed in the next column following the last character of data.

<s>

A single character (uppercase or lowercase) that specifies the column alignment. The available characters are:

L: Left-justified. Data is aligned with the left-hand edge of the column. Excess data is truncated at the column boundary.
R: Right-justified. Data is aligned with the right-hand edge of the column. Excess data is truncated at the right-hand column boundary.
C: Centered. Data is centered within the column. Excess data is truncated at the right-hand column boundary.
W: Wrapped. Data is aligned with the left-hand edge of the column. Excess data is wrapped onto successive lines.

For example:

%CUSTOMER_PROMPT:9:16:L%
------------------------
%CUSTOMER:9:16:L%

%CUSTOMERS_BLOCKNAME%

---------------------

%PHONE_PROMPT:27:7:L%
---------------------
%PHONE:27:7:R%

%PRIORITY_PROMPT:40:7:L%
------------------------
%PRIORITY:40:7:C%

Syntax guidelines:

You must include either all or none of the fields in the substitution variable syntax (c:w:s).
Generally, make the starting column equal to or greater than the previous column's starting column value plus its width. This ensures that the columns of data are separated by whitespace.
We do not recommend using substitution variable syntax (%<variable-name>:<c>:<w>:<s>%) and plain substitution variables (%<variable-name>%) on the same line. This can lead to unpredictable formatting results.
You can use a mixture of both variable types on different lines without any problem.
Substitution variable syntax is supported only for plain text substitution.
Substitution variable syntax is not supported for proportional fonts because positions are determined by the number of characters you specify.
Avoid using tab characters or inserting text to the left or right of substitution variable syntax. These actions may lead to unpredictable formatting results.