Tokens Best Practices

Tokens let you provide different values for parameters within configuration files based on the environment that is being used.
ra55
Overview
Tokens let you provide different values for parameters within configuration files based on the environment that is being used.
Tokens work very closely with artifact definitions. You can also use tokens to replace objects that are part of a file.
Tokens give you the flexibility to replace file contents downloaded by
Nolio Release Automation
to a given server. Tokens reduce the number of errors at deployment time, especially when you are deploying to multiple environments.
Token Creation Details
Create and manage tokens by selecting Administration, Token Management in Release Operations Center.
For more information about basic token creation steps, see Tokens.
When creating a token, the main values you have to define are token masks and token types.
Token Masks
Masks enforce validation on token values. The pre-defined masks deal with enforcing validation of IP and email addresses. The pre-defined masks apply to String and Number token types.
For custom masks, you define the validation rule that the token must match. For more information, see Custom Token Masks.
Token Type
Token types represent common token categories and define what you can enter as a mask value:
  • Boolean
  • Number
  • String
  • Password
For the String and Number types, you can use pre-defined masks. For the Boolean type, you can only have “True or False”. For a Password type, you must enter the password, which is masked.
Example Create Token page selections:
Typical token creation
Example list of defined tokens for an application:
Token definitions as shown in Release Operations Center
After you create tokens, you can configure the necessary token values for the environments that you have defined by selecting Environment, Parameter Configuration, Tokens in Release Operations Center:
Token values at the environment level
Token Custom Masks
Custom mask for tokens are based on JavaScript regular expressions (regex) syntax.
For more information about regular expression syntax, http://www.w3schools.com/jsref/jsref_obj_regexp.asp.
Metacharacters supported
Metacharacters are special characters used for to control what type of character, how to search for a word, and other conditions. Tokens support the following metacharacters:
Metacharacter
Description
.
Finds a single character, except newline or line terminator.
\w
Finds a word character.
\W
Finds a non-word character.
\d
Finds a digit.
\D
Finds a non-digit character.
\s
Finds a white space character.
\S
Finds a non-white space character.
\b
Finds a match at the beginning or end of a word.
\B
Finds a match not at the beginning or end of a word.
\0
Finds a NULL character.
\n
Finds a new line character.
\f
Finds a form feed character.
\r
Finds a carriage return character.
\t
Finds a tab character.
\v
Finds a vertical tab character.
\
xxx
Finds the character specified by an octal number
xxx
.
\x
dd
Finds the character specified by a hexadecimal number
dd
.
\u
xxxx
Finds the Unicode character specified by a hexadecimal number
xxxx.
Quantifiers Supported
Use quantifiers to match the desired number of characters.
Quantifier
Description
n
+
Matches any string that contains at least one
n
.
n
*
Matches any string that contains zero or more occurrences of
n
.
n
?
Matches any string that contains zero or one occurrences of
n
.
n
{
X
}
Matches any string that contains a sequence of
X
n
's.
n
{
X
,
Y
}
Matches any string that contains a sequence of
X
to
Y
n
's.
n
{
X
,}
Matches any string that contains a sequence of at least
X
n
's.
n
$
Matches any string with
n
at the end of it.
^
n
Matches any string with
n
at the beginning of it.
?=
n
Matches any string that is followed by a specific string
n
.
?!
n
Matches any string that is not followed by a specific string
n
.
Brackets Supported
Use brackets to find the range of characters.
Expression
Description
[
abc
]
Find any character between the brackets.
[^
abc
]
Find any character not between the brackets.
[0-9]
Find any digit between the brackets.
[^0-9]
Find any digit not between the brackets.
(
x
|
y
)
Find any of the alternatives specified.
Common Expressions
The following table presents the most common JavaScript regular expressions:
Expression
Description
.
Matches any character.
^
n
Finds
n
that must match at the beginning of the line.
n
$
Finds
n
that must match at the end of the line.
[
abc
]
Set definition, can match the latter a or b or c.
[
abc
][
vz
]
Set definition, can match a or b or c followed by either v or z.
[^
abc
]
When a caret appears as the first character inside the square brackets, it negates the pattern. This content can match any character except for a or b or c.
[
a-d
1-7]
Matches a letter between
a
and
d
and figures from 1 to 7, but not d1.
X
|
Z
Finds
X
or
Z
.
XZ
Finds
X
directly followed by
Z
.
$
Checks if a line end follows.
Example Custom Masks
JAVA-based regular expressions are a powerful mechanism for configuring your token's custom mask. Based on the supported and most common regular expressions, this section contains some custom mask examples.
Example Custom Mask: Number Token
The following are examples of how to create the different number masks:
  • 999999.99
    Requires a number up to that value with two digits for the suffix value, such as 128474.45.
  • \d{6}
    Requires a number with a fixed value of 6 digits, such as 123456.
  • ^[-0-9].*
    Requires a number (positive or negative) with a floating suffix, such as 234, -204.02, 93.394.
