Metacoda Plug-ins Tip: Replaceable Tokens

This is a tip for those who use the Metacoda Security Plug-ins Batch Interface for scheduled automation of SAS® metadata security reporting, testing and identity synchronization. You will find this tip useful if you are using the same configuration values in multiple batch configuration or Identity Sync Profile (IDSP) XML files and would like a way to specify these values in a single places rather than maintain them in multiple locations.

An enhancement that was added in Metacoda Plug-ins 6.1 R3 (Feb 2020) included widespread support for the use of replaceable tokens, including operating system environment variables, Java system properties, and various components/formats of the current date/time, in batch configuration files and identity sync profiles.

For an example of where this may be useful, imagine that you have several batch configuration files used for metadata security HTML export, metadata security test XML export, metadata security testing, and identity synchronization. Each of those batch configuration files includes a <MetadataConnection> tag to target a SAS metadata server to use:

<BatchConfig xmlns="http://metacoda.com/xsd/plugins-batchconfig-6"
    ...
    <MetadataConnection host="sasmeta.example.com" port="8561" user="service@saspw" password="{sas002}ABCDABCDABCDABCDABCDABCD" authDomain="DefaultAuth"/>
    ...
</BatchConfig>

If you needed to change any of those values then you would have to make the change in each of the XML files. Alternatively, you could replace that <MetadataConnection> tag with one that uses replaceable tokens for environment variables and define those environment variables in a script that calls the Metacoda Plug-ins Batch Interface.

The <MetadataConnection> tag will now look like this:

<BatchConfig xmlns="http://metacoda.com/xsd/plugins-batchconfig-6"
    ...
    <MetadataConnection host="${META_HOST}" port="${META_PORT}" user="${META_USER}" password="${META_PASS}" authDomain="${META_DOMAIN}"/>
    ...
</BatchConfig>

… and the environment variables will be set in a calling script like this snippet from a Linux shell script:

...
export META_HOST="sasmeta.example.com"
export META_PORT="8561"
export META_USER="service@saspw"
export META_PASS="{sas002}ABCDABCDABCDABCDABCDABCD"
export META_DOMAIN="DefaultAuth"
...

… or this snippet from a Windows batch script:

...
set META_HOST=sasmeta.example.com
set META_PORT=8561
set META_USER=service@saspw
set META_PASS={sas002}ABCDABCDABCDABCDABCDABCD
set META_DOMAIN=DefaultAuth
...

Now, if any of those values need to change, there is a single place to change it instead of several places.

Another example, showing the user of date tokens, is where you may want to export to a directory path that uses the current date, so you keep a history of exports/reports over time. In a batch configuration file you could have the following for exporting reports of the current metadata security implementation in HTML format:

<BatchConfig xmlns="http://metacoda.com/xsd/plugins-batchconfig-6"
    ...
    <SecurityToolsExport file="${DIR}/output/${dt:F}/security-report.html">
    ...
</BatchConfig>

… or a batch config for metadata security testing results in HTML format:

<BatchConfig xmlns="http://metacoda.com/xsd/plugins-batchconfig-6"
    ...
    <HTMLResults file="${DIR}/output/${dt:F}/security-test-results.html"/>
    ...
</BatchConfig>

… or an Identity Sync Profile (IDSP) that generates an audit report of changes in HTML format:

<IdentitySyncProfile xmlns="http://metacoda.com/xsd/plugins-idsync-profile-6"
    ...
        auditReportFile="${DIR}/output/${dt:F}/idsync-audit-report.html"
    ...
</IdentitySyncProfile>

In all of these cases the ${dt:F} token will be replaced with the current date in ISO 8601 format (e.g. 2020-10-09). If the directory doesn’t exist it will be created.

Here is some more info on the types of replaceable tokens available….

Operating System Environment Variable Tokens

Operating system environment variables can be specified in the form ${ENVIRONMENT_VAR_NAME}. They are case sensitive on Linux and UNIX platforms and case insensitive on Windows platforms. You can use system provided ones as well as any custom ones you specify yourself. e.g.

