Working with Dynamic Properties

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, you can also add or remove the properties at runtime for each entity individually.
• Namespace: the dynamic properties of an entity can be organized in namespaces similar to UNIX filesystem folders. This allows you to 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:

1. Create an application named My CRM with two components: Database and Web App.
2. Navigate to the details of the Database component and create a new dynamic property /database/database-name with the value My Database.
3. Select Prompt and click Package.
4. Create a package 1.0.2130 for the application.
5. 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.
6. 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

• Single Line Text (Default)

  Type: SingleLineText

  A single line text field which can contain up to 2000 characters.

• Number

  Type: 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

  Type: Date

  You can select a date via a date picker. By default, a new property is empty.

• Date/Time

  Type: DateTime

  You can select a date and time via a picker. Per default a new property is empty.

• Long Text

  Type: LongText

  A multiline text field which can contain an unlimited number of characters.

• Protected

  Type: 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

  Type: ShortText

  A multiline text field which can contain up to 2000 characters.

• Single Choice

  Type: 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).

  Click Change Options to enter the options that you want to be available, one per line. The line starting with an * is taken as selected value.

  In case one or multiple choices are duplicated, an error message is shown.

  Example:

  The following text makes three choices available and selects c1 as initial value after creation:

  * c1

  c2

  c3

  Notes:

  • You can change the available options only on the entity where the dynamic property is defined.
  • When you override a Single Choice property you have to select a value from the predefined options (or enter a custom value).

  Important! 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.

• Multi Choice

  Type: 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, click Change Options to enter the options that you want to be available, one per line. The lines starting with an * are taken as selected values.

  Example:

  The following text makes four choices available and selects c1 and c4 as initial values after creation:

  * c1

  c2

  c3

  * c4

  Notes:

  • You can change the available options only on the entity where the dynamic property is defined
  • When you override a Multi Choice property, you have to select a value from the predefined options.

  Important! 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.

• List

  Type: 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

  Type: 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.

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.

Important! 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:

• 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}

• Other 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.

For example, if you enter database in the Property field and click the filter icon, the following properties are displayed:

Related Entities

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

• Component

  Displayed as: [Component Name] (C)

  Entities that can be referenced: current component

• Application

  Displayed as: [Application Name]

  Entities that can be referenced:

  • Current Application
  • All Components of the Application

• Deployment Profile

  Displayed as: NOT AVAILABLE in other entities

  Entities that can be referenced: All Components of the Application

• Package

  Displayed as: Package: [Package Name]

  Entities that can be referenced:

  • Current Package
  • The Application
  • All Components of the Application

• Workflow

  Displayed as: [Workflow Name]

  Entities that can be referenced:

  In Application Workflows:

  • Current Workflow
  • The Application
  • All Components of the Application

  In General Workflows:

  • Current Workflow

• Execution

  Displayed as: NOT AVAILABLE in other entities.

  Entities that be referenced: Current execution

• Environment

  Displayed as: [Environment Name]

  Entities that be referenced: Current Environment

• Deployment Target

  Displayed as: [Deployment Target Name]

  Entities that be referenced: 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

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

   Notes:

   • Component dynamic properties can be also created from the variable picker of the PrompSets tab in the Workflow Editor. See: PromptSets Tab
   • Dynamic properties cannot be used with e-mail templates.
2. Enter the 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.

   Notes:

   • You cannot create dynamic properties in the /custom namespace. For more information, see Custom Types.
   • Namespaces are case sensitive.
3. Enter the (case sensitive) name of the property after the slash. For example: /target/target_files_dirs
4. 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.

5. Select one of the following value types:

   • Static: if the dynamic property is a static value (hard value).

     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 for the value while the Package is being created (only displayed for Applications and Components).
        • Execution: users are prompted for the value while the Workflow is being executed (displayed for Applications, Components, Workflows and Packages).
     2. Enter a caption for the dialog.
     3. Enter a default value.

     Important! You can define the order of the prompts. To do so:

     1. Click the Reorder prompts button in the toolbar.
     2. Move the properties up or down in the list.
     3. Save your changes.

     Note: Changes in the order of prompts are saved in the history. See: Statistics & History.

   Important! 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.

   For 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.

6. Click the yes radio-button if you want this property to be highlighted in yellow. This helps you find the important dynamic properties later.
7. 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 inline changes made to a dynamic property that result in an invalid expression will not be saved. The edit dialog will show the latest correct expression instead.
     • 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

1. Go to the Release Automation perspective.
2. Select the entity where you want to delete the dynamic property (Application, Component, Deployment Target...).
3. Go to General / Dynamic Properties.
4. 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

Important! 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)
• Two / are allowed after each other (for example, /not//allowed)

Folders

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

See also: