Working with Dynamic Properties

This page includes the following:

About Properties

See: About Properties

Features of Dynamic Properties

Dynamic properties have the following features:

Add/Remove at Runtime: you do not have to specify the properties in the definition of a custom type, but can add or remove the properties at runtime for each entity individually.
Namespace: dynamic properties on an entity can be organized in namespaces similar to UNIX filesystem folders. This way you can organize and manage large lists of dynamic properties.
Caption: a human-readable name for the properties, which is used when prompting for their values. If no caption exists for the prompt property, the namespace is shown instead.
Dynamic Values: the value of a dynamic property can either be static or dynamic. A dynamic value is an expression that is evaluated during a deployment.
Prompting: properties can be overridden along hierarchies. For example, a dbname that is defined on a database component can be overridden for a single execution.
Highlighted: you can easily identify important dynamic properties by highlighting them.

Example

Create an application My CRM with two components Database and Web App.
Navigate to the details of the Database component and create a new dynamic property /database/database-name with the value My Database.
Select Prompt and click Package.
Create a package 1.0.2130 for the application.
For this package, you decide to change the name of the database to My CRM Database:
Navigate to the dynamic properties of the package and select the Highlighted value in the View properties of selector.
This displays all highlighted dynamic properties and the properties you have set to be prompted on and allows you to override the database name specifically for this package.

Types of Dynamic Properties

The following types of dynamic properties are available:

The technical type name refers to predefined dynamic properties in your custom type definitions. See: Dynamic Properties.

Display name of type	Technical type name	Comment
Single Line Text (Default)	SingleLineText	A single line text field which can contain up to 2000 characters.
Number	Float	A single line text field where only numbers can be entered. "." has to be used as comma separator. The number has to be a valid decimal.
Date	Date	You can select a date via a date picker. By default, a new property is empty.
Date/Time	DateTime	You can select a date and time via a picker. Per default a new property is empty.
Long Text	LongText	A multiline text field which can contain an unlimited number of characters.
Protected	Protected	A single line text field which can contain up to 2000 characters where the entered text is masked. Protected properties are stored encrypted in the database and never show up in plain text. Protected properties are also sent encrypted to the Automation Engine, and can only be decrypted by Automation Engine agents with a JCL like this: Windows :SET &UC4RB_ENCRYPTED_PASSWORD_TMP#="&UC4RB_PASSWORD#" :INCLUDE PCK.ITPA_SHARED.PRV.INCLUDE.DECRYPT_PASSWORD :SET &UC4RB_PASSWORD# = "%UC4_DECRYPTED_PWD%" UNIX :SET &UC4RB_ENCRYPTED_PASSWORD_TMP#="&UC4RB_PASSWORD#" :INCLUDE PCK.ITPA_SHARED.PRV.INCLUDE.DECRYPT_PASSWORD :SET &UC4RB_PASSWORD# = "$UC4_DECRYPTED_PWD" A protected property can be referenced like all other properties via expressions. When you evaluate a property that references a protected property in CDA, "**" is displayed instead of the clear text value. For example, if there is a connection_string property which contains the expression "user={username}, password={password}" and "password" is a protected property, the evaluated connection_string property would look like this: user=theuser, password=**. Values of properties that reference protected properties (recursively) are passed encrypted to the Automation Engine and can only be converted to clear text again by using the command previously described. You cannot reference a protected dynamic property in another protected dynamic property, unless it is set to expression. When a protected property is in expression mode, the expression is NOT stored encrypted in the database, but visible in clear text. However when the expression gets evaluated, the normal semantics of protected properties apply. You can drill down into the expressions in clear text up until you hit a static protected property.
Short Text	ShortText	A multiline text field which can contain up to 2000 characters.
Single Choice	SingleChoice	A single choice dynamic property allows you to select an option from a predefined list of choices. When creating the choicelist, you can decide if the user is allowed to enter new values (check the allow custom values checkbox) or can only select an option from the predefined value list (default). In the Change Options field, you can enter the available options (one per line). Note: The first item is used as the default value. In case one or multiple choices are duplicated, an error message is shown. You can change the available options only on the entity where the dynamic property is defined via the Change Options action. When you override a Single Choice property you have to select a value from the predefined options (or enter a custom value). If you change the available options, you can invalidate entries that were already entered by users. Dynamic Properties where selected values are invalid, are highlighted in red. Note: When creating Single Choice dynamic properties you have to enter the options that you want to be available, one per line. The default value is the first line starting with an *.
Multi Choice	MultiChoice	A multi choice dynamic property allows you to select multiple options from a predefined list of choices. In the second step during property creation, you can enter the available options (one per line). If you start a line with a "", the choice is selected after creation. You can change the available options only on the entity where the dynamic property is defined via the Change Options action. When you override a Multi Choice property, you have to select a value from the predefined options. If you change the available options, you can invalidate entries that were already entered by users. Entities where some of the selected values are invalid, are highlighted in red. Note:* When creating Multi Choice dynamic properties, you have to enter the options that you want to be available, one per line. Lines starting with an * are taken as default values.
List	List	Dynamic properties of type List allow you to pass values as a list of comma separated values to the Automation Engine. Click the edit in pop-up link to show the items in a pop-up. Each line in the text box in the pop-up is a single entry. Empty lines are ignored. Note: In the dynamic property grids, or evaluation screens, only the first 5 entries of the list are shown. If there are more, they are abbreviated with "...".
Reference	Reference	Allows you to reference other entities of following main types: Package Environment Deployment Target Application User / Usergroup (= Member, displayed as "User / Group") Login Workflow Note: For security reasons, using/referencing “foreign” protected properties is not supported. You can define protected properties at application level and reference them at component level to use them for component deployment Workflows.

