Named Configuration

Named configurations are predefined configurations that are assigned a name and stored for later reuse. These named configurations ease the process of Event Process Orchestration and Change Management within the Fiorano Event Processes. For example, if a particular connection configuration for SMTP or JMS components is reused in multiple Event Processes, each such Service Instance will have its own copy of the configuration. If a change in configuration is required at a later point of time, then all such Service Instances have to be reconfigured. Using named configuration support, configurations can be predefined and the name of the predefined configuration can be linked/transferred to all Service Instances. Since the actual configuration has only one location but is referred to by multiple Service Instances, making changes to the named configuration will affect all Service Instances automatically (without the need to reconfigure the Service Instances again). The route messaging/selector/transformation configuration, port messaging/workflow configuration and runtime arguments/connection factory properties of service instances follow the same principle stated above.

Below is a glossary of terms used in this Chapter.

Advantages

Faster Event Process Composition

Once named configurations exist, then all artifacts using the same configuration can be configured by providing only the name of the configuration. Configuration details do not have to be provided for each artifact separately.

For example, multiple database instances might be configured to use the same database connection properties. Instead of typing these properties again for each such database instances, a User can save this configuration as a named object and reuse it in all database instances.

Easy Change Management

When artifacts like Service Instance or Port Instance are configured using a named configuration, any changes to the configuration at a later point should be applied only to the predefined configuration instead of reconfiguring each artifact.
For example, if the IP address of a database server changes, all database components should use the new IP address to connect to the database server. Once named configurations exist, instead of re-configuring each database instance using the previous IP address, changes can be made just to the saved named object and this will automatically be reflected across all Event Processes.

Easy Resource Management

Easy Resource Management indicates that if Users wish to see details of all FTP Servers used across all Event Processes, they just need to query the registry for all saved FTP connection configurations.

Smaller Event Process Size

Given that configuration data is no longer part of the Event Process (since the Event Process only contains references to the named objects), the size of the Event Process reduces considerably.

Configuration Types

Configurations can be of the types listed below. An explanation for each of these configuration types and how to use them are given in this section.

• Service Instance Configuration
• Resource Configuration
• Route Configuration
• Selectors Configuration
• Transformation Configuration (Route / App-Context / XSLT Transformations)
• Port Configuration
• Workflow Configuration
• Runtime argument Configuration
• Connection Factory Configuration

The figure below shows the Configuration Repository View with the types of configuration available.

Each configuration type further has 4 sub-categories viz, Development, Testing, Staging, and Production, referring to the four environment labels of an Event Process.

A configuration defined in a particular environment can be applied to elements in an Event Process only if the Event Process is within the same environment. So Configurations with the same name can be defined for different target Environments and the corresponding configuration will be picked during configuration and run-time of an event process based on its Environment.

Service Instance Configuration

Service Instance Configurations refer to the configuration of component instances in an Event Process. Various sections of the configuration, using the Custom Property Sheet (CPS) of a component [Semantic check please], can be saved and used as named configurations. Examples of component configurations that can be saved as named configurations are:

• Component Connection Configuration
• Business logic configuration / Interaction Configuration
• SSL Configuration
• Proxy Configuration

To add a new service configuration, right click on Service in the Configuration Repository view and select the Add Configuration option. Select the Guid and the Version of the service. Few components like FTPGet have multiple configuration types. Select the appropriate type and click Next, as shown in the figure below.

To demonstrate the addition of a New Configuration, the FileReader is used as an example and the FileReader configuration details are displayed. Click on Next and the values of the configuration. Click Finish to save the configuration, as shown in the figure below.

To use the newly added configuration, open the Custom Property Sheet (CPS) of the component and click on the ellipsis button against the property FileReader Configuration, as shown in the figure below.

The FileReader Config dialog box is displayed. Select the Load from option and add the configuration name. Click on the Load button to load the configuration details. Provide additional configuration details for the FileReader and click Finish to save the CPS settings. The named configuration that is referred by the component will be used by the component both at the time of configuration and at the runtime.

If the configuration property is a manageable property then it can be viewed from the Environment Properties section within the Event Process properties.

As shown in the figure above, clicking the ellipsis button against the property FileReaderConfiguration launches the FileReader configuration dialog box .

Resource Configuration

Resource Configurations refer to resources such as files, URLs etc. Various types of resources such as XML, XSD, XSL, TFL, HTML, Script, SSL Configurations and so on can be saved as resource configurations.

