Red paper

Red

paper

Kurt Baumann

SOA Runtime Metadata Management using WebSphere Service Registry and

Repository and WebSphere MQ File

Transfer Edition

This IBM® Redpaper™ provides an automated solution to asynchronously promote centrally managed service artifacts from a governance production environment to runtime environments. The solution combines the promotion capability of WebSphere® Service

Registry and Repository with the file transfer capability of WebSphere MQ File Transfer

Edition.

This paper contains the following sections:

򐂰 Solution overview

Discusses the solution at a high level. We describe the essential components of both products, and we show how they integrate.

򐂰 Installation

Lists the products to be installed on the separate environments. The section ends with simple test cases to verify that the installed products integrate.

򐂰 Configuration and customizing

Provides a detailed description of all required steps to enable the automated promotion process without any user interaction. The section ends with simple test cases to verify that promotion works.

򐂰 Running the automated promotion process

Executes various scenarios to see how promotion works from end-to-end.

򐂰 Enhancements

Introduces two additional features: archiving promotion .zip files and promoting to multiple runtime production environments.

ibm.com/redbooks 1 © Copyright IBM Corp. 2010. All rights reserved.

򐂰 Troubleshooting

Shows the various log files that you can use, if problems occur.

Solution overview

This section provides an overview of the automated solution to asynchronously promote service artifacts from the governance production environment to the runtime environments.

We address the following topics in this section:

򐂰 Why clients need to use manual promotion?

򐂰 How does manual promotion without user interaction work?

򐂰 What aspects of WebSphere Service Registry and Repository do we use?

򐂰 What aspects of WebSphere MQ File Transfer Edition do we use?

Using manual promotion

Promotion

allows you to centrally manage service artifacts relating to multiple runtime environments by enabling you to transfer content automatically to these runtime environments and import the content into the WebSphere Service Repository and Registry runtime instances in response to specific governance life cycle transitions. We recommend that clients make use of synchronous promotion where possible to ensure that the content of the runtime instances is synchronized with the content of the governance production instance.

However, you might not be able to keep the content of the runtime instances synchronized with the content of the governance production instances for a number of reasons:

򐂰 In situations where a single transition triggers promotion to multiple runtime environments, all the WebSphere Service Repository and Registry runtime instances must be available when the transition occurs for promotion to complete successfully. If even one of the runtime environments is unavailable for any reason (currently down, network outage, maintenance of a WebSphere Service Repository and Registry runtime instance, and so forth), the promotion to that runtime environment fails and causes the rollback of the transaction for the transition. The transition operation fails on the governance production instance. In this situation, the relevant service artifacts have not been promoted to any of the runtime environments, and the governance life cycle transition does not succeed until all the runtime environments are available. This result is unacceptable to certain clients, and these clients must use manual promotion in this case.

򐂰 The network connection can be slow and unreliable in situations where a runtime environment is hosted in a data center in a remote geographical location. Manual promotion might be required to ensure that the governance life cycle transition is completed and that the data is transferred successfully.

The problem with manual promotion is that it requires user intervention to copy the generated compressed file from the governance production environment to the runtime environment and then to import the compressed file into the WebSphere Service Repository and Registry runtime instances. The purpose of this IBM Redpaper is to explain how you can use

WebSphere MQ File Transfer Edition to automate this process.

2 SOA Runtime Metadata Management using WebSphere Service Registry and Repository and WebSphere MQ

Asynchronous promotion capability: The current asynchronous promotion capability of

WebSphere Service Repository and Registry is deprecated and might be removed in a future release. If you require this capability, use manual promotion instead, and import the generated promotion files into the target environments.

This paper uses manual promotion, but it provides an automated solution to promote service artifacts asynchronously without user interaction. In this paper, the term

asynchronous

relates to the automated promotion process using WebSphere MQ File

Transfer Edition and not to the deprecated asynchronous promotion of WebSphere Service

Repository and Registry.

Using manual promotion without user interaction

Manual promotion

of WebSphere Service Repository and Registry writes the relevant objects and their associated metadata to a file on the file system of the governance production environment. WebSphere MQ File Transfer Edition detects the file, transfers the file to a runtime environment, and triggers the import into the runtime environment. The runtime environment is now synchronized with the governance production environment. WebSphere

MQ transports the files containing service data in the form of messages across the network.

Figure 1 on page 4 shows the essential parts of the solution. The governance life cycle is a predefined set of states and transitions. The users apply the life cycles to service artifacts to indicate their progress in the development process. Selected governance life cycle transitions trigger the service data promotion.

Promotion

is a feature to push service artifacts from a single service registry to multiple service registries. Three environments exist within these two axes:

򐂰 The governance production environment (WSRRGM) is the master of all service-related data. The user transitions the service data through the states of the life cycle in this central environment. This environment is also called

governance master

or

governance registry

.

򐂰 The runtime staging environment holds the service artifacts that are related to its environment. You can use the staging environment for testing or training.

򐂰 The runtime production environment holds the service artifacts that are related to its environment. Other productive applications can retrieve metadata from a desired service or can execute dynamic service endpoint lookups.

SOA Runtime Metadata Management using WebSphere Service Registry and Repository and WebSphere MQ File

Life cycle

Staging

WSRRSTAG

WebSphere Service

Registry and Reposito ry

WebSphere File Transfer Editi on

Client

WMQFTE Agent

3

Production

WSRRGM

WebSphere Se rvice

Regi stry and Repository

1

WebSphere Fil e Transfer Editi on

Server

WMQFTE Age nt

WebSphere MQ

Queue Manager

2

WSRRPROD

WebSphere Service

Reg istry and Repository

WebSphere File Transfer Edition

Cli ent

WMQFTE A gent

3

Figure 1 Solution overview

The promotion process involves three steps. These steps correlated to the numbers in

Figure 1:

1. The user transitions services through the states of the relevant governance life cycles on the governance production instance. At a certain point in time, a specific governance life cycle transition triggers an export of the related service artifacts and service metadata in the promotion compressed file. The compressed file is stored in a specified promotion directory on the governance production environment. If the export terminates successfully, the governance life cycle transition is committed, and the relevant objects are now in the next governance state.

2. WebSphere MQ File Transfer Edition detects and transfers the promotion compressed file from the agent running on the governance production environment to the agent running on the runtime environment, either staging or production.

3. WebSphere MQ File Transfer Edition triggers the import of the promotion compressed file into the WebSphere Service Repository and Registry runtime instance. Now, the

WebSphere Service Repository and Registry runtime instance is synchronized with the governance production instance.


The automated asynchronous promotion process involves three WebSphere products:

򐂰 IBM WebSphere Service Repository and Registry has the capability to centrally store and manage service artifacts relating to multiple runtime environments. A key aspect of service management is the governance enablement profile. It defines the governance model entities and the governance life cycles. In this paper, we use the capabilities to govern, classify, export, and import service artifacts and service metadata.

Default governance enablement profile: The solution in this paper uses the default governance enablement profile. The default governance enablement profile defines two runtime instances in the promotion properties file: staging and promotion.

򐂰 IBM WebSphere MQ File Transfer Edition for z/OS® provides a reliable managed file transfer solution for transferring files between heterogeneous IT systems. The WebSphere

MQ File Transfer Edition agent represents the endpoint for file transfer operations and uses the WebSphere MQ network to execute the message-based file transfer. Therefore, each agent must connect to the queue manager. In this paper, we use the file transfer capability to transfer the exported promotion compressed files from the governance production environment to the runtime environments.

򐂰 IBM WebSphere MQ for z/OS enables programs to communicate across a network of components (processors, operating systems, subsystems, and communication protocols) by using a simple and consistent application programming interface (API). This product is a messaging and queuing middleware, with publish/subscribe capabilities. In this paper,

WebSphere MQ File Transfer Edition uses the messaging and queuing middleware to transport the promotion compressed files between the governance production environment and the runtime environments.

Using WebSphere Service Registry and Repository

Figure 2 on page 6 shows the architecture of WebSphere Service Registry and Repository.

We describe each component we use to promote the service data.


User

Interface

Web

Eclipse

Plug-in

Programming

Interfaces

Java

External

Systems

ESBs

Process

Servers

Appliances Monitors

SOAP REST

Third

Party

Registries and

Repositories

Events

Generated

Extensions and

Integrations

Governance

Transition

Validate

Notify

Impact Analysis

Audit

Life cycle

Validators

Admin

JMX

Import/Export

Configure

Access Control

Classifications

Registry and Repository

Create

Retrieve

Update

Delete

Query

Validation

Notification

Events Generated

Content Models

RDB

WebSphere Application Server

Operating System

Figure 2 Overview of the WebSphere Service Repository and Registry architecture

Governance

Governance

provides the capability to manage service artifacts based on defined processes.

The service artifacts are called the

governance entity model

. The processes are called the

governance life cycle model

. The governance enablement profile (GEP) defines the entity model and the life cycle model.

The entity model is a data model. The data model defines the types of governed service artifacts, for example, service, service version, or service endpoint.

The governance life cycle model is a state engine. The state engine defines the states that a governed entity goes through, normally from identification to retirement. In this paper, we use two life cycles:

򐂰 The service-oriented architecture (

SOA) life cycle

defines the state engine to govern a capability version from initially identified to retired. The entities involved are: capability version, application version, process version, and service version.

򐂰 The

Endpoint life cycle

defines the state engine to govern a service endpoint from being approved for use to retired. The entities involved are: service endpoints, MQ service endpoints, SOAP service endpoints, and extension service endpoints.

Reference: Service Lifecycle Governance with IBM WebSphere Service Registry and

Repository, SG24-7793, provides a detailed description of the governance enablement profile entity model, roles, and life cycles.


Hint: The default governance enablement profile does not use the endpoint life cycle to trigger promotion; therefore, we do not use it to trigger promotion in the scenarios described in this paper. However, this life cycle allows you to repeat the promotion to all runtime environments multiple times. You can go forward and backward between the two states

OffLine

and

Online

. Therefore, we extended the promotion properties file and added the two endpoint transitions,

ApproveForUse

and

RevokeFromUse

, but these two transitions are inactive. You can activate them by removing the XML

comment tag. For more information about the promotion properties file, see “Adjusting promotion properties” on page 18.

Admin