${HOME}
${APPDATA}
${LOCALAPPDATA}
${USERPROFILE}
${TEMP}

Java System Property Tokens

Java system properties can be specified in the form in the form ${SYSTEM_PROPERTY_NAME}. They are case sensitive on all platforms. Again, you can use system provided ones as well as any custom ones you specify yourself. e.g.

${java.io.tmpdir}
${user.dir}
${user.home}
${user.name}

Calendar (Date/Time) Tokens

Current date/time tokens, of the form ${dt:DATE_TOKEN_NAME}, are based on Java String.format patterns (see http://docs.oracle.com/javase/1.5.0/docs/api/java/util/Formatter.html#syntax):

${dt:H} is the 2 digit hour of the day (00-23)
${dt:I} is the 2 digit hour of the day (01-12)
${dt:k} is the 1-2 digit hour of the day (0-23)
${dt:l} is the 1-2 digit hour of the day (1-12)
${dt:M} is the 2 digit minutes within the hour (00-59)
${dt:S} is the 2 digit seconds within the minute (00-59)
${dt:L} is the millisecond within the second as 3 digits (000-999)
${dt:N} is the nanosecond within the second as 9 digits (000000000-999999999)
${dt:p} is locale specific am/pm indicator as lower case
${dt:P} is locale specific AM/PM indicator as upper case
${dt:z} is numeric time zone offset e.g. +1000
${dt:Z} is time zone abbreviation e.g. EDT
${dt:s} is seconds since 01Jan1970
${dt:Q} is milliseconds since 01Jan1970
${dt:B} is the full month name (January-December)
${dt:b} is the abbreviated month name (Jan-Dec)
${dt:A} is the full name of the day of the week (Monday-Sunday)
${dt:a} is the abbreviated name of the day of the week (Mon-Sun)
${dt:C} is the 2 digit century as 4 digit year / 100 (00-99)
${dt:Y} is the 4 digit year e.g. 2016
${dt:y} is the 2 digit year e.g. 16
${dt:j} is the 3 digit day of year (001-366)
${dt:m} is the 2 digit month (01-13)
${dt:d} is the 2 digit day of month (01-31)
${dt:e} is the 1-2 digit day of month (1-31)
${dt:R} is 24 hour clock time as HH:MM e.g. 23:59
${dt:T} is 24 hour clock time as HH:MM:SS e.g. 23:59:59
${dt:r} is 12 hour clock time II:MM:SS PP e.g. 11:59:38 PM
${dt:D} is US-style date as mm/dd/yy e.g. 12/31/16
${dt:F} is ISO 8601 date YYYY-mm-dd e.g. 2016-12-31
${dt:c} is date/time aaa bbb dd HH:MM:SS ZZZ YYYY e.g. Sun Jul 20 16:17:00 EDT 1969

For backwards compatibility, the identity sync audit report file path attribute still supports these short forms:

%Y the 4 digit year e.g. 2016
%y the 2 digit year e.g. 16
%m the 2 digit month (01-12)
%b the abbreviated month name (Jan-Dec)
%B the full month name (January-December)
%d the 2 digit day of month (00-31)
%a the abbreviated name of the day of the week (Mon-Sun)
%A the full name of the day of the week (Monday-Sunday)
%H the 2 digit hour of the day (00-23)
%M the 2 digit minutes within the hour (00-59)
%S the 2 digit seconds within the minute (00-59)

Metacoda Context Tokens

The following tokens are also provided by Metacoda software:

${batchConfigFile} is the absolute path to the batch config file being processed e.g. C:\Metacoda\batch\idsync-batch-config.xml
${batchConfigDir} is the absolute path to the directory for the batch config file being processed e.g .C:\Metacoda\batch

I hope you found this tip useful. If you have any feedback, questions, or comments please leave a comment below or contact me. If you’d like to try out Metacoda Plug-ins in your own SAS environment you can also register to request a free 30 day evaluation at the Metacoda web site.

Operating System Environment Variable Tokens

Java System Property Tokens

Calendar (Date/Time) Tokens

Metacoda Context Tokens

Leave a Reply