XRM Tokens

XRM Tokens provide a generic method to substitute static texts with information from Microsoft Dataverse or Dynamics 365.

This is a XrmToolBox tool to test and learn how XRM Tokens is used. Try it!

Substitutions always start within the context of a record in the database, the source record. Based on the token, information from the source record and its relationships is used to substitute the token with dynamic information.

The source code for XRM Tokens is maintained in a C# Shared Project, which can be included in Plugins, Custom APIs, Custom Workflow Activities, XrmToolBox tools, or any other kind of SDK client.


References

Attribute tokensSimple way to get readable attribute, and linked references.
Raw tokensGetting the raw values, numbers, ids, etc.
Expand tokensGet a list of children records.
System tokensA number of like date and user etc.
Token formattingLot of feature to change values.
If-else statementsIf-Else for attribute values compare to anything.
SequencesA simple way of numbering a list of any records.

Code πŸ”—

XRM Tokens is maintained on GitHub:
https://github.com/rappen/Rappen.XTB.Helper

XrmSubstituter has all details:
https://github.com/rappen/Rappen.XTB.Helper/blob/main/XrmSubstituter.cs


Attribute tokens πŸ”—

Attributes on the source record are referred to by using simple curly braces around the attribute logical name. Example:

First name is {firstname}.

Information from related parent records can be referenced with dot notation. Example:

Parent account email is {parentaccoundid.emailaddress1}.

This method can be used recursively. Example:

Parent account owner BU name is {parentaccoundid.ownerid.businessunitid.name}.

Raw tokens πŸ”—

Attributes can always get as “raw” values. If you only do as above it will always get a “nice” readable result. Example was to get raw value:

Credit Limit is money "{creditlimit}" and value to count {creditlimit|<value>}
Parent Contant is "{primarycontactid}" and raw id {primarycontactid|<value>}

Example result:

Credit Limit is money "200,00 kr" and value to count 200,0000
Parent Contant is "Tin Tin" and raw id c45ad2cd-4257-ea11-a811-000d3a4aa8e7

Expand tokens πŸ”—

XRM Tokens can concatenate information from related child records in 1:M relationships, and even through M:M relationships.

1:M relationships are expanded using the following format:

<expand|childtable|lookup|childtoken|order|separator|distinct|activeonly|maxcount>

Definition of parameters:

  • childtable – logical name of the child table of the 1:M relationship (required)
  • lookup – logical name of the column on the child table that contains the lookup value to the parent (required)
  • childtoken – any valid XRM Token, this is applied to each child record retrieved (required)
  • order – comma separated logical names to sort the child records by, may be suffixed by /asc or /desc to specify direction (optional)
  • separator – string sequence to separate the values of each retrieved child record (optional)
  • distinct – set to true if only one unique occurrence of the child record values shall be included (optional)
  • activeonly – set to false to include inactive child records (optional)
  • maxcount – specify max number of child records to return (optional)

Examples from an account:

Active case types: <expand|incident|customerid|{casetypecode}||\n|true>
Contact first names: <expand|contact|parentaccountid|{firstname}|lastname,firstname|, |false|true|100>

Expanding over M:M relationship:

Marketing lists: <expand|listmember|entityid|{listid.listname}||, ||false>

Sample result of the text above:
Marketing lists: Rocket News, X-mas cards


System tokens πŸ”—

System tokens are identified by <system|content|format>.
Available system tokens:

  • Now – current date and time
    Format is any standard or custom C# DateTime format, and may be omitted.
    Example: <system|now|yyyy-MM-dd hh:mm>
  • Today – current date
    Same as Now, but excludes time portion of current DateTime.
  • User – current Dataverse user
    Format is any XRM Token.
    Example: <system|user|{fullname} of {businessunitid.name}>
  • Char – special character handling
    Format can be any of \\n, \\r and \\t, which will be replaced by \n, \r and \t for line breaks and tabs.
    Example: {fullname}<system|char|\\n\\r>{address1_line1}

Token formatting πŸ”—

Formats can be added to the returned values by adding a pipe character after the token.

Available format tokens:

  • Left – truncates populated value at the end if necessary.
    Format contains the max number of characters.
    Example: {description|<MaxLen|50>}
  • Right – same as Left but truncates from the beginning.
  • Pad – fills a populated value to specified number of characters
    Format contains R/L defining which end to pad, number of total characters, and an optional pad character.
    Example: {firstname|<Pad|L|25|_>}
    The example will right align the first name and prepend it with underscore up to a total of 25 characters.
  • SubStr – gets a section of the populated value.
    Format contains start character (zero indexed) and number of characters to return.
    Example: {accountnumber|<SubStr|3,6>}
    The example will return 6 characters of the account number, starting at the fourth character.
  • Replace – replaces occurrences of old string with the new string in the populated value.
    Example: {description|<Replace|CDS|Dataverse>}
  • Math – performs a few mathematical operations.
    Format contains operator, and a second value. Second value may be a token itself.
    Example: Total VAT: {price|<value><Math|*|{vat}>}
    This example will return the price multiplied by the VAT.
    Math operators: + – * / Div Mod Round Abs. Note that Round and Abs do not require second value.

The formats can be applied to any previous token, and combined:

User last name is <system|user|{lastname|<Left|3><Pad|R|10|*>}>.

The example above would look up the current user, extract the last name, take the first three characters of that, and finally append asterisks to the right up to a total length of 10 characters.


If-else statements πŸ”—

XRM Tokens can include conditions.

Conditional values are defined using the following format:

<iif|value1|operator|value2|trueresult|falseresult>

Definition of parameters:

  • value1 – any token, static value, or combination for the first value of the comparison
  • operator – defines how to compare value1 and value2
    Allowed operators: eq, neq, lt, gt, le, ge
  • value2 – any token, static value, or combination for the second value of the comparison
  • trueresult – any token, static value, or combination to return if the comparison evaluates to true
  • falseresult – any token, static value, or combination to return if the comparison evaluates to false

Example:

{firstname} has <iif|{emailaddress1}|neq||email {emailaddress1}|no email|>

Sequences πŸ”—

When using XRM Tokens on a bulk of records, it can be beneficial to number them using an external sequence counter. To add and format this sequence number, enter sequence tokens:

[#|startno|format]

Definition of parameters:

  • startno – indicates first number of the bulk (optional)
  • format – Format is and standard or custom C# number format, and may be omitted.

Examples:

[#] {fullname}
[#|1001|0000000] {name}