The administration interface supports loading the governance enablement profile (which includes classification, life cycles, and entities) and importing and exporting service artifacts for exchange with other instances of WebSphere Service Registry and Repository. The command-line interface (CLI) supports two scripting languages: Jython and Jacl (Java TCL).

In this paper, we use this interface to import the promotion compressed file.

Jython: Both scripting languages have been supported since WebSphere Application

Server V5.1. But, as of today, Jython is the strategic direction for the administration scripting language for WebSphere Application Server, because future enhancements of the scripting language focus on the use of Jython.

Registry and repository

The

repository

allows users to store, manage, and query service artifacts that contain service information. The

registry

allows users to add and query service metadata as properties, relationships, and classifiers.

User interface

The web user interface is deployed with the WebSphere Service Registry and Repository run time. The web user interface is the key interface for users in various roles to interact with the

WebSphere Service Registry and Repository, for example, to transition services and import or export promotion data.

Using WebSphere MQ File Transfer Edition

Figure 3 on page 8 shows the architecture of WebSphere MQ File Transfer Edition. We

describe each component that we use to promote the service data.


WMQFTE

Agent

Queue Manager Queue Manager

WMQFTE

Agent requests

Coordination

Queue Manager

(WebSphere MQ V7) subscribes

Commands and

WebSphere

MQ Explorer subscribes

External Applications

Monitoring

Auditing

JDBC

Audit

Log

Figure 3 Overview of WebSphere MQ File Transfer Edition architecture

Agent

The

file transfer agent

is a Java™ Virtual Machine (JVM) process. It executes the file transfer and is either the sending or the receiving endpoint of the file transfer. It uses the WebSphere

MQ network as the messaging middleware to transport the files.

The sending agent reads the file from the file system and sends the file to the receiving agent in the form of MQ messages. On each system, an agent that can transfer files to or from other systems is running. To transfer the files using messages, each agent requires a queue manager, which is called the

agent queue manager

.

There are two WebSphere MQ File Transfer Edition products, either client or server:

򐂰 In a server edition, the agent connects to its queue manager through an MQ binding connection. In that case, the agent must be located on the same system as the queue manager. The server agent can also use the less efficient MQ client connections.

򐂰 In a client edition, the agent connects to its queue manager through an MQ client connection. Client agents can be located either on the same system as the queue manager or on another system.

For the solution that is described in this paper, the agent running on the governance production environment uses an MQ binding, and the agents running on the runtime environment use MQ client connections to connect to the queue manager.


Queue manager

WebSphere MQ File Transfer Edition uses WebSphere MQ to communicate between its components and transfer files. Three types of logical queue manager roles exist. One physical queue manager can perform all three logical roles at one time:

򐂰 The

coordination queue manager

is the central point within the MQ network. It collects and broadcasts file transfer status and audit information. It also gathers information about all agents.

򐂰 The agent uses the

agent queue manager

to transfer files and communicate with the coordination queue manager. It hosts a set of uniquely named queues for each agent.

򐂰 The command-line tools and the MQ Explorer use the

command queue manager

to communicate with the agents.

For the solution that is described in this paper, we use only one queue manager that is running on the governance production environment. The queue manager is called QM_GM .

Command-line tools

The command-line tools provide a set of programs to configure and operate WebSphere MQ

File Transfer Edition. You can obtain a list of all the commands in the [MQFTE_HOME]\bin directory:

򐂰 You use the configuration commands to configure the file transfer infrastructure: fteSetupCoordination , fteCreateAgent , fteDeleteAgent , fteSetupCommands , and fteChangeDefaultConfigurationOptions . These commands relate to the three types of queue managers: coordination, agent, and command.

򐂰 You use the operation commands to execute the file transfers. You can start and stop agents. You can create, schedule, or cancel a file transfer. A monitor allows you to observe a directory and initiate a file transfer when a specific file arrives. You can use other commands to list agents, agent details, and monitors.

Additionally, the command fteAnt allows you to execute ant scripts. The command-line tools provide specific ant tasks that are related to file transfer. These tasks allow you to transfer files or execute scripts or programs on remote systems.

For the solution that is described in this paper, you use the command to start and stop the agents and create the monitors. You use fteAnt to copy the promotion compressed file to the runtime environments and execute remote calls.

MQ Explorer

The WebSphere MQ File Transfer Edition graphical user interface (GUI) plug-in extends the

MQ Explorer. This plug-in allows you to execute and monitor file transfers.

Installation

In this section, we list the products that we have installed on the platforms for the solution that we described in the previous section. Windows® XP Professional, Service Pack (SP) 3 is installed on all platforms. At the end of this section, we provide additional information regarding installation.


We describe the following topics in this section:

򐂰 Installed products

򐂰 Additional information

򐂰 Verification of installation

򐂰 Troubleshooting

Installed products

We do not provide step-by-step instructions for the product installation. We assume that you have followed the installation instructions contained in the product installation packages.

Figure 4 shows the environments with the installed products.

Staging

Life cycle

Production

WSRRGM (Windows XP Professional, SP3)

WebSphere Service

Registry a nd Repository V7.0.0.2


Server V7.0.2


Documentation and Tools V7.0.2

WebSphere MQ V7.0.1

(incl. MQ Explorer V7.0.1 and Eclipse V3.3)

WSRRSTA G

(Windows XP Professional, SP3)

WebSphere Service

Registry and Repository V7.0.0.2


Client V7.0.2

WSRRPROD

(Windows XP Professional, SP3)

WebSphere Service

Registry a nd Repository V7.0.0.2


Client V7.0.2

Figure 4 Installed products by environment

Before you start the installation, check the section “Additional information” on page 11 to

ensure that you follow the naming conventions.

Products on the governance production environment

Install the following products on the governance production environment:

򐂰 WebSphere MQ V7.0.1, including WebSphere MQ Explorer

򐂰 WebSphere Eclipse Platform Version 3.3 (included in the WebSphere MQ V7.0.1 installation package)


򐂰 WebSphere MQ File Transfer Edition Server V7.0.2

򐂰 WebSphere MQ File Transfer Edition Documentation and Tools V7.0.2

򐂰 WebSphere Service Registry and Repository V7.0.0.2

Products on the runtime environments: Staging and production

Install the following products on the staging and production runtime environments:

򐂰 WebSphere MQ File Transfer Edition Client V7.0.2

򐂰 WebSphere Service Registry and Repository V7.0.0.2

Requirement: The WebSphere Service Registry and Repository instances must be at the same version level (for example, V7.0.0.2) to support promotion between them.

Additional information

You need to follow these additional instructions, such as using these naming conventions, during installation. These hints can help you if the installation fails:

򐂰 We used the typical installation mode to install all products.

򐂰 If you install WebSphere MQ V.7.0.1 and WebSphere MQ File Transfer Edition V7.0.2 on

Windows, you require Service Pack 2 (or later). See the following links for all requirements:

– http://www-01.ibm.com/software/integration/wmq/requirements/index.html

– http://www-01.ibm.com/software/integration/wmq/filetransfer/requirements/inde x.html

򐂰 If you install WebSphere MQ Explorer V7.0, you require WebSphere Eclipse Platform

Version 3.3. You can install this product from the WebSphere MQ installation package.

򐂰 Optionally, you can install WebSphere MQ File Transfer Edition Fix Pack 7.0.2.1. See the support portal: http://www-01.ibm.com/support/docview.wss?uid=swg24025878

Naming conventions

If you are running the product installation, follow these naming conventions:

򐂰 The names for the three machines:

– WSRRGM for the governance production environment

– WSRRSTAG for the runtime staging environment

– WSRRPROD for the runtime production environment

򐂰 The name of the WebSphere MQ queue manager that you create is QM_GM . This queue manager serves as the coordination, command, and agent queue manager and runs on the governance production environment.

򐂰 The names of the WebSphere File Transfer Edition agents:

– WSRR.GM.AGENT

for the governance production environment

– WSRR.STAG.AGENT

for the runtime staging environment

– WSRR.PROD.AGENT

for the runtime production environment


Hints

One of these hints might be helpful if you have problems during the installation process:

򐂰 Your Windows user name must not be longer than 12 characters; otherwise, WebSphere

MQ trims to that length, and the file transfers fail. See this web site: http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq

.explorer.doc/e_authority_groups.htm

򐂰 Your Windows host name must not contain the underline character (_). See Chapter 2.1,

“Host Names and Numbers” at http://tools.ietf.org/html/rfc1123 . Otherwise, you get an error message during the installation of WebSphere Service Registry and Repository, and you have to provide the IP address, instead.

򐂰 You need to create the coordination queue manager that is named QM_GM before you start with the installation of WebSphere MQ File Transfer Edition. To create a queue manager, either use the WebSphere MQ Explorer, the MQ control command crtmqm , or the MQSC command DEFINE QLOCAL. For more information, see the WebSphere MQ

Information Center: http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp

򐂰 If the installation of WebSphere Service Registry and Repository stops, most probably, it was unable to install the IBM Installation Manager. Therefore, install the installation manager manually before you start with the product installation.

򐂰 You need to the binary directory of WebSphere File Transfer Edition to the PATH environment variables, for example, C:\Program Files\IBM\WMQFTE\bin . This directory contains the command-line tools.

Verifying the installation

In this section, we verify the proper installation on the governance production environment and on the runtime environments. Additionally, we execute a manual file transfer to make sure that all required product services are available and well integrated.

Important: Ensure that the queue manager and all file transfer agents have already been created and configured during product installation.

Verifying installation on the governance production environment

Execute the following steps to verify that the installed products and their provided services work properly. Before you start with the verification, restart the operating system by selecting

Start



Restart. Follow these steps:

1. Check if the WebSphere MQ and WebSphere Application Server (installed together with

WebSphere Service Registry and Repository) services are started by selecting Start

Settings



Control Panel



Administrative Tools





Services (Figure 5 on page 13).


Figure 5 Automatically started services on governance production environment

2. Check if you can log in to the web user interfaces: a. WebSphere Application Server Console, for example: https://localhost:9043/ibm/console/logon.jsp

b. WebSphere Service Registry and Repository Console, for example: https://localhost:9443/ServiceRegistry/logon.jsp

3. Check if the queue manager is running (Example 1).

Example 1 Display queue manager

C:\>dspmq

QMNAME(QM_GM) STATUS(Running)

4. Check if you can start WebSphere MQ Explorer by selecting Start



Programs



IBM

WebSphere MQ



