Create a Dictionary

This topic describes how to use placeholders and dictionaries in Deploy to manage environment-specific information and sensitive data.

Placeholders are configurable entries in your application that will be set to an actual value at deployment time. This makes the deployment package environment-independent and reusable. At deployment time, you can provide values for placeholders manually or they can be resolved from dictionaries that are assigned to the target environment.

Dictionaries are sets of key-value pairs that store environment-specific information such as file paths and user names and sensitive data such as passwords. Dictionaries are designed to store small pieces of data. The maximum string length allowed for dictionary values is 255 characters.

You can assign dictionaries to environments. If the same entry exists in multiple dictionaries, Deploy uses the first entry that it finds. Ensure that you use the correct order for dictionaries in an environment.

important

As of Deploy version 9.8.x, you cannot assign the same dictionary to an environment multiple times. If you try to assign a dictionary to an environment more than once, Deploy will generate an error message displaying the duplicate entries. You must remove the duplicate entries in order to create or update the environment successfully.

A dictionary can contain both plain-text and encrypted entries. Use dictionaries for plain-text entries and encrypted dictionaries for sensitive information.

Create a dictionary

To create a dictionary:

1. In the top bar, click Explorer.
2. Hover over Environments, click , and select New > Dictionary.
3. In the Name field, enter a name for the dictionary.
4. In the Common section, in the Entries field, click Add new row.
5. Under Key, enter the placeholder without delimiters {{ and }} by default.
6. Under Value, enter the corresponding value.
7. Repeat this process for each plain-text entry.

note

To remove an entry, click cross icon against the entry.

1. In the Encrypted Entries section, click Add new row.
2. Under Key, enter the placeholder without delimiters.
3. Under Value, enter the corresponding value.

note

Encrypted entry values are always masked with an asterisks (*).

1. Repeat this process for each encrypted entry.

note

To remove an entry, click cross icon against the entry.

1. Click Save.

tip

You can create a dictionary while creating a new environment.

Create an encrypted dictionary

To create an encrypted dictionary:

1. In the top bar, click Explorer.
2. Hover over Environments, click , and select New > Encrypted dictionary.
3. In the Name field, enter a name for the encrypted dictionary.
4. In the Common section, in the Entries field, click Add new row.
5. Under Key, enter the placeholder without delimiters {{ and }} by default.
6. Under Value, enter the corresponding value.
7. Repeat this process for each plain-text entry.

note

To remove an entry, click cross icon against the entry.

1. Click Save to save the dictionary.

Assign a dictionary to an environment

To assign a dictionary to an environment:

1. In the top bar, click Explorer.
2. Expand Environments and double-click the desired environment.
3. In the Dictionaries field, select a dictionary from the dropdown list.
4. Click Save to save the environment.

Multiple dictionaries can be assigned to an environment. Dictionaries are evaluated in order. Deploy resolves each placeholder using the first value that it finds. For more information, see Using placeholders in Deploy.

Restrict a dictionary to containers or applications

You can restrict a dictionary to ensure that Deploy applies it only to specific containers, specific applications, or both. To restrict a dictionary:

1. In the top bar, click Explorer.
2. Expand Environments and double-click the desired dictionary.
3. Under the Restrictions section, click in the Restrict to containers field and select one or more container from the dropdown list.
4. Click in the Restrict to applications field, and from the dropdown list, select one or more applications.
5. Click Save.

note

An unrestricted dictionary cannot refer to entries in a restricted dictionary.

Troubleshooting restricted dictionary

When you restrict a dictionary, it affects how Deploy resolves placeholders at deployment time.

For example, if you have the following setup:

• A dictionary called DICT1 has an entry with the key key1. DICT1 is restricted to a container called CONT1.
• A dictionary called DICT2 has an entry with the key key2 and value key1.
• An environment has CONT1 as a member. DICT1 and DICT2 are both assigned to this environment.
• An application called APP1 has a deployment package that contains a file.File CI. The artifact attached to the CI contains the placeholder {{key2}}.

When you deploy the package to the environment, mapping of the CI will fail with the error Cannot expand placeholder {{key1}} because it references an unknown key key1.

This occurs because, when Deploy resolves placeholders from a dictionary, it requires that all keys in the dictionary are resolved. In this scenario, Deploy tries to resolve {{key2}} with the value from key1, but key1 is missing because DICT1 is restricted to CONT1. The restriction means that DICT1 is not available to APP1.

Suggested workarounds:

• Restrict DICT1 to APP1 (in addition to CONT1).
• Add key1 to DICT2 and assign it a "dummy" value (so the mapping will succeed).
• Create another unrestricted dictionary that will provide a default value for key1.