Rhapsody Variables

Rhapsody variables provide a mechanism for specifying environment-specific parameters when setting configuration properties for components, such as port numbers, hostnames and directory paths. Variables usage is global, meaning a Rhapsody variable can be used simultaneously in the configuration of any communication point, filter or conditional pathway in any folder or locker on the Rhapsody engine.

Rhapsody variables are specified using the notation: $(VariableName), for example $(Port). Some component configuration properties can be specified using a combination of a variable and a hard-coded literal value, for example $(Output_Dir)\Output. Rhapsody variables can also be referenced using this notation in JavaScript, for example by the JavaScript filter.

The Variables Manager provides a central location for managing Rhapsody variables:

Viewing Variables

To launch the Variables Manager:

• From the View menu, select Variables Manager.
• Alternatively, press Ctrl+SHIFT+A.

The Variables Manager displays the following information:

Managing Variables

You can perform the following actions relating to variables from the Variables Manager:

Rhapsody variables can also be managed through the REST API.

Adding Variables

To add a new variable, select the Add button. New variables must have a unique name.

When adding a new variable, you can also copy the variable name to the clipboard, by right-clicking on it and selecting Copy Variable Name. You can also copy-paste variable values using the right-click menu.

Editing Variables

To edit a variable value, type directly into the Value column. You can only edit a variable when you have the 'Edit Locker' access right for all lockers where the variable is used.

Deleting Variables

To delete Rhapsody variables manually:

1. Multi-select the variables to delete.
2. Select the Delete button.
3. If the variables are being used by one or more components, you will be required to confirm deletion.

To find and delete unused variables automatically:

1. Select the Delete Unused Variables button.

2. After scanning the variables, the Variables Manager presents you with the Delete Unused Rhapsody Variables dialog:

   

3. Review the identified unused variables list, and ensure only the variables you want to delete are selected.
4. Select the Delete button to proceed with the deletion, or the Cancel button to abort.

Encrypting Variables

The Variables Manager displays all variables that have been created, and their values. If you do not wish the value of the variable to be visible in the Variables Manager or in the communication point or filter referencing the variable, select the Encrypted checkbox. The entered value is then displayed as <encrypted>. If this checkbox is subsequently cleared, the variable value is lost and must be re-entered; if this is not done, all items that reference this variable will lose that configuration property.

Showing Uses of Variables

The Variable Uses dialog displays a list of the components and shared JavaScript functions that use variables you have selected. The list includes any objects that could be affected as a result of the variables being modified or deleted.

To view a list of objects that use particular variables:

1. In the Variables Manager, select a variable or multi-select variables, and then select the Show Uses button (or right-click on the variable and select Show Uses). The name and path of all components using the selected variables are displayed in the Show Uses tab in the Information panel of Rhapsody IDE:

   

2. To view or edit the configuration properties of a component using the variable: 
   • Double-click on the component path.
   • Or alternatively, from the right-click menu, select Open Properties.

In the case where the variable is used by components in lockers you do not have permission to access, only the count of uses for that locker is displayed, instead of the actual components.

Overriding Variables

On occasion, you may want to modify the value of a variable temporarily, without losing the original value.

To override a variable value:

1. Enter the temporary Override Value for the variable you want to override.
2. Select the Overridden checkbox to override the variable's original value.
3. Check in your changes to the variable.

To restore a variable value:

1. Deselect the Overridden checkbox to restore the variable's original value (unchecking the Overridden checkbox does not delete the override value).
2. Check in your changes to the variable.

Setting a Component Configuration Property

The variables listed in the Variables Manager are accessed when configuring a communication point or filter by entering $( as the first part of the value for the selected configuration property. A context menu is displayed, listing the variables that may be selected. Highlighting any one variable displays its value in a tooltip, except for encrypted variables (in such cases the tool-tip simply reads encrypted). Select a variable from the list by double-clicking its entry; this places the name of the variable (not its value) as the configuration property value in the Configuration dialog:

If a configuration property value is updated in the Variables Manager, all items that reference that value are automatically updated after being checked in.

Rhapsody Environment Variables and Configuration Loading

One of the major benefits of using environment variables is that it makes the process of migrating configurations from Development to Test to Production much simpler. Environment variables should be used for any configuration parameters that are specific to the machine and environment the particular Rhapsody engine is running on. If environment variables are set up on both Rhapsody engines, then the new configuration can be loaded simply by loading the new RLC file. The loaded configuration will automatically use the variables defined on each engine.

Therefore, environment variables are ideal for those configuration parameters that need to be different between the development, test and production systems. For example, if a database communication point is used to update a database with information extracted from a message, it is important that the test Rhapsody engine cannot modify the production database. By setting up the Database communication point to use an environment variable for the database to modify, the appropriate database is automatically selected. Environment variables are always saved when creating an RLC from a loaded configuration, no specific steps need to be taken to enable this.

Environment variables are automatically loaded when loading the configuration from an RLC, however, if the environment variable already exists on the target Rhapsody engine, the current value is not overwritten. If the value does not yet exist then it will take the values from the RLC. This means that once the environment variables are set up correctly on the test and production servers, the production server will save its own variable values, even when an updated configuration from the test environment is loaded.

When environment variables are loaded through the REST API, if the environment variable already exists on the target Rhapsody engine, the current value is overwritten. If the environment variable already exists on the target Rhapsody engine but not in the new configuration, the variable is deleted. The affected communication points or filters enter an unconfigured state due to missing referencing variables.