STEM help

8.6.4 Token-replacement keywords and intended usage

The table below describes each of the available token-replacement keywords and its intended usage. If any cell has content that starts with the tag value but doesn’t match any of the expected formats, or if a value fails to be retrieved for any reason to fill the cell, the cell will be made empty and an explanatory message will be logged to the configured logs folder for the web service.

The syntax is evidently rather intricate as it essentially embeds the same kind of information as you might be familiar with providing to the StemGetResult() and StemGetPeriod() worksheet functions in Excel after exporting results to Excel in the desktop environment. Therefore you may wish to use formulae in Excel to construct the necessary token-replacement strings from scenario, element and result identifiers entered in adjacent cells to avoid having to manipulate this syntax directly too often!

For example, if you have entered scenario, element and result identifiers in cells B8, C8 and D8, then you could use the formula shown below in cell E8 to construct the required token to access the first result, and then just use $STEM$ next for the adjacent cells:

Please note the multiplicity of double-quote characters. The use of two together is an escape sequence which gets a literal double quote into the resulting token, and then the other (single) double quotes are used to de-limit the separate and static string chunks from those concatenated from cells B8, C8 and D8. Try it: you know it makes sense!

<tag> input <element> <field> <period>
$STEM$ input "My Resource" UnitCapacity
$STEM$ input "My Resource" SomeInterpSeries Y4
The value of the specified input when the report was generated.
The period argument is optional. If present, it selects the period of an interpolated series input that should have a value returned for it. If omitted for an interpolated series input, the first value in the interpolated series will be returned. The period may be the name of a period (e.g., Y4 or Q3 2010) or it may be the index of a period (e.g., 5).
Note that the input needn’t be one of those made available in the Web GUI as long as it exists in the DTL file for the model.
<tag> result <scenario> <element> <result> <consolidation mode> <period>
$STEM$ result "Option A/None" Resource5 "Capital Expenditure"
$STEM$ result "" "My Service" Revenue Quarter "Q3 2010"
$STEM$ result "" Service2 Revenue "" Y5
The value of the specified result in the specified scenario. To refer to the working model, pass an empty string for the scenario name.
The consolidation mode argument is optional unless the period argument is supplied, in which case it must be given. Valid values are Month, Quarter and Year. If omitted, results will not be consolidated (equivalent to ‘Month’).
The period argument is optional. If present, the result for the specified period will be returned. If omitted, the result for the first period of the model’s run period will be returned.
<tag> period <scenario> <consolidation mode> <period>
$STEM$ period "Option A/None"
$STEM$ period "" Quarter "Q3 2010"
A period label for the specified scenario. To refer to the working model, pass an empty string for the scenario name.
The consolidation mode argument is optional unless the period argument is supplied, in which case it must be given. Valid values are Month, Quarter and Year. If omitted, periods will not be consolidated (equivalent to ‘Month’).
The period argument is optional. If present, the label for the specified period will be returned. If omitted, the label for the first period of the model’s run period will be returned.
<tag> next
$STEM$ next
If the cell immediately to the left of this cell contains an ‘input’, ‘result’, ‘period’ or ‘next’ instruction, this cell will be given the value or label from the subsequent period for the same input or result if values or labels remain to be displayed. In all other cases, this format is invalid.
<input or result> [ <string 1> <string 2> … ]
$STEM$ next [ "A message" "Another" ]
$STEM$ result "" WMResource "Installed Units" Year Y0 ["None" "One" "Two" "Many" "Lots"]
$STEM$ input "My Resource" UnitCapacity ["A string with ""Quotes"" in it." "String 2" ]
Retrieves a value using the initial instruction, but uses that value to select a string from a list and places the selected string in the cell rather than the retrieved value.
The value is rounded to the nearest integer and then used as an index into the given list of strings. If it is less than zero, the first string will be returned. If it is equal to or greater than the length of the list of strings, the last string will be returned.
Each of the strings must be enclosed in double quotes. There must be at least one whitespace character between each string. A literal double-quote character can be included in an output string (‘escaped’) by placing two such characters next to each other with no space between them.
You can have as many strings as you like in the list, within any cell content limits imposed by Excel.

Token-replacement keywords for exported reports in Excel

 

© Implied Logic Limited