For example, the Database Connection Configuration can be applied to all database components in the Database category in the Micro Service Palette.

To define a resource configuration, right-click on Resource in the Configuration Repository view and the select Add Configuration option. A dialog is displayed as shown in the figure below.

Provide basic details of the configuration and select the type of configuration required. Properties are automatically updated on the next page depending upon the type of configuration selected.

Click Next and provide configuration details that need to be filled in and click Finish to save the configuration, as shown in the figure below.

The configuration type Connection Configuration is saved to the repository and can be used by components that have Connection Configuration as part of their configuration settings.

Open Custom Property Sheets of a component that has Connection Configuration details could be, for example, JMS: 4.0. Click the ellipsis button against the Connection Configuration property. This launches the dialog box shown in the figure below.

By default, no named configuration is used. To use a Named Configuration, select the Load from option and type the configuration name and click the Load button to load configuration details, as shown in the figure below.

Similarly, a resource configuration can also be created using the Save to option in the Named Configuration section.

Route Configuration

Route Configurations refer to the messaging configurations used by routes. These configurations define the following properties of the routes created within an Event Process:

• Compress Messages
• Encrypt Messages
• Durability of route

A route configuration can be created using the Add Configuration option in the Configuration Repository view. Route Configuration contains route specific properties such as Compress Messages, Encrypt Messages and Durable Subscription.

To use a route named configuration on a route, select the route and in the route properties move to the Messaging section. A property called Configuration lists all route named configurations.

Select the configuration required. The corresponding configuration properties are automatically updated, though grayed out to prevent editing, as shown in the figure below.

Selectors Configuration

Selectors Configurations refer to the selector configurations used by routes. A single selector configuration can be used to define the four types of message selectors available on the routes. Selector configurations store within them the four message selector configurations given below:

• Sender Selector
• JMS Selector
• Message Body XPath Selector
• Application Context XPath Selector

To add a configuration, right click on Selectors in the Configuration Repository view and select the Add Configuration option. The required selectors can be defined and saved as a Named Configuration using this dialog box displayed in the figure below.

To use the selector on the route being used, navigate to the Selectors tab in the Route properties section and select the Named Configuration from the drop down menu in the property Configuration. The fields of the properties entered are grayed, as shown in the figure below so that they can not be edited. The properties entered are selected at runtime.

Transformation Configuration (Route / App-Context / XSLT Transformations)

Transformation configurations consist of the three types of configurations given below:

• Message transformation configurations used by routes
• Application context transformation at output ports
• XSLT component transformation

To define a Transformation Configuration, right click on Transformation in the Configuration Repository view and select Add Configuration option, as shown in the figure below.

If the Use Custom XSL option is selected, on clicking Finish a new dialog box (Custom XSL dialog) is displayed. Provide custom XSL and other configuration details and click on Ok to save the configuration as a Named Configuration, as shown in the figure below.

If the Use Custom XSL option is not selected, the Mapper project will be opened. Enter both Input and Output schemas and save the transformation. This transformation will then be saved as a Named Configuration.

To use the Transformation Named Configuration, right click on a route and select the Configure Transformation > Use Named Configuration option, as shown in the figure below.

A dialog box is displayed where the configuration to be used can be selected, as shown in the figure below.

Select the configuration and click on OK. The configuration selected will be applied on the route. The route is shown in bold indicating the Transformation. The route name is shown in bold indicating the Named Configuration used, as shown in the figure below.

Transformations that are already defined on a route can also be saved in the Configuration Repository. To save a route's transformation as a Named Configuration, right click on the route and click on Save Configuraiton As.. as shown in the figure below.

The Save Transformation Configuration dialog is opened. Provide a name for the configuration and save. A new Transformation Configuration will be added to the Configuration repository and the route name will be shown in bold to indicate that a named configuration is used

Port Configuration

Port Configurations point to messaging configurations that are used by the input and the output ports of components within Event Processes.

An input port configuration stores the properties given below:

• Is Transacted
• Transaction Size
• Number Of Sessions
• Acknowledge Mode
• Message Selector
• Use Durable Subscription
• Subscription Name

An output port configuration stores the properties given below:

• Time To Live
• Message Priority
• Persistent Messages

In the Configuration Repository view, right click on Port and select the Add Configuration option to define a named configuration port, as shown in the figure below.

Provide details of the configuration name, environment, port type and destination type and click Next.

