Specifying promotion environments

You use the <environments> element to specify the details of the environments to which you want to promote WSRR entities. As part of the environment information, you supply details of the target WSRR instance associated with that environment.

If a WSRR entity undergoes a lifecycle transition that is associated with one of the promotion environments defined in the <environments> element, that entity is promoted to the target WSRR instance that you specify, along with all entities to which it is related. Transitions are associated with promotion environments using the <transitions> element; see the "Specifying promotion transitions" Related link for details.
Note: To use custom classifications as promotion environments, these classifications must sub-class Environment from the Governance Policy Taxonomy classification system.
The <environments> element has the following structure:
<environments>
  <environment>
     ... elements specifying the details of a promotion environment ...
  </environment>
         .
         .
         .
  <environment>
     ... elements specifying the details of a promotion environment ...
  </environment>
</environments>
Each <environment> element specifies the details of one promotion environment.
Note: If security is enabled on the target WSRR instance, then promotion must be performed by a user that has the J2EE administrator role.
The <environment> element has the following attribute:
Attribute Description
name A name that uniquely identifies the promotion environment.
The <environment> element contains the <promotion>, <servers>, and <security> elements.

<promotion>

This element provides details of the promotion, and is required.
The <promotion> element contains the following elements, which must be specified in the order shown:
Element Description
<type> The type of promotion that is performed. This element must be set to one of the following values:
  • sync: The promotion is performed as soon as the lifecycle transition is made (that is, in the same transaction). If the promotion fails for any reason, the transition also fails (and the transaction is rolled back). This type is deprecated in favor of sync-minimal, and might be removed in a future release.
    Note: For compatibility with releases prior to WSRR V8.0, the word sync-optimized can be used as a synonym for sync in <type> element values. This option is only available from WSRR 7.5.0.2 onwards.
  • sync-optimized: The promotion is performed in the same way as sync, but provides an optimized data transfer path that avoids the use of a temporary Derby database in order to improve the performance of promotions.
  • sync-minimal: The promotion is performed in the same way as sync, but in some cases can result in fewer items being promoted. If items in the governed collection being promoted have dependencies on items in separate governed collections, then only the items in the governed collection and items that satisfy dependencies from the separate collection are promoted. In non-minimal promotion, by contrast, both collections are promoted. Items that satisfy the dependency are marked with a system property on the target WSRR to identify the governed collection they belong to on the governance WSRR. If that governed collection is promoted subsequently, the marked item is replaced by the item from the governance master.
  • async: The promotion is performed at a later time, as part of a scheduled task (see the "Asynchronous promotion and scheduled tasks" Related link for details).
    Note: The current asynchronous promotion capability is deprecated, and will be removed in a future release.
  • manual: The information and content required to perform the promotion is written to a file. You must then manually import the file into the target WSRR system. If you specify this option, you must also provide <filepath> and <filename> elements. This type is deprecated in favor of manual-optimized-minimal, and might be removed in a future release.
  • manual-minimal: As for manual promotion, the information and content required to perform the promotion is written to a file. Fewer items are promoted, as described for the sync-minimal promotion type.
  • manual-optimized: As for manual promotion, the information and content required to perform the promotion is written to a file. The contents of the file are a compressed serialization of the object being promoted, and cannot be edited. If manual changes need to be made to the promoted items, standard manual promotion should be used. This type is deprecated in favor of manual-optimized-minimal, and might be removed in a future release.
  • manual-optimized-minimal: As for manual promotion, the information and content required to perform the promotion is written to a file. The contents of the file are a compressed serialization of the object being promoted, and cannot be edited. Fewer items are promoted, as described for the sync-minimal promotion type. This option is only available from WSRR 8.0.0.1 onwards.
This element is required.
<filepath>

The directory path to the file used to store the promotion data.

You can specify a WebSphere® Environment variable (which is configured within WebSphere Application Server in the Node scope for each Node within the system). This variable is used to determine the filepath used to store the promotion data. The format of this variable is ${variable_name} where variable_name is a valid WebSphere Environment variable name.

The path specified either directly or by using an WebSphere Environment variable must be valid for the operating system you are using, and must end in "/" or "\".

This element is required if the value of the <type> element is manual.
<filename> The name of the file used to store the promotion data. This element is required if the value of the <type> element is manual.

When a promotion is performed, if the file name already exists on the file system, a time stamp is added to the file. The time stamp is in the format yyyyMMddHHmmssSSS.

If you include the special tag %TS% in the file name, a time stamp is placed at this position, regardless of whether or not the file already exists. If the special tag is not included, and the file already exists, the time stamp is added at the end of the file name before the file extension.
Examples:
<promotion>
  <type>manual</type>
  <filepath>c:/temp/</filepath>
  <filename>promote.zip</filename>
</promotion>
<promotion>
  <type>sync</type>