WebSphere MQ Explorer (Figure 6). You can see the queue

managers (for example, QM_GM), a queue manager’s resources (for example, its queues, topics, subscriptions, and so forth), and the file transfer-specific aspects (for example, its monitors, transfer templates, and transfer logs).

Figure 6 WebSphere MQ Explorer shows the queue manager and the file transfers


5. Check if you can start and ping the file transfer agent (Example 2).

Example 2 Starting and pinging the file transfer agent

C:\>fteStartAgent WSRR.GM.AGENT

5655-U80, 5724-R10 Copyright IBM Corp. 2008, 2009. ALL RIGHTS RESERVED

BFGCL0030I: The request to start agent 'WSRR.GM.AGENT' on this machine has been submitted.

BFGCL0031I: Agent log files located at: C:\Program Files\IBM\WMQFTE\config\

QM_GM\agents\WSRR.GM.AGENT

C:\>

C:\>ftePingAgent WSRR.GM.AGENT


BFGCL0212I: Issuing ping request to agent WSRR.GM.AGENT

BFGCL0213I: agent WSRR.GM.AGENT responded to ping in 0.5 seconds.

Verifying the installation on the runtime environments

Execute the following steps to verify that the installed products and their provided services work properly. Before you start with verification, restart the operating system by selecting

Start



Restart. Follow these steps:

1. Check if the WebSphere Application Server (installed together with WebSphere Service

Registry and Repository) service is started by selecting Start



Settings



Control

Panel



Administrative Tools



Services (Figure 7).

Figure 7 Automatically started services on the governance production environment

2. Check if you can log in to the web user interfaces: a. WebSphere Application Server Console, for example: https://localhost:9043/ibm/console/logon.jsp

b. WebSphere Service Registry and Repository Console, for example: https://localhost:9443/ServiceRegistry/logon.jsp

3. Check if you can start and ping the file transfer agent (Example 3 on page 15).

Note: The WSRR.PROD.AGENT agent is registered on the queue manager on the governance production environment.


Example 3 Starting and pinging the agent

C:\>fteStartAgent WSRR.PROD.AGENT


BFGCL0030I: The request to start agent 'WSRR.PROD.AGENT' on this machine has been submitted.

BFGCL0031I: Agent log files located at: C:\Program Files\IBM\WMQFTE\config\

QM_GM\agents\WSRR.PROD.AGENT

C:\>

C:\>ftePingAgent WSRR.PROD.AGENT


BFGCL0212I: Issuing ping request to agent WSRR.PROD.AGENT

BFGCL0213I: agent WSRR.PROD.AGENT responded to ping in 0.5 seconds.

Verifying the file transfer from governance to production

The last verification step is to manually transfer a file from the source to the target. The source is the governance production environment, and the target is the runtime production environment. You execute the file transfer either by using WebSphere MQ Explorer or the file transfer command fteCreateTransfer . Follow these steps:

1. On the governance production environment, run the following file transfer command

(Example 4). It will fail, because there is no file in the source directory.

Example 4 Creating a file transfer

C:\>fteCreateTransfer -sa WSRR.GM.AGENT -da WSRR.PROD.AGENT -dm QM_GM -df

C:\solution\promotion\target.txt -w -jn FIRST_JOB

C:\solution\promotion\production\source.txt


BFGCL0035I: Transfer request issued. The request ID is:

414d5120514d5f474d2020202020202044e3494c2001a403

BFGCL0142I: The file transfer request has been submitted. The command is waiting for notification of the transfer's completion.

BFGCL0141I: The requested file transfer has completed with no files being transferred.

2. Prepare the directory structures: a. On the governance production environment, create a directory named

C:\solution\promotion\production\ . Place a simple text file named source.txt

into that directory.

b. On the runtime production environment, create a directory named

C:\solution\promotion\ .

3. Run the command that is shown in Example 4 again. It is successfully executed. In the

target directory on the runtime production environment, you see a file named target.txt

.

The source file has not been deleted.

4. Run the command again. It fails, because a file named target.txt

already exists in the target directory C:\solution\promotion\ .

5. Start WebSphere MQ Explorer, and select Managed File Transfer



QM_GM



Transfer Log to verify the results (Figure 8 on page 16).


Figure 8 Transfer log after simple file transfer

Configuring and customizing the products

This section describes how to configure WebSphere Service Registry and Repository and

WebSphere File Transfer Edition to promote service artifacts from the governance production environment to the runtime environments.

We discuss the following topics in this section:

򐂰

Outlining the elements to configure and customize

򐂰

Loading the configuration profile

򐂰

Adjusting promotion properties

򐂰

Creating the promotion directories

򐂰

Automating the promotion process

򐂰

Configuring the command-line interface

Outlining the elements to configure and customize

Figure 9 shows the elements that we configure and customize in this section.


Staging

Life cycle

Production

WSRRGM

GEP

WebSphere Service

Registry and Repository

WebSphere File Transfer Edition Client

WMQFTE Agent

(WSRR.GM.AGENT)

Monitor

FTE

Scripts

Prom otion

Properties

File

System

Queue Manager

(QM_GM)

WebSphere MQ

WSRRSTAG

GEP

WebSphere Service

R egistry and Repository


WMQFTE Agent

(WSRR.STAG.AGENT)

WSRR

Scripts

File

System

WSRRPROD

GEP

WebSphere Service



WMQFTE Agent

(WSRR .PROD .AGENT)

WSRR

Scripts

File

System

Figure 9 Elements to configure and customize

Execute the following configuration steps, which we describe in detail:

1. Load the governance enablement profile (GEP V7.0) in all environments.

2. Configure the promotion properties on the governance production environment.

3. Create the directory structures on the file system in all environments.

4. Automate promotion through WebSphere MQ File Transfer Edition on the governance production environment (FTE scripts). This task includes creating the monitors that observe the promotion directories, providing the scripts (a task definition, an ant script, and a property file), and adjusting the agent property files. We have already created the

agents and the queue manager in “Installation” on page 9.

5. Configure the CLI of WebSphere Service Registry and Repository on all runtime environments (WSRR scripts). This task is required to import the promoted services into the runtime environments.

Important: Read the following sections carefully, because not all steps apply to all environments. Most of the steps apply only to the governance production environment, unless otherwise stated.


Loading the configuration profile

First, we load the default governance enablement profile to all WebSphere Service Registry and Repository instances. The profile is required to transition and promote the service artifacts. Follow these steps:

1. Log in to the WebSphere Service Registry and Repository Console, for example: https://localhost:9443/ServiceRegistry/logon.jsp

2. Switch to the configuration perspective, if necessary, by selecting Configuration in the

Perspective drop-down menu.

3. Click Manage Profiles



Configuration Profiles.

4. Click Load Configuration Profile.

5. Click Browse. Navigate to the C:\Program

Files\IBM\WebSphere\ServiceRegistry\WSRR\config local config directory. Select the file

GovernanceEnablementProfile_v70.zip, and click Open.

6. Click OK.

7. Select Governance Enablement Profile (default), and click Make Active.

After loading and activating the governance enablement profile (Figure 10), we are now able

to transition entities through the governance life cycles.

Figure 10 Loaded and activated governance enablement profile

Important: All WebSphere Service Registry and Repository instances require the identical software version and the same governance enablement profile. Otherwise, the promotion of service artifacts fails.

See the WebSphere Service Registry and Repository Information Center for more information about configuration profiles: http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm.sr.doc/c wsr_configrn_config_profiles.html

Adjusting promotion properties

Now, we replace the existing promotion properties file with the configuration that we require in our solution on the governance production environment. Follow these steps:

1. Load the promotion properties file into the WebSphere Service Registry and Repository: a. Log in to the WebSphere Service Registry and Repository Console, for example: https://localhost:9443/ServiceRegistry/logon.jsp

b. Change to the Configuration perspective.


c. Load the promotion properties file: i.

Click Active Profile



Promotion. ii. Click PromotionProperties. iii. Click Replace Promotion Properties. iv. Specify the path on the local file system where the promotion properties file is stored, for example, .\config\PromotionProperties.xml

. We supply this file in the

additional material accompanying this paper, which is described in “Additional material” on page 48. Example 5 shows the content of the promotion properties file.

Click OK.

Promoting multiple times: If you want to promote multiple times using the same service version (for example, for test purposes), you can uncomment the transitions ApproveForUse and RevokeFromUse in the promotion properties file. If you do so, these two life cycle transitions of the Endpoint life cycle trigger promotion each time. In this case, only the related endpoint is promoted and not the service version, but you can test and debug the automated promotion process multiple times.

Example 5 Promotion properties file: PromotionProperties.xml

<promotion-configuration xmlns="http://www.ibm.com/xmlns/prod/serviceregistry/6/1/PromotionPropert ies" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<environments>

<environment name="http://www.ibm.com/xmlns/prod/serviceregistry/6/1/GovernanceProfile

Taxonomy#Staging">

<promotion>

<type>manual</type>

<filepath>${WSRR_PROMOTION_STAGING}/staging/</filepath>

<filename>%TS%_promotion_staging.zip</filename>

</promotion>

</environment>

<environment name="http://www.ibm.com/xmlns/prod/serviceregistry/6/1/GovernanceProfile

Taxonomy#Production">

<promotion>

<type>manual</type>

<filepath>${WSRR_PROMOTION_PRODUCTION}</filepath>

<filename>%TS%_promotion_production.zip</filename>

</promotion>

</environment>

</environments>

<transitions>

<transition name="http://www.ibm.com/xmlns/prod/serviceregistry/lifecycle/v6r3/Lifecy cleDefinition#ApproveStagingDeployment">

<target-environments>

<name>http://www.ibm.com/xmlns/prod/serviceregistry/6/1/GovernanceProfile

Taxonomy#Staging</name>

</target-environments>

</transition>


<transition name="http://www.ibm.com/xmlns/prod/serviceregistry/lifecycle/v6r3/Lifecy cleDefinition#ApproveProductionDeployment">



Taxonomy#Production</name>


</transition>

</transitions>



</transitions>

</promotion-configuration>

2. Create two new environment variables on the application server: a. Log in to the WebSphere Application Server Console, for example: https://localhost:9043/ibm/console/logon.jsp

b. Click Environment



WebSphere Variables.

c. Select Node=WSRRGMNode01, Server=server1 in the Scope pull-down menu.

d. Click New. Enter WSRR_PROMOTION_STAGING for the name and