• Provide the port messaging configurations such as transaction details, Number of Sessions, message selector and so on and click Finish to save the configuration as a Named Configuration as shown in the figure above.
• Once Named Configurations are added to the repository, a User has the choice to either define Port properties or to refer to an existing Port Named Configuration of the same type. This option is provided in the Messaging tab of Port properties.
• In the figure below, when the input port of a component (chat2) is selected, the property Configuration lists all the available input port Named Configurations. By default, no Named Configuration is used and the property is set to <None>.
• When a configuration is selected, the configuration details are loaded and the property fields are then grayed out to prevent further editing.

Workflow Configuration

Workflow Configurations point to workflow properties used by ports of component instances within Event Processes. A workflow configuration can define the type of workflow to be tracked at a port (such as None, Workflow Item or Workflow End).

Workflow configurations also define the workflow data type to be used for the workflow which, in turn, is used to define the type of data tracked. Workflow data type can be a combination of one or more of the data types given below:

• Message Header
• Message Body
• Attachments
• Application Context

To define a Workflow Configuration, right click on WorkFlow in the Configuration Repository view and select the Add Configuration option. Enter the configuration name, select the environment and click the Next button. Enter values for Work Flow Configuration and click Finish to save as the Named Configuration, as shown in the figure below.

To use the Workflow Named Configuration, select a component port and in the Properties view. Select the configuration as shown in the figure below. The configuration will be applied to the selected port.

Runtime Argument Configuration

Runtime Argument Configurations refer to the runtime arguments used by component instances within Event Processes. A runtime argument configuration defines a set of name-value pairs that are used at the time of launching the service/component instances. The set of allowed values for names used within these runtime argument configurations depend on the service for which the configuration is being created.

For example, a runtime argument configuration created for the Feeder component has only two runtime arguments, JVM_PARAMS and JAVA_HOME, where the User can define the values. On the other hand, a runtime argument configuration created for the Sender component will have several additional runtime arguments such as totalMessageCount, isTransacted, transactionSize, msgSize and so on.

To add Runtime Arguments Named Configuration, right click on Runtime Arguments in the Configuration Repository view and select the Add Configuration option. A dialog box is displayed as shown in the figure below.

In addition to basic details such as the configuration name and environment, this page contains the Guid and Version fields.

Few components like Sender, Receiver and so on contain component specific runtime arguments. To provide these component specific runtime arguments the User must select the components Guid and Version. If no Guid and Version are selected, then the common runtime arguments will be shown on the next page.

Click Next to provide values for runtime arguments and click Finish to save the configuration, as shown in the figure below.

If the Runtime Argument value has space(s) between the names in the path, encapsulate the value within double quotation marks.

Example

 -Djava.ext.dirs="C:\Program Files (x86)\Java\jdk1.8.0_121\jre\lib\ext\;D:\sources\trunk\installer\esb\lib\ext"

In the above example, there are spaces between the term "Program Files (x86)".

To use Runtime Argument Named Configurations, select a component and in the Properties view, move to the Runtime Arguments section.

The property Configuration lists all available Runtime Arguments configurations. Select the configuration. Properties corresponding to the configuration are loaded automatically. The properties entered are grayed out to prevent further editing, as shown in the figure below.

Connection Factory Configuration

Connection Factory Configurations point to connection factory properties used by component instances to create a connection to Peer Servers. A connection factory configuration defines a set of name-value properties that are used by the component at the time of creating a connection to the Peer Server.

To add a Connection Factory configuration, right click on Connection Factory and select Add Configuration as shown in the figure below.

Provide a name for the configuration on the details page. Click Next to add Connection factory configurations. Add the desired properties using the Add button provided in the configuration page and click Finish to save the configuration, as shown in the figure below.

Once the configuration is saved in the repository, it can be used to provide Execution Details of a Service Instance. To use a named configuration for the Connection Factory properties, select a Service Instance and go to the Execution tab in the properties view. The property Configuration lists the names of all available Connection Factory configurations. Select the configuration to be used and the corresponding Connection Factory properties will be fetched from the named configuration selected.

These properties can be viewed in the Connection Factory Properties table as shown in the figure below.

When the Connection Factory named configuration is used, the properties in the named configuration are grayed out to prevent editing. To modify these properties, edit the configuration from the Configuration Repository view if the changes need to be applied to all the components using that particular configuration or use the default configuration (with the required values).

Destination Configuration

Destination configuration represents the JMS destination configuration provided for a port. Contains the following information