Viewing Dynamic Properties

Dynamic properties are managed within the Dynamic Properties section of some entities.

Image displaying dynamic properties defined for component workflow

The Dynamic Properties section lists all properties that are configured for the entity with their syntax and the evaluated value; that is, the value the syntax is pointing to.

Note: Component values starting with non-alphabetic characters (A-Z) or containing blank spaces cannot be evaluated.

Dynamic properties are grouped in namespaces, which are displayed in alphabetical order.

The property type can be recognized by the icon that is displayed right before the value:

Type	Icon
Static
Dynamic (expressions)
Prompt

One entity can display not only its own dynamic properties, but also the dynamic properties of related entities. For example, an application can also display/override the properties of its components.

Expressions are always in curly brackets:

{@target/custom/protocol}://{/tomcat/host}:{/tomcat/port}

In this example you can see three expressions that are concatenated in a single property expression: an expression called "protocol", and expression called "host" and an expression called "port". These values are separated by various symbols like colons and slashes. Each expression is surrounded by curly brackets. Together, they form another separate dynamic property.

Tip: To learn how to use curly brackets in an expression, read the section: Using Curly Brackets in Expressions.
Other entities (Deployment Targets, Applications, Components) are referenced by: @entity type

@target: references the Target that the Component is associated to in the Profile that is used at runtime. For example, TRG1_QA1 Tomcat
If "custom" is in the property name, you know that this is the expression getting the property from the UI screen. Customs sources a value that is defined in one of the custom property fields.

@target/custom/host: sources the value that is stored in the host field of the target UI screen.
You can also source system properties that are found in the general category; things like name, folder, or owner. Sourcing the name of an entity can be useful if you want to name databases based on each environment. Then, when you execute the script that creates that database, the naming could use the following property:

{@environment/system/name}: Name of the Environment - development.

The following expression can be entered to assign a unique identifier to your database:

{@environment/system/id}
Another symbols can be also used, like / for URL directories.

Note: For security reasons, using/referencing “foreign” protected properties is not supported. You can define protected properties at application level and can reference them at component level to use them for component deployment Workflows.

Custom types are displayed in the /custom namespace (read-only). For more information, see Custom Types.

Filtering Dynamic Properties

When you access the Dynamic Properties section, all properties configured for that entity are displayed. You can filter the properties displayed by name and by value by entering the appropriate values in the filter fields and clicking the filter icon.

Note: When filtering dynamic properties, all values whose path includes the word you are searching for are displayed.

Example: If you enter "database" in the Property field and click the filter icon, the following properties are displayed:

Image displaying path for dynamic properties

Related Entities

The following table displays which related entities are shown depending on the type of the current entity:

Current Entity	Displayed as	Referenceable entities
Component	[Component Name] (C)	Current component
Application	[Application Name]	Current application All components of the application
Deployment Profile	NOT AVAILABLE in other entities	All components of the application
Package	Package: [Package Name]	Current package The application All components of the application
Workflow	[Workflow Name]	In application workflows: Current workflow The application All components of the application In general workflows: Current workflow
Execution	NOT AVAILABLE in other entities.	Current execution
Environment	[Environment Name]	Current environment
Deployment Target	[Deployment Target Name]	Current deployment target

Important! The Properties of drop-down displays related entities regardless of the users permission. You may overwrite properties of related objects even though you do not have direct access to them; overwriting does not change the original value.

Note: For more information about how to change the evaluation settings, see Evaluation Settings.

Creating Dynamic Properties

Go to the Dynamic Properties section of the entity and click the Create button. The Create Dynamic Property dialog appears.