C:/solution/promotion/staging/ for the value. Click OK.

e. Click New. Enter WSRR_PROMOTION_PRODUCTION for the name and

C:/solution/promotion/production/ for the value. Click OK.

Figure 11 on page 21 shows the two new environment variables.


Figure 11 Environment variables defining the promotion directories

Directories: It is not possible to define a root directory and use this root directory within the promotion file in conjunction with the staging and production subdirectories, for example,

<filepath>${WSRR_PROMOTION_ROOT_DIRECTORY}/staging/</filepath> . If you do, the promotion fails and logs an exception. You can define nested environment variables instead.

f. Click Save now that the variables are stored in the master configuration of the application server.

Important: Make sure that you restart the server before the first promotion happens; otherwise, the export of the service data fails, because the environment variables might not be available for the service registry application.

For more information about promotion and classification systems, see the following web sites:

򐂰 http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm.sr.doc/ cwsr_promotion.html

򐂰 http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm.sr.doc/ twsr_configrn_classifications02.html


Creating the promotion directories

Create the required directory structure on the file system according to the promotion

properties file. Also, see the directory structures that are provided in “Additional material” on page 48. Follow these steps:

1. On the governance production environment, create the following directory structure if it does not already exist. You can find the directories, including the content for the

governance production environment, in “Additional material” on page 48. Use the directory

structure that is provided within the .\wsrrgm directory:

– C:\solution\archive

– C:\solution\promotion :

• C:\solution\promotion\production

• C:\solution\promotion\staging

– C:\solution\scripts

2. On all runtime environments, create the following directory structure if it does not already exist. You can find the directories, including the content for the runtime environments, in

“Additional material” on page 48. Use the directory structure that is provided within the

.\wsrrprod directory:

– C:\solution\archive

– C:\solution\promotion

– C:\solution\scripts

Automating the promotion process

The governance enablement profile is activated, and the promotion properties are adjusted.

Therefore, if you execute the ApproveStagingDeployment or ApproveProductionDeployment transition of the SOA life cycle, a promotion compressed file will be exported.

We now automate the promotion process, so that the file transfer starts as soon as the first promotion export takes place.

Creating the scripts to execute the file transfer

Figure 12 on page 23 shows the required scripts for the automated promotion. These scripts

are only required on the governance production environment. You can find the scripts in the

.\wsrrgm\solution\scripts\

directory in “Additional material” on page 48.


WSRRGM

Monitors running on agent

WSRR.GM.PROD

Monitor

WSRR.GM.TO.STAG.MONITOR

Execute

Observe

Observe

Monitor

WSRR.GM.TO.PROD.MONITOR

Execute

Promotion ZIP files in

C:\solution\promotion

.\staging

.\production

Scripts in C:\solution\scripts

Properties promote_to_staging.properties

Task Definition promote_to_staging.xml

Execute

Configure

Ant Script promote.xml

Execute

Configure

Task Definition promote_to_production.xml

Properties promote_to_production.properties

Figure 12 Scripts to transfer and import the service data

Follow these steps to create the scripts to execute the file transfer:

1. The promote_to_<target>.xml script is the task definition XML file, which is triggered if the monitor detects a .zip

file in the promotion directory (Example 6). The script

delegates further processing to the promote.xml

ant script. The parameters that are provided by the monitor are important and define where the .zip

file was detected. The property.file

parameter defines the name of an environment-specific property file.

Example 6 Task definition for the runtime production environment

<?xml version="1.0" encoding="UTF-8"?>

<request version="2.00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FileTransfer.xsd">

<managedCall>

<originator>

<hostName>WSRRGM</hostName>

<userID><the user id></userID>

</originator>

<agent QMgr="QM_GM" agent="WSRR.GM.AGENT"/>

<reply QMGR="QM_GM">reply</reply>

<transferSet>

<call>

<command name="promote.xml" type="antscript" retryCount="0" retryWait="0" successRC="0">



<property name="cmd.qmgr" value="QM_GM"/>

<property name="src.agent" value="WSRR.GM.AGENT"/>

<property name="zip.path" value="${FilePath}"/>

<property name="zip.file" value="${FileName}"/>



<property name="property.file" value="promote_to_production.properties"/>

</command>

</call>

</transferSet>

</managedCall>

</request>

2. The promote_to_<target>.properties

property file defines the runtime

environment-specific properties, for example, the command-line path (Example 7). The

name of the runtime environment-specific property file is passed as a parameter from the task definition to the ant script. Adjust the dst.agent

property according to the name of the agent that is running on the runtime environment, for example, STAG for staging or PROD for production.

Example 7 Property file for the runtime production environment

#########################################################################

# This property file contains the runtime environment-specific

# properties. The runtime environment can be either staging or

# production.

#########################################################################

#########################################################################

# Properties for basic solution

#########################################################################

# Defines the name of the agent running on the runtime environment.

dst.agent=WSRR.PROD.AGENT

# Defines the directory for the promotion zip file on the runtime environment.

dst.path=C:\\solution\\promotion

# Defines the prefix for the jobname.

job.name.prefix=TRANSFER_PROMOTION_ZIP#

# Defines the path of the WSRR command-line interface (CLI) command. Make

# sure the commandPath property in the agent.properties file of the runtime

# environment has been assigned the same value.

cli.path=C:\\Program Files\\IBM\\WebSphere\\ServiceRegistry\\WSRR\\CLI


3. The promote.xml

script promotes the exported .zip

file from the governance production

environment to the runtime environments (Example 8). The script works for both the

staging and production runtime environments. The two key targets in the ant script are

transfer

and

import

:

– The transfer target executes the file copy to the remote runtime environment using the file transfer filecopy command. The prefix

fte

is the name space within the XML file.

– The import target executes the CLI of WebSphere Service Registry and Repository to import the promotion .zip

file to the remote runtime environment by calling the import.py

Jython script.

The task definition starts the default target

complete

. The nested arguments in the import target are required; otherwise, the import program only receives one concatenated argument and fails. Use the target

show_props

to check the actual values of the properties.

Example 8 Ant script to promote the .zip file to the runtime environment

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns:fte="antlib:com.ibm.wmqfte.ant.taskdefs" default="complete">



<property file="${property.file}"/>



<target name="complete">



<antcall target="promote" />

</target>



<target name="promote">

<echo message="*** INFO: Promotion started (dst.agent=${dst.agent})" />

<antcall target="transfer"/>

<antcall target="import"/>

<echo message="*** INFO: Promotion successfully executed

(dst.agent=${dst.agent})" />

</target>



<target name="transfer" description="Transfers the exported zip file to the target environment.">

<echo message="*** INFO: Transfer started (dst.agent=${dst.agent})" />

<fte:uuid property="job.name" length="8" prefix="${job.name.prefix}" />

<fte:filecopy cmdqm="${cmd.qmgr}" src="${src.agent}@${cmd.qmgr}" dst="${dst.agent}@${cmd.qmgr}" jobname="${job.name}" rcproperty="transfer.rc" outcome="await">


<fte:filespec srcfilespec="${zip.path}" dstfile="${dst.path}\${zip.file}" overwrite="true" />

</fte:filecopy>

<fail message="Failed to transfer (file=${zip.path, dst.agent=${dst.agent}, return code=${transfer.rc})">

<condition>

<not><equals arg1="${transfer.rc}" arg2="0" /></not>

</condition>

</fail>

<echo message="*** INFO: Transfer successfully executed


</target>



<target name="import" description="Imports transferred zip file into the

WSRR target instance.">

<echo message="*** INFO: Import started (dst.agent=${dst.agent})" />

<fte:call cmdqm="${cmd.qmgr}" agent="${dst.agent}@${cmd.qmgr}" rcproperty="import.rc" outcome="await">

<fte:command command="wsrrcli.bat" successrc="0">

<fte:arg value="${cli.path}\scripts\import.py" />

<fte:arg value="-a" />

<fte:arg value="secure" />

<fte:arg value="-c" />

<fte:arg value="${cli.path}\config\wsrrcli.conf" />

<fte:arg value="-u" />

<fte:arg value="<the user id>" />

<fte:arg value="-p" />

<fte:arg value="<the password>" />

<fte:arg value="-in" />

<fte:arg value="${dst.path}\${zip.file}" />

</fte:command>

</fte:call>

<fail message="Failed to import (file=${dst.path\${zip.file}, dst.agent=${dst.agent}, return code=${import.rc})">

<condition>

<not><equals arg1="${import.rc}" arg2="0" /></not>

</condition>

</fail>

<echo message="*** INFO: Import successfully executed


</target>



<target name="show_props">

<echo message="**************************************" />

<echo message="*** Property Name = Property Value ***" />

<echo message="**************************************" />

<echo message="cmd.qmgr = ${cmd.qmgr}" />

<echo message="src.agent = ${src.agent}" />


<echo message="zip.path = ${zip.path}" />

<echo message="zip.file = ${zip.file}" />

<echo message="dst.agent = ${dst.agent}" />

<echo message="dst.path = ${dst.path}" />

<echo message="job.name.prefix = ${job.name.prefix}" />

<echo message="cli.path = ${cli.path}" />

<echo message="property.file = ${property.file}" />

<echo message="**************************************" />

</target>

</project>

Creating the monitors to trigger the file transfer

Now, we create the monitors to observe the promotion directories for the various runtime environments. The monitor triggers the task definition XML file to start the promotion process.

The monitors are required on the governance production environment only.

Run the command that is shown in Example 9. Then, adjust the script slightly to create the

monitor to observe the runtime production environment by replacing production with staging .

Example 9 Monitor to observe the production directory and trigger the file transfer fteCreateMonitor -ma WSRR.GM.AGENT -mm QM_GM -mn WSRR.GM.TO.PROD.MONITOR -md

C:\solution\promotion\production -pi 5 -pu seconds -tr match,*promotion_production.zip -mt C:\solution\scripts\promote_to_production.xml

Adjusting the agent property files

The last step is to adjust the default agent property files, so that the properties fit the specific environments. The property file is stored in the [MQFTE_HOME]\config\QM_GM\agents\<agent

name> directory. Follow these steps:

1. Add the following two properties to the agent.properties

file on the governance production environment:

– commandPath=C:\\solution\\scripts

– sandboxRoot=C:\\solution

2. Add the following two properties to the agent.properties

file on the runtime environments:

– commandPath=C:\\Program Files\\IBM\\WebSphere\\ServiceRegistry\\WSRR\\CLI

– sandboxRoot=C:\\solution

Important: Make sure that you use the double backslash (\\) for the command path.

Otherwise, the scripts cannot be found, and the promotion fails.

3. Restart the agents on all environments by executing the following commands: a. Stop the agent: C:\fteStopAgent <agent name> b. Start the agent: C:\fteStartAgent <agent name> c. Ping the agent: C:\ftePingAgent <agent name>


Configuring the command-line interface

The promote.xml

ant transfer script of the automated promotion process remotely calls the import.py

Jython script using the command-line interface (CLI) on the runtime environment.

The script imports the transferred promotion .zip

file into the runtime instance. Therefore, we need to configure the scripting environment on all runtime environments.

For more information about the configuration of the CLI, see this web site: http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm.sr.doc/t wsr_adminstn_adiministration24.html

Setting the environment variables

The WSRRCLI.bat

CLI script requires four environment variables. The environment variables depend on the location where you have installed the WebSphere products. If you have

chosen the default location during product installation, Table 1 shows the respective variable

values. Follow these steps:

1. Click Start



Control Panel



System



Advanced



Environment Variables. Under system variables, click New, and set the variable name and variable value. Click OK. Add all four environment variables.

Table 1 Environment variables that are used by the CLI

Variable name Variable value

JAVA

JYTHON_HOME

WAS_HOME

C:\Program Files\IBM\WebSphere\ServiceRegistry\java\bin\java.exe

C:\Program Files\IBM\WebSphere\ServiceRegistry\optionalLibraries\jython

WSRR_HOME

C:\Program Files\IBM\WebSphere\ServiceRegistry

(in our case, not C:\IBM\WebSphere\AppServer)

C:\Program Files\IBM\WebSphere\ServiceRegistry\WSRR

(in our case, not C:\IBM\WebSphereServiceRegistry)

2. In the Environment Variables dialog, click OK. In the System Properties dialog, click OK.

3. If you do not want to set the environment variables, you can also adjust the C:\Program

Files\IBM\WebSphere\ServiceRegistry\WSRR\CLI\WSRRCLI.bat

script. In that case, you only replace these four variables at the top of the script.

Adjusting the command-line interface configuration

You configure the WSRRCLI.bat

CLI script through the wsrrcli.conf

configuration file. The configuration file is located in the following directory:

C:\Program Files\IBM\WebSphere\ServiceRegistry\WSRR\CLI\config\

Replace the placeholder <CLIENT_HOME> with the following directory:

C:/Program Files/IBM/WebSphere/ServiceRegistry/profiles/WSRRSrv01

Example 10 on page 29 shows how the CLI properties for a secured application server

environment look.


Example 10 Configuration properties for the CLI

# Details for a secure system

# Alias = secure

# EJB Settings secure.java.naming.provider.url = corbaloc:iiop:localhost:2809 secure.com.ibm.CORBA.ConfigURL=file:C:/Program

Files/IBM/WebSphere/ServiceRegistry/profiles/WSRRSrv01/properties/sas.client.props

secure.java.security.auth.login.config=file:C:/Program

Files/IBM/WebSphere/ServiceRegistry/profiles/WSRRSrv01/properties/wsjaas_client.co

nf secure.com.ibm.SSL.ConfigURL=file:C:/Program

Files/IBM/WebSphere/ServiceRegistry/profiles/WSRRSrv01/properties/ssl.client.props

# MBean settings secure.host = localhost secure.port = 8880 secure.type = SOAP secure.securityEnabled = true secure.wasHome = C:/Program Files/IBM/WebSphere/ServiceRegistry/profiles/WSRRSrv01 secure.com.ibm.SOAP.requestTimeout = 600

Testing the connectivity

Run the connectivity test to make sure that the CLI can properly connect to the application

server (Example 11). In the console, you see the string

Connection test successful .

Example 11 Command to test connectivity

C:\Program Files\IBM\WebSphere\ServiceRegistry\WSRR\CLI>WSRRCLI.bat scripts\conn ectTest.py -a secure -c config\wsrrcli.conf -u <the user id> -p <the password>

...

Connection test successful

Verifying the proper configuration

The automated promotion process is configured and customized. Before we start to transition service objects and promote in the next section, we execute several test cases to verify that the transfer step and the import step work properly.

Verifying the transfer of the promotion compressed file

Now, we test the transfer target. Execute the following steps:

1. On the governance production environment, delete the monitor that runs on the

WSRR.GM.AGENT agent and that observes the promotion staging directory (Example 12 on page 30).


Example 12 Deleting the monitor that observes the staging directory

C:\solution\scripts>fteListMonitors


Agent Name: Monitor Name:

WSRR.GM.AGENT WSRR.GM.TO.PROD.MONITOR

WSRR.GM.AGENT WSRR.GM.TO.STAG.MONITOR

C:\solution\scripts>fteDeleteMonitor -ma WSRR.GM.AGENT -mn

WSRR.GM.TO.STAG.MONITOR


BFGCL0192I: A request to delete monitor WSRR.GM.TO.STAG.MONITOR has been issued.

BFGCL0251I: The request has successfully completed.

2. On the governance production environment, copy the

C:\solution\wsrrgm\samples\promotion_to_staging_of_eligibility_service.zip

compressed file to the C:\solution\promotion\staging\test.zip

test compressed file

(Example 13).

Example 13 Copying sample compressed file into the staging directory and naming it test.zip

C:\>copy c:\solution\samples\promotion_to_staging_of_eligibility_service.zip

c:\solution\promotion\staging\test.zip

1 file(s) copied.

3. On the runtime staging environment, make sure that there is not a compressed file called test.zip

. Delete the file, if it exists (Example 14).

Example 14 Deleting test.zip file from the promotion directory

C:\solution\promotion>del test.zip

4. On the governance production environment, run the transfer target for the runtime staging

environment (Example 15). Make sure that the ant script does not print any error

messages to the system.

Example 15 Running the transfer target for the test.zip file

C:\solution\scripts>fteAnt -v -f promote.xml -propertyfile promote_to_staging.properties -Dzip.path=C:\solution\promotion\staging\test.zip

-Dzip.file=test.zip transfer