</promotion>
In this example, a time stamp is added to the front of the file name: 
<promotion>
  <type>manual</type>
  <filepath>c:/temp/</filepath>
  <filename>%TS%promote.zip</filename>
</promotion>
In this example, a WebSphere Environment variable called MY_PROMOTION_DATA_DIR (which is configured in WebSphere Application Server as having a value of /tmp/promotion_data/) is used to determine the filepath that will be used to store the data. With this configuration the data will be stored in a file /tmp/promotion_data/promote.zip on the WebSphere Application Server system.
<promotion>
  <type>manual</type>
  <filepath>${MY_PROMOTION_DATA_DIR}</filepath>
  <filename>promote.zip</filename>
</promotion>

<servers>

This element provides details of the servers to which content is promoted, and is required if the value of the <type> element is either sync or async.
The <servers> element contains the following element:
Element Description
<server> Each <server> element provides details of one server to which content is promoted. You must specify at least one <server> element. The <server> element has the following attributes:
  • name: the server host name or IP address.
  • port: the server bootstrap address. The port is the BOOTSTRAP_ADDRESS on the WebSphere Application Server.
If you are promoting to a cluster, specify one <server> element for each server in the cluster.
You must not specify more than one server for a promotion environment unless the servers are configured as a cluster, otherwise entities are promoted only to the first server in the list. If you want to promote to multiple servers that are not configured as a cluster, you must define a separate environment for each server and specify multiple target environments within the <transitions> element of the configuration.

In a cluster environment, if all cluster members are specified, WSRR will succeed in promoting to a cluster member if at least one of the servers is running, eliminating a single point of failure. There is no guarantee of any particular order in which the server list will be processed. WSRR might try to connect first to any of the servers in the list, and try to connect to any of the others in the list if the first server is not available.

Example for a stand-alone WebSphere Application Server:
<servers>
  <server name="myServer1.hursley.ibm.com" port="2809"/>
</servers>
Example for a WebSphere Application Server cluster:
<servers>
  <server name="myClusterServer1.hursley.ibm.com" port="9809"/>
  <server name="myClusterServer2.hursley.ibm.com" port="9809"/>
  <server name="myClusterServer3.hursley.ibm.com" port="9809"/>
</servers>

<security>

This element provides security information for the WebSphere Application Server or cluster to which content is promoted, and is required if security is enabled. If you omit the <security> element or the enabled attribute, it is assumed that security is disabled.
The <security> element has the following attribute:
Attribute Description
enabled Specifies whether security is enabled on the server or cluster. The value of this element must be one of the following:
  • "true": security is enabled.
  • "false": security is disabled.
This attribute is required.

Note that if you supply a value of "false", any subelements specified in the <security> element are ignored.
The <security> element contains the following elements, which must be specified in the order shown:
Element Description
wsrrUser The user ID for accessing the server or cluster. This element is required. The user must be listed in the J2EE Administrator role on the target WSRR
wsrrRealm The name of the target realm.

For example, if the target WebSphere Application Server instance is configured to use a Lightweight Directory Access Protocol (LDAP) server as its user registry, the name of the target realm is the <hostname>:<port>, where <hostname> is the host name or IP address of the LDAP server and <port> is the port on which the LDAP server is listening. If the target WebSphere Application Server instance is configured to use local operating system user registry, then the target realm is the computer name. If the target WebSphere Application Server instance is configured to use Federated repositories, then the realm is the target server Realm name that was specified for Federated repositories.

This element is optional and needs only be configured if the target realm is different to the current realm, that is, the target server is configured to use a different user registry to the current server.

Note: If the current and target realms are different, you must disable transaction security on your WebSphere Application Servers; see Configuring the Transaction Service for details.
wsrrPassword The password for accessing the server or cluster. This element is required.
Examples:
<security enabled="true">
  <wsrrUser>user1</wsrrUser>
  <wsrrPassword>password1</wsrrPassword>
</security>
<security enabled="true">
  <wsrrUser>user1</wsrrUser>
  <wsrrRealm>server1:389</wsrrRealm>
  <wsrrPassword>password1</wsrrPassword>
</security>

Example of a complete <environment> element

This example defines a "Development" promotion environment. If a WSRR entity undergoes a life-cycle transition that is associated with this environment in the <transitions> element, that entity is promoted to the WSRR instance on the server myServer.hursley.ibm.com at port 2809, using the specified authentication details.
<environment
  name="http://www.ibm.com/xmlns/prod/serviceregistry/6/1/GovernanceProfileTaxonomy#Development">
  <promotion>
    <type>sync</type>
  </promotion>
  <servers>
    <server name="myServer.hursley.ibm.com" port="2809"/>
  </servers>
  <security enabled="true">
    <wsrrUser>user1</wsrrUser>
    <wsrrPassword>password1</wsrrPassword>
  </security>
</environment>
Parent topic: The promotion properties configuration file format
Related concepts:
Asynchronous promotion and scheduled tasks
Related reference:
Specifying promotion transitions