Example Custom Mask: String Token
The following examples are for string masks:
  • ^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$
    Requires a hex value with a minimum of 3 characters and a maximum of 6 characters, such as #3F0 or #FFA.
  • (0?[1-9]|[12][0-9]|3[01])/(0?[1-9]|1[012])/((19|20)\d\d)
    Requires a date format in the form of DD/MM/YYYY, such as 10/03/2015.
  • (0?[1-9]|1[012])/( 0?[1-9]|[12][0-9]|3[01] )/((19|20)\d\d)
    Requires a date format in the form of MM/DD/YYYY, such as 03/10/2015.
  • ([01]?[0-9]|2[0-3]):[0-5][0-9]
    Requires a time in a 24 hour format, such as 18:20.
  • ^([0-9]|([1][0-2])):[0-5][0-9][[ ]] ?([ap][m]?|[AP][M]?)
    Requires a time in a 12 hour format, such as 7:30 am.
  • ([^\s]+(\.?([jpg|png|gif|bmp]?|[JPG|PNG|GIH|BMP]?))$)
    Requires an Image file extension, such as tester.jpg.
  • ^[a-z0-9_-]{3,15}$
    Requires a user name, such as rauser.
  • ^[_A-Za-z0-9-]+(\.[_A-Za-z0-9-]+)*@[A-Za-z0-9]+(\.[A-Za-z0-9]+)*(\.[A-Za-z]{2,})$
    Requires an email address, such as [email protected]
  • ^([01]?\d\d?|2[0-4]\d|25[0-5])\.([01]?\d\d?|2[0-4]\d|25[0-5])\.([01]?\d\\d?|2[0-4]\d|25[0-5])\.([01]?\d\d?|2[0-4]\d|25[0-5])$
    Requires an IP address. You could also configure a string to just look at a specific subnet.
Artifacts Using Tokens
After you have defined the tokens, you can either modify existing files or create new files that will contain the token objects. Define a token object as follows in a text file:
Consider the following examples:
The following file is an example of a configuration file that handles
Nolio Release Automation
token values:
A file containing CA Release Automation defined tokens
When you add the token definitions in a file that has been added to the software package repository, it will be deployed and executed based on the defined tokens.
Tokenize an Artifact Type
For the artifact type that you have defined, the artifact definition must be “tokenized” to perform the replacement of the token with the token contents for the given environment. Below is an example of how to ensure that the artifact type is tokenized.
Setting tokenization for an artifact type
By default, the tokenized file value is “@@[email protected]@”. Use this format to define a token in the file. You can change this value on the Edit Artifact Definition dialog to reflect your coding standards.
Tokens and Manifest Files
Token facilities can also create the necessary manifest files, which you can use to configure the necessary token values at deployment time. You can download or upload manifest files using the Manifest drop-down menu in the Token Definitions or Environment Parameter configuration pages.
Manifest drop-down menu
  • Administration -> Token Management menu:
    Token definitions and all environments values from the manifest file are applied.
  • Environments -> Parameter Configuration menu (Tokens tab):
    Only token values for the environment, selected in the left panel, are applied. Token definitions and token values for other environments are not applied. If a tag with the selected environment name is not present in the manifest file, the error message "Environment is not specified in manifest" is displayed.
The following file is a sample of a tokens manifest:
Sample Token Manifest File
Manifest files provide you with the flexibility of determining the correct values for the token values that will be passed to the different artifacts for processing.
Best Practices
The following best practices can help you determine the best token usage method to follow.
Number of Tokens to Use
Consider and answer these questions before creating the tokens for a given application:
  • How many tokens are required?
  • How generic are these tokens?
  • Are the tokens only specific to one environment?
  • Do you need to modify the token mask from “@@[email protected]@” to your coding standards?
Number of Token Manifest Files to Use
Before creating tokens, determine the number of token manifest files to be maintained and how many different manifest files are required for your application.
Artifacts Affected by Tokens
At the same time that you are determining the number of tokens to use for a given application, determine the number of software package artifacts affected by these tokens.
We recommend that you add a comment in the artifact definition stating that the artifact makes use of
Nolio Release Automation
tokens for its successful processing.
Simple Tokens Example
To help illustrate token functionality, this example presents a simple application that performs a series of delay actions lasting about 30 seconds each. The application includes a user input action in the flow and processes that demonstrates how the token values are updated.
  1. Create a Release Automation application.
  2. Configure the corresponding server types, architectures, and environments.
  3. Select Administration, Token Management in Release Operations Center.
  4. Create the following tokens:
    Boolean Token
    Number Token
    Password Token
    String token
  5. Add entries to the tokens for the different environments by selecting
    Environment
    ,
    Parameter Configuration
    ,
    Tokens
    .
  6. Select
    Artifacts
    ,
    Artifact Management
    .
  7. Create a new artifact type and call it Tokens_Demo.properties.
    Tokens demo file
  8. Make sure that this file resides in the C:\temp directory of the
    Nolio Release Automation
    Management Server before to creating an artifact definition for it
  9. Map the components in the application to this artifact type, and make sure that you select the Tokenized File for… @@[email protected]@ option.
  10. Add an artifact definition based on the file name above
  11. Add a version to the artifact definition, specifying where the file resides on the Management Server, since it will be a local file
  12. Select
    Designer
    ,
    Process Design
    .
  13. Add the following actions to a process for the application:
    Delay
    ,
    Copy Files or Folders
    , and
    User Input - Stop for Manual Operation
    .
  14. Create a flow for the process and call it Delay-Loops.
    Example flow
  15. Configure the flow to use a loop type:
    COLLECTION
    with the input as the artifact type you defined in Step 7.
    Example flow with collections loop
  16. Add the
    Artifact File
    parameter to the source path field in the
    Copy Files and Folders action
    .
  17. Create the c:\temp\demo folder on the Management Server.
  18. Create a process named Tokens Demo and publish it.
  19. Select
    Releases
    ,
    Template Categories
    and create the following:
    • A template category
    • A deployment template
    • Add the process that you have already published, and add it as deployment step
    • A deployment plan
    • A project
    • A new deployment off the deployment template
    • Add an artifact package based off the artifact type that you created previously
    • A deployment
  20. Start the deployment.
    The User Input Required dialog opens:
    User input for tokens
  21. Switch to the Management Server and check the status of the file that you placed in the c:\temp\demo folder.
    The contents of the downloaded file appear as follows:
    Tokens demo file
This example demonstrates the power of the tokenization of the different values being passed in the different environments for your application.