Using Variables or Placeholders

Using the XTAM Task and Job Engine, remote commands and scripts can be executed against a remote host.

In conjunction with the XTAM Identity Vault, the execution of these tasks can be shared and delegated to other users who may not necessarily have native permissions to perform such actions on the host.

It is in this scenario, where XTAM provides the flexibility for the user executing the task to determine some of the parameters of the operation.


Let’s begin by taking a look at a simplistic script that one may wish to run against a remote host.

netsh.exe advfirewall set privateprofile state off


This basic script will set the Private Profile of the Windows Firewall Off on the host.

A very specific script that executes a very specific command which expects a very specific result. However, what if you wanted your user to be able to turn On the firewall profile rather than Off.

netsh.exe advfirewall set privateprofile state on


Well, that is simple too. Just create another script with the state on. And what if you wanted the user to be able to check the status settings of a firewall profile.

netsh.exe advfirewall show publicprofile


There’s a script for that as well.

So you could conceivably create a specific script for every possible scenario (on, off, status for public; on, off, status for private; on, off, status for domain), but that would be incredibly time consuming, extremely difficult to manage and not very efficient for users.

This is precisely where the power of variables or placeholders comes in to the picture.

Rather than creating dozens of individual scripts (which the system will certainly support if you choose), you can create a single script using placeholders and allow the user to implement the commands they need.

And that would look like this:

netsh.exe $${Service Name} $${Command}


When the above script is executed in XTAM, the user executing it will be asked to provide the values defined by the placeholders, $${Service Name} and $${Command}.

They can then enter which service and command that they specifically want to execute and the XTAM job engine will replace those in the script and then execute it accordingly.




In this example, the user would enter advfirewall and set privateprofile state off into the Script Parameters dialog, the engine will add those values into the placeholders and execute the command:

netsh.exe advfirewall set privateprofile state off


This provides much greater flexibility to the users to determine exactly which command they want to execute without having to pre-create dozens or hundreds of scripts for them.



The results or output of the script will be displayed in the Job History page of this record.


You could use this functionality in any script that you want to configure, but here are a few more examples.


To restart a service in a Unix or Linux host:

SRV=$${Service Name}
ACT=$${Command (options: start,stop,restart,status)} 
sudo service $SRV $ACT
echo Results:
ps -ef | grep $SRV




To create a new user in Active Directory and add them to a group:

New-ADUser -Name '$${Name}' -Path '$${Path}' -userPrincipalName '$${UPN}' -DisplayName '$${Display Name}' -AccountPassword (ConvertTo-SecureString '$${Password}' -AsPlainText -Force) -ChangePasswordAtLogon $true -Enabled $false
Add-ADGroupMember '$${Domain Group}' '$${Name}'
write-host "-------- User $${Name} has been created --------"




To list the members of a Windows local group:

([ADSI]'WinNT://./$${Group Name},group').members() | ForEach{$_.GetType().InvokeMember('ADspath',  'GetProperty',  $null,  $_, $null).Replace('WinNT://', '') }




Script designers can use values from any record field in the scripts using {{RECORD:FieldName}} placeholder and any field of a shadow record using {{SHADOW:FieldName}} placeholder. Note that FiledName in this context is the name of the field from the record type architecture (not display name visible on the record view)

Script designers can also use predefined placeholders for frequently used fields:

{{LOGIN}} - User on record

{{NEWPWD}}, {{PWDNEW}} or {{NEWPWD-BASE64}} - New password

{{OLDPWD}}, {{PWDOLD}} or {{OLDPWD-BASE64}} - Old password or Password on record

{{DOMAIN}} - domain part of the User on record

{{SHADOW_LOGIN}} - User name of the Shadow record

{{SHADOW_PASSWORD}} or {{SHADOW_PASSWORD-BASE64}} - Password on the Shadow record

{{PAMLOGIN}} - User name of the currently logged in user (the field is useful for on-demand tasks triggered interactively by user actions)