• Destination Type
• Custom Destination
• Encryption Algorithm
• Encryption key
• Allow padding key
• Initialization vector(Optional based on Algorithm selected)

To add a destination named configuration, right click on Destination in the Named Configuration repository and select Add

To define a Destination Configuration, right click on Destination in the Configuration Repository view and select the Add Configuration option. Enter the configuration name, select the environment and click the Next button. Enter values for Destination Configuration and click Finish to save as the Named Configuration, as shown in the figure below.

To use the Destination Named Configuration, select a component port and in the Properties view. Select the JMSDetination as shown in the figure below. Select the list from Configuration and the configuration will be applied to the selected port.

MessageFilters Configuration

MessageFilters Configurations point to message filter properties used by ports of component instances within Event Processes. A MessageFilters configuration can define multiple filters with name and their corresponding values that need to be set on messages sent out of the component (configuration set on output port) and also based on which the messages will be filtered at the receiving component (configuration set at input port).

To define a MessageFilters Configuration, right click on MessageFilters in the Configuration Repository view and select the Add Configuration option. Enter the configuration name, select the environment and click the Next button. Enter values for MessageFilters Configuration and click Finish to save as the Named Configuration, as shown in the figure below.

To use the MessageFilters Named Configuration, select a component port and in the Properties view. Select the MessageFilters configuration as shown in the figure below. The configuration will be applied to the selected port.

Defining and Using Configurations

This section explains how Users can create new configurations, modify existing ones and use the configurations already defined at the time of orchestration:

Creating / Modifying Configurations

Configurations can be added/modified to the named configuration repository by using the (two) methods described below:

Configuration Repository view in eStudio

Users can create named configuration from eStudio 'Configuration Repository' view. This process is explained above while explaining the types of configurations.

In order to modify an existing named object, right click on the named configuration present in the named configuration repository and choose Edit.

If a configuration is edited at runtime it can require that the Component or the Event Process be restarted.

'Save As Named Configuration' in component CPS

At various locations in the Custom Property Sheet (CPS) of components, an option is provided to save the configurations defined in the CPS as a named object, as shown in the figure below. When this option is chosen, the configuration defined in the CPS of the component will be saved against the given named object at the time of closing/finishing the CPS wizard.

Exporting /Importing Named Configuration

1. Local Disk

To export, right-click on named object and select the Export to Local Disk option to export the configuration to the local disk. The configuration will be stored in a zip file.

To import, Right click on named object and select the Import from local disk icon as shown in the figure below and select the named configuration zip file from the local repository.

2. Offline mode

To export, right-click on named object and select the Export to offline mode to export the Named Configuration Offline.

For importing to Server from offline mode, the server should be added in the list of connection available for offline mode, by default local server enterprise server will be in to list. In offline Named Configuration repository right click on the intended named object and select Export to Server and select server from the list of servers connections available.

Deleting / Renaming Configurations

Named objects can be deleted/renamed using the Configuration Repository view in eStudio. Right click on the desired named object in the Configuration Repository view and choose the appropriate option from the pop-up menu, as shown in the figure below.

Creating New Configurations from Existing Configurations

To create new named objects as duplicates of existing named object the Save As option can be used by right-clicking the existing named object, as seen in the figure below.

Using Configurations From Repository View

Using the configurations is explained in detail while explaining Configurations Types that is from the properties panel of the respective configuration. The other way of using the named configuration is from Configuration Repository view.

The configuration repository view in eStudio provides an Assign To command which is available upon right-clicking a named object, using which users can assign the selected named configuration to specific artifacts shown in a selection list.

For example, when a User executes the Assign To command for a route configuration created for the development environment, a list of all routes belonging to the Event Process within the development environment as shown in the figure below.

Users can select the routes to which this configuration is to be applied and click the OK button.

1. The Assign To option will not list an entry if the configuration entered is already assigned.
2. The Assign To option is not present for the Service and the Resource configurations since these cannot be directly assigned from this view.
3. The Assign configuration dialog only lists those Event processes that are not running and those which have same target environment as the selected configuration.

Finding and Clearing Usages

To find the list of artifacts (routes, ports, services) using a particular named object, a User should right click on the named object in the Configuration Repository view and select the Find Usages… option. This action will show a list of all artifacts using the named object.

A sample of configuration usage is shown in the figure below.

To clear the usages of this named object, right click on the named object in the Configuration Repository view and select Clear Usages… option and select the artifacts from which the usage should be cleared and click OK as shown in the figure below. The configuration name for these artifacts will be set to None and the affected Event Processes will be automatically saved/deployed to the server.