BFGCL0209I: Build sequence for target(s) `transfer' is [transfer]

BFGCL0209I: Complete build sequence is [transfer, complete, import, ]

BFGCL0211I:

BFGCL0211I: transfer:

BFGCL0209I: parsing buildfile jar:file:/C:/Program%20Files/IBM/WMQFTE/lib/com.ib

m.wmqfte.ant.jar!/com/ibm/wmqfte/ant/taskdefs/antlib.xml with URI = jar:file:/C:/Program%20Files/IBM/WMQFTE/lib/com.ibm.wmqfte.ant.jar!/com/ibm/wmq fte/ant/taskdefs/antlib.xml


5. On the staging environment, verify that the test.zip

file has been transferred

(Example 16).

Example 16 Verifying the transfer of the test.zip file

C:\>dir c:\solution\promotion\*.*

Directory of C:\solution\promotion

08/03/2010 04:32 PM 6,264 test.zip

6. Recreate the monitor running on the WSRR.GM.AGENT agent that observes the

promotion staging directory. See “Creating the monitors to trigger the file transfer” on page 27.

Verifying the import of the promotion compressed file

Now, we test the import target. Execute the following steps:

1. On the runtime staging environment, make sure that the test.zip

file from the previous transfer test exists in the C:\solution\promotion directory.

2. On the governance production environment, run the import target for the runtime staging

environment (Example 17). Make sure that the ant script

does not print any error messages to the system.

Example 17 Running the import target for the test compressed file

C:\solution\scripts>fteAnt -v -f promote.xml -propertyfile promote_to_staging.properties -Dzip.file=test.zip import


BFGCL0209I: Build sequence for target(s) 'import' is [import]

BFGCL0209I: Complete build sequence is [import, transfer, complete, ]

BFGCL0211I:

BFGCL0211I: import:

BFGCL0209I: parsing buildfile jar:file:/C:/Program%20Files/IBM/WMQFTE/lib/com.ibm.wmqfte.ant.jar!/com/ibm/wmq fte/ant/taskdefs/antlib.xml with URI = jar:file:/C:/Program%20Files/IBM/WMQFTE/lib/com.ibm.wmqfte.ant.jar!/com/ibm/wmq fte/ant/taskdefs/antlib.xml

3. Log in to the WebSphere Service Registry and Repository Console, for example, https://localhost:9443/ServiceRegistry/logon.jsp

4. Switch to the Development perspective.

5. Click View



Technical Governance



Capability Versions



Service Versions



Eligibility Service. Under Links, click Graphical View. Expand the graph for the eligibility

service, as shown in Figure 13 on page 32. Figure 13 on page 32 shows the imported

objects.


Figure 13 Graph of eligibility service

6. Click View



Life Cycle View



Endpoint Life Cycle



Online Endpoints



http://www.jkhle.com/jkhle/services/Eligibility. In the Classifications section, you see three classifications: Online, Staging, and SOAP Service Endpoint.

7. Optionally, in the Administrator perspective, delete all concepts and Web Services

Description Language (WSDL) documents on the runtime staging environment, which deletes all service data in the runtime environments.

In the case of an error

In the case of an error, the best option is to subscribe to the SYSTEM.FTE/# topic and

analyze the request and response messages. For more information, see “Troubleshooting” on page 47.

Running the automated promotion process

In this section, we promote service data to the runtime environments. We have prepared two services with a service version in a life cycle state just before promotion. The services are called

eligibility service

and

account creation service

. After loading the prepared service data into the governance production instance, you will transition two service versions through the deployment states of the SOA life cycle and execute the automated promotion process end-to-end.


򐂰 What are you going to test?

򐂰 How do you prepare the environments?

򐂰 How do you promote the services?

Additional resources:

򐂰 The services are built according to the Governance Enablement Profile tutorial in the Information Center. The scenario is about a fictional company named JKHL

Enterprise (JKHLE). For more information, go to this web site: http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm

.sr.doc/cwsr_gep.html

򐂰 Service Lifecycle Governance with IBM WebSphere Service Registry and

Repository, SG24-7793, provides almost the same services for the same fictional company. The book slightly adjusted the governance enablement profile, both the governance entity model and the governance life cycles model.


Testing

After testing, you can expect these results:

򐂰 The promotion compressed file is exported from the governance production environment

instance as soon as a defined governance life cycle transition is executed. See “Adjusting promotion properties” on page 18.

򐂰 The monitor detects the exported compressed file and triggers the task definition script.

The script transfers the compressed file to the runtime environment and imports the

service data into the runtime instance. See “Automating the promotion process” on page 22.

򐂰 The service data in the runtime environment is synchronized with the governance production environment, for example, the same entity instances have the same states.

Preparing the environments

You have installed, configured, and tested your environments. Now, we are going to prepare the governance production instance, so that you can promote services in a few steps first to the runtime staging environment and then to the runtime production environment. For that purpose, we have prepared the two services: eligibility and account creation. To load these services, execute the following steps:

1. Log in to the WebSphere Service Registry and Repository Console, for example: https://localhost:9443/ServiceRegistry/logon.jsp

1. Change to the Administrator perspective.

2. Import the prepared services into the governance production instance. Click Actions



Import. Click Browse. Go to the directory where the additional material is stored, and select prepared_tutorial.zip. This file is in the .\preparation directory of the additional material. Click OK.

3. Click View



Concepts. Now, you see 27 entries in the list of concepts. Figure 14 on page 34 shows the state of the imported governance entities.


Eligibility service

Business Service approved

Charter

(doc)

Owning

Organization:

Common Service

Business Service

Version realized

Service Level

Definition subscribable

Service Interface

Service Endpoint: all environments

(WSDL)

(WSDL)

Account creation service

Charter

(doc)

Owning

Organization:

Commercial

Business Service approved

Document of

Understanding approved

Business Service

Version specified

Service Interface

Specification approved

Schema Specification

Service Level

Agreement active

Service Level

Definition subscribable

Service Endpoint:

Specification

(WSDL)

Service Interface

(WSDL)

Schema

(XSD)

Legend

An entity of governance model

The life cycle state of an entity

Figure 14 State of the imported governance entities before promotion

Figure 14 shows the eligibility service and the account creation service before promotion:

򐂰 The tutorial Governing an existing service governs the existing eligibility service.

Therefore, no interface specification exists. See this web site: http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm.sr.do

c/tutorial_gep_govern_existing_service.html

򐂰 The tutorial Governing a new service governs the new account creation service. This service uses the eligibility service. Therefore, we need two additional entities: document of understanding and service-level agreement. See this web site: http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm.sr.do

c/tutorial_gep_govern_new_service.html

We have executed the following steps of the two tutorials to come to the state that is shown in

Figure 14.

򐂰 For the eligibility service, from step

Registering the WSDL for a service

to step

Providing a specification and service level definition for the service

򐂰 For the account creation service, from step

Identifying a requirement for a new business capability

to step

Activating a service level agreement

In the next section, we execute the promotion to the runtime staging environment and the runtime production environment.


Promoting the services

This section describes how to promote the eligibility and account creation services.

Promoting the eligibility service

The eligibility service is in the governance life cycle state

realized

. Now, we promote this service to the runtime staging environment and the runtime production environment. Execute the following steps in the Development perspective:

1. Navigate to the service version entity of the eligibility service.

2. Under Provides, click SLD - Eligibility Service.

3. Click http://www.jkhle.com/jkhle/services/Eligibility under the available endpoints relationship.

4. Add the staging classification to the selected endpoint and activate the endpoint: a. Click Edit Classifications. Expand Governance Profile Taxonomy



Environment.

Check Staging, and then click Add. Click OK.

b. Click Approve for Use.

5. Promote the service to the runtime staging environment: a. Navigate to the entity service version of the eligibility service.

b. Click Propose Staging Deployment, and then, click Approve Staging Deployment.

The eligibility service version is now promoted to the runtime staging environment. Log in to the staging environment in the Development perspective to check if the service version is promoted with the classification staging:

1. Click View












Eligibility Service. Under Links, click Graphical View. Expand the graph for the eligibility

service, as shown in Figure 13 on page 32. Now, you can see the service version

(Figure 13 on page 32).

2. Click View



Life Cycle View







 http://www.jkhle.com/jkhle/services/Eligibility



Edit Classification. In the

Classification List, you see three classifications: Online, Staging, and SOAP Service

Endpoint.

Go back to the governance production environment, and execute the following steps to promote the service version to the runtime production environment:

1. Navigate to the entity service-level definition of the eligibility service. Click

http://www.jkhle.com/jkhle/services/Eligibility under the available endpoints relationship.

2. Add the production classification to the selected endpoint and activate the endpoint: a. Click Edit Classifications. Expand Governance Profile Taxonomy



Environment.

Check Production, and then, click Add. Click OK.

b. The endpoint is already Online.

3. Promote the service to the runtime production environment: a. Navigate to the entity service version of the eligibility service.

b. Click Propose Certification, and then, click Approve Certification. c. Click Propose Production Deployment, and then, click Approve Production

Deployment.


The eligibility service version is now promoted to the runtime production environments. The service endpoint has an additional classification

Production

.

Important: The promoted service version is transferred and imported asynchronously into the runtime environment. Therefore, it can take time until the environments are synchronized.

Promoting the account creation service

The account creation service is in the governance life cycle state

specified

. We will promote this service to the runtime staging environment and to the runtime production environment.

Execute the following steps in the Development perspective:

1. Load the service implementation WSDL: a. Click Actions



Load Documents.

b. Select WSDL in the Document type pull-down menu.

c. Click Browse and navigate to the account creation service directory.

d. Select AccountCreationDevelopmentEndpoint.wsdl, click Open, and click OK.

e. Click Finish.

2. Associate the service version with the development endpoint: a. Navigate to the service version Account creation service.

b. Click Edit Relationships.

c. Click Add Service (next to the Provided Web Services relationship).

d. Enter A in the name field. Select AccountCreationService-Development. Click Add.


3. Go further in the SOA life cycle, and simulate the service development: a. Click Propose Realization.

b. Click Approve Realization.

4. Load the staging endpoint WSDL: a. Switch to the Operation perspective.

b. Click Actions



Load Documents.

c. Select WSDL in the Document type pull-down menu.

d. Click Browse, and navigate to the account creation service directory.

e. Select AccountCreationStagingEndpoint.wsdl, click Open, and click OK.

f. Click Finish.

5. Add the staging classification to the loaded WSDL document: a. Click AccountCreationStagingEndpoint.wsdl.

b. Click Edit Classifications. Expand Governance Profile Taxonomy



Environment.

Check Staging, and then, click Add. Click OK.

6. Add the staging classification to the service version endpoint: a. Click View



Lifecycle View



Endpoint Lifecycle



Offline Endpoints.

b. Click http://staging.jkhle.com:9080/jkhle/services/AccountCreation.

c. Click Edit Classifications. Expand Governance Profile Taxonomy



Environment.

Check Staging, and then, click Add. Click OK.


7. Associate the service version with the staging service: a. Navigate to the service version Account creation service.



d. Enter A in the name field, and select AccountCreationService-Staging. Click Add.


8. Associate the staging endpoint with the service-level definition: a. Click SLD - Account creation service.


c. Click Add Service Endpoint (next to the Available Endpoints relationship).

d. Enter h in the name field, and select

http://staging.jkhle.com:9080/jkhle/services/AccountCreation. Click Add.


9. Approve the service for use: a. Click View



Lifecycle View







b. Click http://staging.jkhle.com:9080/jkhle/services/AccountCreation.

c. Click ApproveForUse.

10.Promote the service version to the runtime staging environment: a. Navigate to the entity service version of the account creation service.

b. Click Propose Staging Deployment, and then, click Approve Staging Deployment.

The account creation service version is now promoted to the runtime staging environment.

Log in to the staging environment in the Development perspective, and check if the service version is promoted with the classification

staging

.

11.Click View












Account Creation Service. Under Links, click Graphical View. Expand the graph for the

Account Creation Service, as shown in Figure 15 on page 38. Now, you can see the graph

of the account creation service version and its dependency to the eligibility service

(Figure 15 on page 38).


Figure 15 Graph of account creation service

12.Click View



Life Cycle View







 http://www.jkhle.com/jkhle/services/AccountCreation



Edit Classification. In the

Classification List, you see three classifications: Online, Staging, and SOAP Service

Endpoint.

Go back to the governance production environment, and execute the following steps to promote the service version to the runtime production environment:

1. Certify the service version: a. Navigate to the entity service version of the account creation service.

b. Click Propose Certification, and then, click Approve Certification.

2. Load the WSDL document: a. Click Actions



Load Documents.

b. Select WSDL in the document type pull-down menu.

c. Click Browse, and navigate to the account creation service directory.

d. Select AccountCreationProductionService.wsdl, click Open, and click OK.



3. Add the production classification to the loaded WSDL document: a. Click AccountCreationProductionService.wsdl.

b. Click Edit Classifications. Expand Governance Profile Taxonomy



Environment.

Click Production, and then, click Add. Click OK.

4. Add the production classification to the service version endpoint: a. Click View



Lifecycle View







b. Click http://production.jkhle.com:9080/jkhle/services/AccountCreation.

c. Click Edit Classifications. Expand Governance Profile Taxonomy



Environment.

Click Production, and then, click Add. Click OK.

5. Associate the service version with the production service: a. Navigate to the service version Account creation service to display the service version details.



d. Enter A in the name field, and select AccountCreationService-Production. Click

Add.

e. Click Finish to save the relationship change.

6. Associate the production endpoint with the service-level definition: a. Click SLD - Account creation service. b. Click Edit Relationships.

c. Click Add Service Endpoint (next to the Available Endpoints relationship).

d. Enter h in the name field, and select

http://production.jkhle.com:9080/jkhle/services/AccountCreation. Click Add.


7. Approve the service for use: a. Click View



Lifecycle View







b. Click http://production.jkhle.com:9080/jkhle/services/AccountCreation.

c. Click ApproveForUse.

8. Promote the service version to the runtime production environment: a. Navigate to the entity service version of the account creation service.

b. Click Propose Production Deployment, and then, click Approve Production

Deployment.

The account creation service version is now promoted to the runtime production environments. The graph of the account creation service version using the eligibility service version still looks the same. The service endpoint has an additional classification of

Production

.


Enhancements

This section describes how you can enhance the solution depending on your specific needs.


򐂰 Archive promotion zip files.

򐂰 Promote to multiple runtime production environments.

Archiving promotion compressed files

This enhancement describes how to archive the compressed files. We archive the compressed files after the promotion has been successfully executed. The archive is a directory on the file system. In the additional material that is supplied with this paper, you can find the scripts in the .\wsrrgm\solution\scripts\enhancement_archive directory. Follow these steps:

1. On all environments, create the C:\solution\archive directory, if it does not exist. This directory will store successfully processed compressed files (Example 18). Later on, you can have a scheduled batch job deleting the oldest compressed files, for example, by time stamp.

Example 18 Creating an archive folder

C:\>mkdir C:\solution\archive

2. Create a batch file named archive.bat in the C:\Program

Files\IBM\WebSphere\ServiceRegistry\WSRR\CLI

directory (Example 19). We provide

the batch file in the additional material in the .\wsrrprod\solution\scripts directory.

Example 19 Script archive.bat

@rem This script moves the transferred promotion zip file into the archive.

@rem

@rem Parameter

@rem %1 source file (incl. path) of the transfered promotion file

@rem %2 target directory to archive the promotion file

@echo off

@rem Move file from %1 to %2 move %1 %2

3. Add a new property to the property files for all runtime environments, for example, promote_to_production.properties

(Example 20).

Example 20 Adding a new property to define the archive directory

#########################################################################

# Additional properties for enhancement archiving

#########################################################################

# Defines the archive path on all environments.

archive.path=C:\\solution\\archive

4. Create the targets to archive the compressed files on the governance production environment (local) and on the runtime environments (remote):

archive_local

and

archive_remote

. Add them to the promote.xml

ant script (Example 21 on page 41).


Example 21 Creating two new targets to archive compressed files



<target name="archive_local" description="Archives exported zip file

(local).">

<move file="${zip.path}" todir="${archive.path}" failonerror="true" overwrite="true" />

</target>



<target name="archive_remote" description="Archives imported zip file

(remote).">

<echo message="*** INFO: Archive remote started (dst.agent=${dst.agent})"

/>

<fte:call cmdqm="${cmd.qmgr}" agent="${dst.agent}@${cmd.qmgr}" rcproperty="archive.remote.rc" outcome="await">

<fte:command command="archive.bat" successrc="0">

<fte:arg value="${dst.path}\${zip.file}" />

<fte:arg value="${archive.path}" />

</fte:command>

</fte:call>

<fail message="Failed to archive remote (file=${dst.path}\${zip.file}, dst.agent=${dst.agent}, return code=${archive.remote.rc})">

<condition>

<not><equals arg1="${archive.remote.rc}" arg2="0" /></not>

</condition>

</fail>

<echo message="*** INFO: Archive remote successfully executed


</target>

5. Add the two new archive ant calls to the

promote

target in the promote.xml

script

(Example 22). If one target of the promotion process fails, you restart the promotion

process. Therefore, the promotion compressed file must be removed at the end of the process.

Example 22 Adding the archive targets to the promote target



<target name="promote">

<echo message="*** START: promote.sequential" />



<antcall target="archive_remote"/>

<antcall target="archive_local"/>

<echo message="*** END: promote.sequential" />

</target>


From now on, the compressed files are archived as soon as the transfer and the import have been successfully executed.

Promoting to multiple runtime production environments

This enhancement describes the promotion to multiple runtime production environments. This kind of promotion might be required if there are two or more WebSphere Service Registry and

Repository instances in separate data centers.

There are two ways to fulfill this additional requirement. The requirement is to copy and import the promotion compressed file to multiple environments at the same time. Use one of these methods:

򐂰 The first way to execute targets in parallel is to use the ant task

parallel

. The parallel task executes nested tasks in parallel. Each task is executed in its own thread.

򐂰 The other solution is to use the file transfer tasks

filecopy

and

awaitoutcome

to copy the promotion compressed file to multiple runtime environments. On each runtime environment, a monitor observes the promotion directory and triggers the import of the transferred promotion compressed file.

For the first solution, we provide a detailed description of how to extend the existing solution.

For the second solution, we only provide the design, but no implementation details. You can derive the details of the implementation from the existing solution.

Promoting to multiple runtime environments using the parallel ant task

This option of parallel promotion uses the parallel ant task. Therefore, the copy and the import of the promotion compressed file are executed in parallel. The changed elements are bold;

see Figure 16 on page 43. In the additional material, you can find the scripts in the

.\wsrrgm\solution\scripts\enhancement_parallel directory.


S taging

Life cycle

Productio n

WS RRGM

GE P

WebSphere Service

Registry an d Repository

WebS phere File Transfer Edition Client

WMQ FTE Agen t

(WS RR.GM.AG ENT)

Monitor

FTE

S cripts

Promotion

Properties

File

S ystem

Qu eue Manager

(QM_GM)

WebSphere MQ

WS RRSTAG

G EP

WebSphere Service



WMQ FTE Agent

(WSRR.S TAG .AG ENT)

WSRR

Scripts

File

System

WSRRPROD03

WSRRPROD02

WebSphere S ervice


WebSphere Service

GE P

GE P


WebSphere Service



(WSRR.P RO D.AGE NT)


(WSRR.P RO D.AG ENT)

W MQFTE Agent


WSRR

Scripts

WSRR

Scripts

WSRR

Scripts

S ystem

File

System

Figure 16 Promoting to multiple runtime production environments using ant task parallel

Execute the following steps to implement the enhancement:

1. Install, configure, and customize the supplementary runtime production environments (for example, WSRRPROD02 and WSRRPROD03). The agents running on these additional environments are called WSRR.PROD02.AGENT and WSRR.PROD03.AGENT. To configure these additional runtime production environments, you have to execute the

steps that are described in “Installation” on page 9 and “Configuring and customizing the products” on page 16 again.

2. Add the new properties to the property file for the runtime production environments, for example, promote_to_production.properties

(Example 23 on page 44). Comment the

property dst.agent

out, because we now support the transfer to multiple agents with separate names, for example, WSRR.PROD.AGENT and WSRR.PROD02.AGENT. To determine the agent name running on the runtime environment, we use the target.name

property instead of the dst.agent

property. The promote.parallel

property indicates that we promote to multiple runtime production environments. We now have two options for promotion:

– Promote sequential: Set the promote.sequential

property, and use the dst.agent

property to define the name of the agent. Use this option when there is only one runtime production environment.


– Promote parallel: Set the promote.parallel

property, and use the target.name

property. In this case, you must comment out the dst.agent

property. Use this option when there are multiple runtime production environments.

Example 23 Adding the new properties for parallel promotion

...

# Define the name of the agent running on the runtime environment.

#dst.agent=WSRR.PROD.AGENT

...

#########################################################################

# Additional properties for enhancement parallel promotion

#########################################################################

# Defines the middle part of the name of the agent running on the runtime

# environment. If you run parallel promotion, do not use the property

# dst.agent. Comment it out, see section basic solution.

target.name=PROD

# Defines if the promotion is parallel or sequential. Parallel promotion

# is only supported for the runtime production environment.

promote.parallel=true

#promote.sequential=true

3. Create a new target called

promote_parallel

in the promote.xml

ant script (Example 24).

The target uses the ant task <parallel> to run the filecopy, the import, and the remote archive task in parallel threads. Therefore, the name of the agent has to be determined based on the target.name

property. The new target

promote_parallel

will only be executed when the promote.parallel

property is set. Add the new target

promote_parallel

to the existing default target

complete

. Add the if-condition promote.sequential

to the existing target

promote

. This target

promote

will only be executed when the promote.sequential

property is set.

Example 24 Creating a new target to promote parallel



<target name="complete">

<antcall target="promote_parallel" />

<antcall target="promote" />

</target>



<target name="promote" if="promote.sequential">

<echo message="*** INFO: Promotion started (dst.agent=${dst.agent})" />



<antcall target="archive_remote"/>

<antcall target="archive_local"/>

<echo message="*** INFO: Promotion successfully executed


</target>



<target name="promote_parallel" if="promote.parallel">

<echo message="*** INFO: Parallel promotion started




<parallel>

<antcall target="transfer">

<param name="dst.agent" value="WSRR.${target.name}.AGENT" />

</antcall>

<antcall target="transfer">

<param name="dst.agent" value="WSRR.${target.name}02.AGENT" />

</antcall>

</parallel>



<parallel>

<antcall target="import">


</antcall>

<antcall target="import">


</antcall>

</parallel>



<parallel>

<antcall target="archive_remote">


</antcall>

<antcall target="archive_remote">


</antcall>

</parallel>



<antcall target="archive_local"/>

<echo message="*** INFO: Parallel promotion successfully executed


</target>

Promoting to multiple runtime environments using monitors

This option of parallel promotion uses the file transfer tasks

ftecopy

and

awaitoutcome

to copy the promotion compressed file to the runtime environments. The import of the promotion compressed file will be triggered by the additional monitors running on the runtime environments. The monitor executes the import script directly on the runtime production environment. The changed elements are bold; see Figure 17 on page 46.


S taging

Life cycle

Productio n

WS RRGM

GE P

WebSphere Service

Registry an d Repository


WMQ FTE Agen t

(WS RR.GM.AG ENT)

Monitor

FTE

S cripts

Promotion

Properties

File

S ystem

Qu eue Manager

(QM_GM)

WebSphere MQ

WS RRSTAG

G EP

WebSphere Service



WMQ FTE Agent

(WSRR.S TAG .AG ENT)

WSRR

Script

File

System

WSRRPROD03

WSRRP ROD02

WebSphere Service

Registry and Repo sitory

WSRRPROD

WebS phere Service


WebSphere Service

GEP


WMQFTE Agent

(WSRR.PROD.AGE NT)

Task

Definition

WMQ FTE Agent

(WSRR.PROD.AG ENT)

W MQFTE Agent


Monitor

Task

Definition

FTE

Scripts

WSRR

Script File

System

File

System

File

System

Figure 17 Promoting to multiple runtime production environments using additional monitors

Execute the following steps to implement the enhancement:

1. Install, configure, and customize the supplementary runtime production environments (for example, WSRRPROD02 and WSRRPROD03). The agents running on these additional environments are called WSRR.PROD02.AGENT and WSRR.PROD03.AGENT. To set up these additional runtime production environments, you have to execute the steps that are

described in “Installation” on page 9 and “Configuring and customizing the products” on page 16 again.

2. Adjust the target promote of the promote.xml

ant script. The target only copies the promotion compressed file to the runtime environments using the file transfer tasks: ftecopy and awaitoutcome. Thus, the transfer of the promotion compressed file is executed in parallel to all runtime production environments. The awaitoutcome task waits until all ftecopy tasks have been executed. Remove the import from that target, because the import is triggered by the monitors running on the runtime environments directly.

3. Create a new monitor on each runtime production environment. The monitor observes the

C:\solution\promotion directory and triggers a new task definition when a compressed file for the runtime production environment arrives.

4. Create a new task definition and a new ant script. The task definition executes the ant script. The ant script executes the import of the promotion compressed file.

Note that you only need to change the promotion to the runtime production environment. The promotion to the runtime staging environment remains unchanged.


Troubleshooting

This section provides an overview of the various log mechanisms of WebSphere MQ File

Transfer Edition and WebSphere Service Registry and Repository. In case you run into problems and your solution does not work as expected, look here first for additional information. If the promotion does not work, try to test each step individually. Later on, integrate the steps.

WebSphere MQ File Transfer Edition: Agent log files

Each agent has its own log file (Example 25). Make sure that the agent starts successfully.

You can adjust the log level for each agent (Example 26). You can temporarily change the trace level for a single command (Example 27 on page 48).

Example 25 Sample log file of an agent

C:\Program Files\IBM\WMQFTE\config\QM_GM\agents\WSRR.PROD.AGENT\logs>more output0.log

************ Start Display Current Environment ************

Build level: V7.0.2 f702-GM5-20091117-1614

Java runtime version:

J2RE 1.5.0 IBM J9 2.3 Windows XP x86-32 j9vmwi3223ifx-20080811 (JIT enabled)

J9VM - 20080809_21892_lHdSMr

JIT - 20080620_1845_r8

GC - 200806_19

ICU4J version: Unable to determine ICU4J version (ICU4J is disabled)

Properties:

agentDesc=Agent of Production (PROD), agentName=WSRR.PROD.AGENT, agentQMgr=QM_GM

agentQMgrChannel=SYSTEM.DEF.SVRCONN, agentQMgrHost=WSRRGM, agentQMgrPort=1414

coordinationQMgr=QM_GM, coordinationQMgrChannel=SYSTEM.DEF.SVRCONN, coordinationQMgrHost=WSRRGM

coordinationQMgrPort=1414, transferRoot=C:\Documents and Settings\admin

Install Locations:

com.ibm.wmqfte.product.root=C:\Program Files\IBM\WMQFTE

com.ibm.wmqfte.product.config=C:\Program Files\IBM\WMQFTE\config

************* End Display Current Environment *************

[22/07/2010 14:16:07:828 PDT] 00000001 Agent I BFGAG0115I: Relative path transfer root directory: C:\Documents and Settings\admin

[22/07/2010 14:16:07:875 PDT] 00000001 AgentRuntime I BFGAG0058I: The agent has successfully initialized.

[22/07/2010 14:16:09:937 PDT] 00000001 AgentRuntime I BFGAG0059I: The agent has been successfully started.

Example 26 Changing the trace level of an agent

C:\Program Files\IBM\WMQFTE\config\QM_GM\agents\WSRR.PROD.AGENT\logs>fteSetAgent

TraceLevel -traceLevel all WSRR.PROD.AGENT


BFGCL0091I: The trace request was successfully sent to agent 'WSRR.PROD.AGENT'.


Example 27 Changing the trace level for a single command fteStartAgent -trace com.ibm.wmqfte=all WSRR.GM.AGENT

WebSphere MQ File Transfer Edition: Messages in the SYSTEM.FTE topic

This topic belongs to the coordination queue manager and shows all messages that are sent by all agents, the command-line tools, and the MQ Explorer. If you subscribe to the topic string SYSTEM.FTE/# , you can see all messages, for example, transfer start, progress and end messages, transfer templates, and monitor messages. Follow these steps:

1. On the governance production environment, start MQ Explorer by clicking Start



Programs



IBM WebSphere MQ



WebSphere MQ Explorer.

2. Click IBM WebSphere



Queue Managers



GM_QM



Topics. Open the context menu using the right-mouse button, and click Test Subscription.

3. Enter SYSTEM.FTE/# in the Topic String field. Click Subscribe.

4. In the message received text box, you can see all messages. Before starting a command, click Clear.

5. Analyze the messages. Check if there is an error. It is easier to read the messages if you copy them into a text editor.

WebSphere Service Registry and Repository: JDK log file

The WebSphere Service Registry and Repository uses the Java Logging API. The application server provides this API. This API allows you to change the log level at run time through the admin console. Follow these steps:

1. Log in to the WebSphere Application Server Console, for example: https://localhost:9043/ibm/console/logon.jsp

2. Click Troubleshooting



Logs and Trace



server1



Change Log Level Details, and add com.ibm.sr.promotion.*=all to the existing log levels. Click OK, and Save the configuration.

3. Restart the application server if you have added the log level in the Configuration tab. If you have added the log level in the Runtime tab, it becomes active immediately.

4. Now, you can see the log output in the following log file: C:\Program

Files\IBM\WebSphere\ServiceRegistry\profiles\WSRRSrv01\logs\server1\trace.log

.

Additional material

This section refers to additional material that can be downloaded from the Internet as described. The material that is associated with this paper is available in softcopy on the

Internet from the IBM Redbooks® web server. Point your web browser at: ftp://www.redbooks.ibm.com/redbooks/REDP4688

Alternatively, you can go to the IBM Redbooks web site at: ibm.com/redbooks

Select Additional materials, and open the directory that corresponds with the IBM Redpaper form number, REDP4688.


Related publications and sources of information

򐂰 WebSphere Service Registry and Repository Information Center: http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp

򐂰 WebSphere MQ File Transfer Edition Information Center: http://publib.boulder.ibm.com/infocenter/wmqfte/v7r0/

򐂰 WebSphere MQ Information Center: http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp

򐂰 WebSphere MQ V.7.0.1: http://www-01.ibm.com/software/integration/wmq/requirements/index.html

򐂰 WebSphere MQ File Transfer Edition V7.0.2: http://www-01.ibm.com/software/integration/wmq/filetransfer/requirements/index.

html

򐂰 WebSphere MQ File Transfer Edition Fix Pack 7.0.2.1: http://www-01.ibm.com/support/docview.wss?uid=swg24025878

򐂰 Promotion and classification systems:

– http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm.sr.

doc/cwsr_promotion.html

– http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm.sr.

doc/twsr_configrn_classifications02.html

򐂰 CLI configuration: http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm.sr.do

c/twsr_adminstn_adiministration24.html

򐂰 Governance Enablement Profile tutorial: http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm.sr.do

c/cwsr_gep.html

򐂰 Service Lifecycle Governance with IBM WebSphere Service Registry and Repository,

SG24-7793-00

򐂰 Getting Started with WebSphere MQ File Transfer Edition V7, SG24-7760-00

򐂰 The tutorial Governing an existing service: http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm.sr.do

c/tutorial_gep_govern_existing_service.html

򐂰 The tutorial Governing a new service: http://publib.boulder.ibm.com/infocenter/sr/v7r0/index.jsp?topic=/com.ibm.sr.do

c/tutorial_gep_govern_new_service.html


The author who wrote this paper

This paper was produced by a technical specialist working at the International Technical

Support Organization, Raleigh Center.

Kurt Baumann is an Advisory IT Architect at IBM Switzerland. He has been with IBM for five years and works in IBM Global Business Services®. Kurt holds a degree in Electrical

Engineering and in Software Engineering from the University of Applied Science Rapperswil in Switzerland. He has more than ten years of experience in software architecture and development of Java 2 Platform, Enterprise Edition (J2EE)-based innovative and complex applications.

Thanks to the following people for their contributions to this project:

򐂰 Martin Keen and Linda Robinson

International Technical Support Organization, Raleigh Center

򐂰 David Bell, Richard Cumbers, Ian Heritage, Christopher Jenkins, David Seager, Martin

Smithson, and Matthew Whitehead

IBM Software Group, Application and Integration Middleware Software, Hursley United

Kingdom

򐂰 Maja Gloor and Carla Simioni

Now you can become a published author, too!

Here’s an opportunity to spotlight your skills, grow your career, and become a published author - all at the same time! Join an ITSO residency project and help write a book in your area of expertise, while honing your experience using leading-edge technologies. Your efforts will help to increase product acceptance and client satisfaction, as you expand your network of technical contacts and relationships. Residencies run from two to six weeks in length, and you can participate either in person or as a remote resident working from your home base.

Find out more about the residency program, browse the residency index, and apply online at:

ibm.com/redbooks/residencies.html

Stay connected to IBM Redbooks

򐂰 Find us on Facebook: http://www.facebook.com/pages/IBM-Redbooks/178023492563?ref=ts

򐂰 Follow us on twitter: http://twitter.com/ibmredbooks

򐂰 Look for us on LinkedIn: http://www.linkedin.com/groups?home=&gid=2130806

򐂰 Explore new Redbooks publications, residencies, and workshops with the IBM Redbooks weekly newsletter: https://www.redbooks.ibm.com/Redbooks.nsf/subscribe?OpenForm

򐂰 Stay current on recent Redbooks publications with RSS Feeds: http://www.redbooks.ibm.com/rss.html


Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such

provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION

PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR

IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,

MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products.

All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

© Copyright International Business Machines Corporation 2010. All rights reserved.

Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by

GSA ADP Schedule Contract with IBM Corp.

51

This document REDP-4688-00 was created or updated on September 21, 2010.

Send us your comments in one of the following ways:

򐂰 Use the online Contact us review Redbooks form found at:

ibm.com/redbooks

򐂰 Send your comments in an email to: redbooks@us.ibm.com

򐂰 Mail your comments to:

IBM Corporation, International Technical Support Organization

Dept. HYTD Mail Station P099

2455 South Road

Poughkeepsie, NY 12601-5400 U.S.A.

®

Red

paper

™

Trademarks

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines

Corporation in the United States, other countries, or both. These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (® or ™), indicating US registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml

The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:

Global Business Services®

IBM®

Redbooks®

Redpaper™

Redbooks (logo)

WebSphere®

® z/OS®

The following terms are trademarks of other companies:

Java, and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.