What are Replacement Tokens?
Replacement tokens are special variables that can be used in certain places to replace/insert data or information which is only available at execution time, such as starting a connection, executing a task in the context of a connection, or creating an object from a template.
Let's take a look at the built-in Ping task, which can be executed in context of a connection by right-clicking an existing connection and selecting the Command Tasks -> Ping command.
The URI of the selected connection (computer name / IP address) will be replaced in the Ping command task argument using the
$URI$ replacement token.
See also Working with Tasks
Where can I use Replacement Tokens?
- In Command Tasks, use the fly-out-button (right arrow) in the
- In Key Sequence Tasks, use the Insert button to insert replacement tokens and/or special keys.
- In Templates use the Template Tokens button at the top right for a list of available tokens.
- In Connections, you can use replacement tokens only in places where it is explicitly mentioned in the docs. The URI property (computer name or web address), for example, can resolve replacement tokens. In these cases, the tokens must be entered manually as there's no fly-out-button available.
When you execute a task or template in the context of one or more connections (the selected connections), the specified tokens such as
$CustomField1$ are resolved and replaced from the context connection.
If no context is available (for example, by simply connecting to a connection), the context is the object itself. This means, using the token
$CustomField1$ in the Computer Name field of a connection will use the value of Custom Field 1 of the very same connection.
If you want to use a value from the task itself instead of the context connection, you can prefix the token with
this.. For example:
$this.CustomField1$ will resolve the value of the Custom Field 1 from the task instead of the context connection.
In general, you can refer to any of the available properties for each involved object type. A complete reference of properties for each type can be found here.
Each object can have an arbitrary number of Custom Properties, such as the Remote Desktop connection. To access the value of a custom property, you need to use the
CustomProperty. prefix and the alphanumeric name WITHOUT spaces of the property.
For example: if you have a custom property with the name:
User's Start-Date: you can access the value using the token
Date and Time
With the prefix
DateTime. and the format string after the
. character you can get the current date and/or time in the format specified.
$DateTime.yyyy-MM-dd$ you will get
Env. provides access to environment variables.
$Env.USERNAME$ will resolve the environment variable
A number of special tokens are also available, mainly for easier access to credential information after the credential (either set directly or referenced by ID or name) has been resolved:
$EffectiveUsername$: the user name of the resolved credential
$EffectiveUserdomain$: the domain portion of the effective user name (if available)
$EffectiveUsernameWithoutDomain$: the user name portion without the domain of the effective user name
$EffectivePassword$: the password of the resolved credential
$EffectiveKeyFile$: the configured key file path of the resolved credential
$EffectivePassphrase$: the pass phrase for the key file of the resolved credential
$EffectiveID$: the ID (GUID) of the context object
$DocumentFilePath: the path to the .rtsz file (document) of the context object
$DocumentFolderPath$: the path to the folder where the .rtsz file (document) of the context object is located
RoyalJSON (rJSON) Tokens
There are a couple of special tokens/prefixes for dynamic folder scripts. Read the Tokens section of the RoyalJSON documentation for more information.
Replacement tokens for protected/encrypted properties, such as passwords, may not be resolved if the document of the object is locked down. See also: Working with Lockdown Documents