Note: Dynamic properties cannot be used with e-mail templates.
Enter the (case sensitive) name of the namespace to which the variable belongs. By default, the namespace field contains the currently selected namespace. Using namespaces is recommended if you have a large list of dynamic properties on an entity.
Note: You cannot create dynamic properties in the /custom namespace. For more information, see Custom Types.
Enter the (case sensitive) name of the property after the slash. E.g.:/target/target_files_dirs
Select the dynamic property type from the drop-down list (date, reference, single line text...).
Note: When creating Single Choice or Multi Choice dynamic properties, the following input must be entered:
- Single Choice: enter the options that you want to be available, one per line. The default value is the first line starting with an *.
- Multi Choice: enter the options that you want to be available, one per line. Lines starting with an * are taken as default values.
Select one of the following value types:
- Static: if the dynamic property is a static value (hard value).
  
  For example: http://myhost:8080
- Expression: values sourced from other entities, either in the component itself or in other entities like targets or environments.
  
  {@target/custom/protocol}://{/tomcat/host}:{/tomcat/port}/
- Prompt: prompts come in the form of a dialog allowing users to enter their own value at runtime. This may be necessary if certain information is available at execution time, like an IT Service-Management ID.
  
  (at Workflow runtime): "Enter the URL of your Tomcat server" + empty textbox.
  1. Select one of the following options from the Prompt for value on... drop-down list:
    - Deployment Package: users are prompted to enter the value while creating a package.
    - Execution: users are prompted to enter a value while executing the workflow.
  2. Enter a caption for the dialog.
  3. Enter a default value.
Note: Do not put variables into the /system/ or /custom/ namespace. The /system/ namespace contains system defined properties of the entity (for example, Name, Type, and so on). See the dynamic properties sections of the respective entities for details. The /custom/ namespace contains all properties that you have defined in you custom type definition file. If you define variables within these namespaces anyway, you may hide system or custom properties.

Example: Most entities have a name property. If you want to access the value of this property in deployments, you can use the /system/name dynamic property in your scripts.
Click the yes radio-button if you want this property to be highlighted in yellow. This helps you find the important dynamic properties later.
Click Create (or Next in choice properties).

If a dynamic property with the same full name (namespace + "/" + property name) already exists, a popup prompts you to confirm if the current property should be overridden.

Editing Dynamic Properties

The properties of a dynamic property can be edited in the General / Dynamic Properties section of entities.

To Edit Dynamic Properties

There are two starting points to edit dynamic properties:

From the dynamic properties list:
1. Go to the Release Automation perspective.
2. Select the entity where you want to edit the dynamic property (Application, Component, Deployment Target...).
3. Go to General / Dynamic Properties.
4. Right-click the property and select Edit in the context menu, enter one or more new values and click Save.
  Notes:
  - Some properties can be also edited directly on the Dynamic Properties page (inline editing). When you hover over an are that can be edited, the mouse cursor changes to text mode. To edit a property inline, click the value of the property, edit it and click somewhere else to save the changes.
  - The autocomplete function helps you create a valid expression for the property.
From the component workflow:
1. Go to the component workflow.
2. Click an action.
3. Select the Prompt Sets tab.
4. Select the appropriate prompt set.
5. Click the edit icon under the variable.
6. The Edit Dynamic Property dialog is displayed.
7. Enter the new values and click Save.
More Information:
- PromptSets Tab

Deleting Dynamic Properties

Go to the Release Automation perspective.
Select the entity where you want to delete the dynamic property (Application, Component, Deployment Target...).
Go to General / Dynamic Properties.
Do one of the following:
- Right-click the property and select Delete in the context menu.
- Click the dynamic property and select the Delete button in the toolbar.

Note: A dynamic property can only be deleted within the dynamic properties section of the entity that defines the dynamic property. If you delete a dynamic property, all overriding properties are deleted too.

Best Practices for Defining Dynamic Properties

Naming Conventions

Wildcards in Dynamic Properties should be reflected in the property name (“_wildcard”).

The following rules apply for names of dynamic properties:

Max. length: See Types of Dynamic Properties
May contain letters, numbers, "-","?", and "_"
Must start with a letter, or "_"
Cannot contain spaces

Note: Component values starting with non-alphabetic characters (A-Z) or containing blank spaces cannot be evaluated.

The same rules apply for the namespace of a dynamic property, except:

Max. length: See Types of Dynamic Properties
It can contain "/" to indicate a subnamespace.
It has to start with "/" (root namespace)
No two "/" are allowed after each other (for example: /not//allowed)

Folders

Custom Dynamic Properties should be stored in separate folders to avoid confusion.