The Clear Usages option is not present for the Service and the Resource configurations.

Validating Configurations

At various stages during the creation/running of an application, a check is made to confirm the presence of all named objects used in the Event Process. If any of the named objects is found missing from the registry, an appropriate error message is thrown and the operation is not allowed to execute unless this problem is resolved. The various stages at which this check is made are while:

• Saving the Event Process
• Connectivity Resource Check (CRC)
• Launching the Event Process
• Synchronizing the Event Process

In addition to the above, a check is made to confirm the presence of all named objects used by a service instance at the time of starting the service instance. This check confirms the presence of all named configurations used within the Custom Property Sheet [CPS] of that particular service instance and the named configurations used at the ports of that service instance.

Error Handling

Though the CRC check may be fine, there might be some runtime errors that may crop up with regard to named configurations. For example, a named object might be incorrectly referenced. An example of this is when a named object representing the SSL configuration for a service instance might be specified at a place where the Proxy configuration is expected. Such issues will be resolved at run-time when the Event Process/Service Instance is launched. An exception message will be shown/logged, wherever possible.

Resolving Named Configurations

Since Event Processes are configured to use named configuration features, they may refer to many named objects on ports, routes or service instances. All these named objects have to be resolved using their actual configuration [Semantic check please] before launching the Event Process. These named objects are resolved during runtime of the respective artifacts as described below.

Service Instances

The named objects referred from the Custom Property Sheet (CPS) of components are resolved at the time of launching/synchronizing the Event Process (and not at the time of CRC). Once these service instances have been launched, they continue to use the configuration data from the registry at the time they were launched. For the changes made to named objects used by service instances to take effect, these service instances have to be restarted either by stopping all the service instances and starting them again or by restarting the Event Process. To summarize, service instance CPS configurations are resolved during:

• Launching the Event Process
• Synchronizing the Event Process
• Starting a stopped service instance

During the synchronization of Event Processes, changes made to named objects used by running the service instances do not take effect. Only those changes made to named objects used when the service instances are stopped take effect.

Port Instances

As ports are bound to service instances, the named objects referred from port instances of services follow exactly the same rules for getting resolved as those followed by the named objects referred from the CPS of components. Please refer to the Service Instances section above.

Routes

The named objects that are referred from routes are resolved at the time of launching/synchronizing Event Processes. Note: During synchronization of an Event Process, changes made to named objects used by routes that already exist will not take effect. Only those changes made to named objects used by newly created routes take effect.

Security

The permissions given below are available at the Enterprise Server Level to govern the usage of named configurations within Event Processes. By default, only the administrators' group is allowed to perform the actions protected by these permissions. Administrators can also assign permissions to other Users to perform one or more of these actions. Navigate to the Security -> Global Permissions page in the dashboard to view and modify these permissions.

Permission to view and use named objects

This permission governs whether a particular User has permission to view the list of named configurations present in the Server. The permission also governs whether those named objects can be used within Event Processes.
When a User who does not have this permission tries to save/launch/synchronize an Event Process that uses named configurations, an exception will be thrown stating that the User is not allowed to use the named objects from the configuration repository.

Permission to add and/or delete named objects

This permission governs whether a particular User has the permission to add and/or delete named objects from a configuration repository.

Permission to modify existing named objects

This permission governs whether a particular User has the permission to edit/modify the data stored within a named object.

Points to Note

• If an Event Process uses a Named Configuration, when it is export all the Named Configurations used by the Event Process will be listed. Users can select the configurations that are to be included in the Event Process export, as shown in the figure below.

• If an Event Process uses Named Configurations and if these are deleted from the repository, then during the export of the Event Process a visual symbol indicates that the Names Configurations are missing from the repository. The figure below shows a configuration called testRuntime that is missing from the repository.

When an Event Process is imported, all configurations present are listed. If the configurations already exist then they will be shown in red color and the user is provided with options to either overwrite or not import the configuration displayed.

• To view all the configurations used in an Event Process, right-click on Event Process and select the Show Configuration Usages option as shown in the figure below.

All the configurations used are displayed, as shown in the figure below.

• The Undo support is present for the Assign To and Clear Configuration actions. This option is present in the Configuration Repository view toolbar and displayed in the toolbar only when a configuration is assigned from this view. Please refer to the figure below.
  Note: This option should be used with care.

Refer the Defining Named Configuration and utilize EPLCM section to work with a sample.