Metric Field Codes with Options
To create a report showing the system names of all current metrics, use Accolade Office Extensions or Accolade Online Reporting to create a report that includes the Metric Display Name and Metric System Name columns from the Metric Definitions subject.
Use metric field codes to do the following:
- Display a metric's value.
- Display other data related to the metric.
- Update a metric value (only in the case of a Long String type metric in a Word document that is not a related document).
The basic pattern of a metric field code is the same as for other codes: {*source:name*}. For metric codes, the source is always "Metric", and the name is the system name of the metric. For example, {*METRIC:TCost*} displays the value of the metric whose system name is "TCost".
Note: Because a metric code uses the metric's system name, if a metric's system name changes, you must update any templates or reports that contain a code for that metric.
Important! This does not apply to MetricRichText tokens.
Option Patterns
Metric codes have optional additions to the basic pattern. Options can:
- Make the code display something other than the metric value.
- Change how the value is displayed.
- Enable the code to update a metric value in addition to displaying it. This capability is limited to codes for Long String type metrics in Word documents that are not related documents.
If options are added, they are listed after the code's name. The pattern for a metric code with options is: {*METRIC:name option*}. The name and options, if any, are separated by a space.
Example
{*METRIC:NPV #DisplayName*} would show the NPV metric's display name rather than the metric value. And {*METRIC:NPV #ProjectCurrency #Format2*} would display the value in the project currency using that currency's second format.
There are two types of options, primary and secondary:
- Primary Option - Identifies the data that replaces the value, so a code can contain only one primary option.
- Secondary Option - Specifies how the field code behaves, so a code can contain one or more secondary options either in addition to or without a primary.
The options in the table below are intended for use in ordinary, non-updating codes while the options in the second table are for codes that update Long String metrics in Word. Options in one table should not be combined in the same code with options from the other table.
Metric Code Options
Some options in the following table can be used with all types of metrics, while others should be used only in certain types, as shown in the table.
| Option | Option Type | Description |
|---|---|---|
| All Metric Types | ||
| #DisplayName | Primary | Displays the metric's display name. |
| #Description | Primary | Displays the metric's description. |
| #DataType | Primary | Displays the metrics data type. |
| #OnceOnly | Secondary | The field refreshes only once, then the persisting bookmark is deleted. Add a code with this option to a Smart Excel cell to display the metric value once, after which the same cell updates the metric. |
| Only List Metrics | ||
| #ListItems_Pipe | Primary | Displays the metric's list items in a pipe-delimited string. |
| #ListItems_Comma | Primary | Displays the metric's list items in a comma-delimited string. |
| #ListItems_CR | Primary | Displays the metric's list items in a carriage-return-separated list. |
| #ListItems_Table | Primary | Displays the metric's list items in a table format. |
| Only Currency Metrics | ||
| #ProjectCurrency | Primary | The metric's value is given in the project currency. |
| #CorporateCurrency | Primary | The metric's value is given in the corporate currency. |
| #Format1 | Secondary | The metric value is displayed using the first number format listed in the Currency reference table. |
| #Format2 | Secondary | The metric value is displayed using the second number format listed in the Currency reference table. |
Long String Metrics Update Options
A metric field for a Long String type metric can update the metric's values when the code is inserted in a Word document. The metric is updated in Accolade when the document is saved back to Accolade. If the document version is created as a link to an external document or web page, the metrics does not update when the document is published.
Important! Long string metric field codes apply only to Word documents and are not applicable in other Microsoft applications. This feature is not supported for related documents.
This kind of code has three options. These options cannot be used in non-updating codes, and the options listed in the table above should not be added to updating codes.
| Option | Option Type | Description |
|---|---|---|
| #Updateable | Secondary | This metric can be updated by the code if this option is present. |
| #DefaultValue=(value) | Secondary | Displays the text following "=" when the metric is empty in Accolade. If the # character is part of the value, enter "##" in the template.
Important! If there is no default value, a string of spaces is inserted into the field. To edit the field, delete the spaces before entering text. |
| #MaxLen=(value) | Secondary | Sets a maximum length, in characters, for the field. The value must be a number under 2000. If this option is not used in the code, the metric field has a size limit of 2000 characters. |
Example
For a Long String type metric named BusiCase:
- The code {*Metric:BusiCase #Updateable*} allows the metric to be updated.
- The code {*Metric:BusiCase #Updateable #MaxLen=500 #DefaultValue=Enter the business case*}:
- Would allow the metric to be updated.
- Would allow the user to enter up to 500 characters in the field.
- Would display the text "Enter the business case" if the metric was empty when the document was opened.