webMethods Adapter

How the webMethods Adapter Works

The webMethods adapter has two parts and supports four basic operations.

Adapter Components

Basic Operations

These operations enable you to perform basic webMethods transactions. The following sections provide details.

Synchronous Request/Response Operation

The following figure shows the synchronous request/response operation for communicating with the webMethods Enterprise server. Only a webMethods Publisher adapter runs in this operation.

Invoke Business Process Asynchronously Operation

The following figure shows starting a business process asynchronously to communicate with the webMethods Enterprise server. Only a webMethods Subscriber adapter runs in this operation.

Fire-and-Forget Operation

The following figure shows the fire-and-forget operation for communicating with the webMethods Enterprise server. Only a webMethods Publisher adapter runs in this operation.

Asynchronous with Transactionality Operation

The asynchronous with transactionality operation runs both a webMethods Publisher adapter and a webMethods Subscriber adapter that connect to the same webMethods Enterprise server. Each transaction is associated with a unique transaction ID.

The following figure shows the asynchronous with transactionality operation:

Structure of Input and Output Data

To publish an event to the webMethods Enterprise server, a webMethods Publisher adapter reads the primary document, which is an XML document, from the business process and translates the primary document to a webMethods event. When the webMethods Publisher adapter receives a reply event or the webMethods Subscriber adapter receives an event from the webMethods Enterprise server, the adapter translates that event to an XML document and sets that document as the primary document of the business process.

The following sections describe the translation between the webMethods event and the XML primary document. Find all the examples in the samples directory.

Basic Structure

The following sample XML document must be translated to an event and published to the webMethods Enterprise server:

<WebmethodsAdapter>
	<event name="Sample::GetCustomerAllFields">
	<customerId>14621</customerId>
	<customerFirstName>Joe</customerFirstName>
	<customerLastName>Smith</customerLastName>
	</event> 
</WebmethodsAdapter>

The root element must always be WebmethodsAdapter.

The event information is wrapped in the event element, which has an attribute named name. The value of the name attribute is the event type name. The tag name for the event element and its name attribute varies depending on your locale. For more information about locale settings, see Internationalization.

The fields of the event element are its child elements. The element name is the field name, and the content text is the field value.

The following sample code shows the translation of the XML document to a webMethods event:

eventtype Sample::GetCustomerAllFields {
	int customerId;
	unicode_string customerFirstName;
	unicode_string customerLastName; 
}

Structure Data Field

In a webMethods event, a structure data field is an event field with a user-defined type. It can contain simple data types, arrays, or other structures. When a structure data field is translated to an XML element, the structure name translates as the element tag, and the members of the structure data field translate as the child elements.

The following sample code shows a structure data field in a webMethods event:

eventtype Sample::GetCustomerAllFieldsStruct {
	struct {
	int customerId;
	struct {
	unicode_string customerFirstName;
	unicode_string customerLastName;
	} customerName;
	} customer;
	boolean current;
	byte document;
	string socSecNumber;
	unicode_char billPaid; 
}

The following sample code shows the translation of the structure data field to XML:

<WebmethodsAdapter>
	<event name="Sample::GetCustomerAllFieldsStruct">
	<customer>
	<customerName>
	<customerFirstName>Joe</customerFirstName>
	<customerLastName>Smith</customerLastName>
	</customerName>
	<customerId>14621</customerId>
	</customer>
	<current>true</current>
	<document>0</document>
	<socSecNumber>123-45-6789</socSecNumber>
	<billPaid>Y</billPaid>
	</event> 
</WebmethodsAdapter>

Sequence Field

When a field of an event is a sequence field, add the attribute type=“seq” to the element for this field and expand each member of the sequence into an element with the same name as the sequence field. The tag name for the type attribute varies depending on your locale. For more information about locale settings, see Internationalization.

The following sample code shows a sequence field in a webMethods event:

eventtype Sample::GetCustomerAllFieldsSeq {
	string depts[]; 
}

The following sample code shows the translation of the sequence field to XML:

<WebmethodsAdapter>
	<event name="Sample::GetCustomerAllFieldsSeq">
	<depts type="seq">
	<depts>sales</depts>
	<depts>marketing</depts>
	</depts>
	</event> 
</WebmethodsAdapter>

Sequence of Structures Field

The tag names for the element and type attributes vary depending on your locale. For more information about locale settings, see Internationalization.

The following sample code shows a sequence of structures field in a webMethods event:

eventtype Sample::GetCustomerAllFieldsSeqOfStructs {
	struct {
	unicode_string name;
	unicode_string industry;
	} company[]; 
}

The following sample code shows the translation of the sequence of structures field to XML:

<WebmethodsAdapter>
	<event name="Sample::GetCustomerAllFieldsSeqOfStructs">
	<company element="struct" type="seq">
	<company>
	<name>ACME</name>
	<industry>food</industry>
	</company>
	<company>
	<name>Computer World</name>
	<industry>computer</industry>
	</company>
	<company>
	<name>Bob's Convenience Store</name>
	<industry>retail</industry>
	</company>
	</company>
	</event> 
</WebmethodsAdapter>

Sequence of Sequences Field

The tag names for the element and type attributes vary depending on your locale. For more information about locale settings, see Internationalization.

The following sample code shows a sequence of sequences field in a webMethods event:

eventtype Sample::GetCustomerAllFieldsSeqOfSeqs {
	string depts[][][]; 
}

The following sample code shows the translation of the sequence of sequences field to XML:

<WebmethodsAdapter>
	<event name="Sample::GetCustomerAllFieldsSeqOfSeqs">
	<!-- sales & marketing depts -->
	<depts element="seq" type="seq">
	<!-- sales -->
	<depts element="seq" type="seq">
	<!-- sales America -->
	<depts type="seq">
	<depts>sales America East</depts>
	<depts>sales America Central</depts>
	<depts>sales America West</depts>
	</depts>
	<!-- sales Europe -->
	<depts type="seq">
	<depts>sales Europe East</depts>
	<depts>sales Europe Central</depts>
	<depts>sales Europe West</depts>
	</depts>
	</depts>
	<!-- Marketing -->
	<depts element="seq" type="seq">
	<!-- marketing America -->
	<depts type="seq">
	<depts>mktg America East</depts>
	<depts>mktg America Central</depts>
	<depts>mktg America West</depts>
	</depts>
	<!-- marketing Europe -->
	<depts type="seq">
	<depts>mktg Europe East</depts>
	<depts>mktg Europe Central</depts>
	<depts>mktg Europe West</depts>
	</depts>
	</depts>
	</depts>
	</event> 
</WebmethodsAdapter>

Installing the webMethods Adapter

Implementing the webMethods Publisher Adapter

The webMethods Publisher adapter enables business processes that run in Sterling B2B Integrator to publish events to a webMethods Enterprise server.

You can create multiple configurations of the webMethods Publisher adapter. Because the client group defines which events a webMethods Publisher adapter has permission to publish, you must configure a separate instance of the adapter for each client group.

Configuring the webMethods Publisher Adapter

Sterling B2B Integrator Configuration

The following table describes the fields used to configure a webMethods Publisher adapter in Sterling B2B Integrator:

GPM Configuration

The following table describes the fields used to configure a webMethods Publisher adapter in the GPM:

Sample BPML

The following sample BPML is for a webMethods Publisher adapter:

...
	<operation name="Webmethods Publisher">
	<participant name="Webmethods Publisher"/>
	<output message="WebmethodsInputMessage">
	<assign to="." from="*"</assign>
	<assign to="webmethodsTimeOut">5000</assign>
	<assign to="webmethodsSynchronousFlag">true</assign>
	<assign to="language">fr</assign>
	<assign to="country">FR</assign>
	</output>
	<input message="inmsg">
	<assign to="." from="*"></assign>
	</input>
	</operation> 
...

Find this sample BPML in the samples directory.

Data Flow

Error Messages

When a business process runs a webMethods Publisher adapter, the adapter can return the following error messages in the Advance Status field. The adapter logs more detailed error information in the log files.

Implementing the webMethods Subscriber Adapter

The webMethods Subscriber adapter enables Sterling B2B Integrator users to subscribe to webMethods events. When an event is received from the webMethods Enterprise server, a user-specified business process is started in Sterling B2B Integrator.

When you create and save a configuration of the webMethods Subscriber adapter, the adapter starts and subscribes to all events specified in Sterling B2B Integrator. No business process can explicitly run this adapter. You must specify a business process related to each event. This is the business process Sterling B2B Integrator starts when it receives the specified event from the webMethods Enterprise server.

Creating a webMethods Subscriber Adapter Configuration

The following tables describe the fields used to configure a webMethods Subscriber adapter in Sterling B2B Integrator and connections for the webMethods Subscriber adapter in a property file.

Sterling B2B Integrator Configuration

The following table describes the fields used to configure the webMethods Subscriber adapter in Sterling B2B Integrator:

To create a webMethods Subscriber adapter with different hosts, ports, broker names, client groups, or security parameters, you must create multiple configurations of the adapter. Each configuration defines a unique set of parameters.

Configuring the Property File

The webMethods Subscriber adapter polls the webMethods Enterprise server periodically to determine whether the adapter is still connected to the server. You must configure connection management parameters in the property file. The webmethods.properties file is located in install_dir/properties/adapter_conf, where install_dir is your Sterling B2B Integrator installation directory.

The following table describes the fields used to configure the connection management parameters in the property file:

Data Flow

When you update the configuration of a webMethods Subscriber adapter—change the Webmethods Host, Webmethods Port, Broker Name, Client Group, Certification File, Password, or Distinguished Name parameter—the connection to the webMethods Enterprise server ends, and a new connection is made.

Error Messages

The webMethods Subscriber adapter starts when you save its configuration, either new or updated, in Sterling B2B Integrator. If the adapter starts successfully, no error logs are created. If the adapter does not start successfully, errors are logged and the adapter does not run.

The webMethods Subscriber adapter can log the following error messages:

DTD Generator

Use the DTD generator from a computer that has an instance of Sterling B2B Integrator with the DTD generator and can communicate with the webMethods Enterprise server.

To use the DTD generator, run the following command under your ${INSTALL_DIR}/bin directory:

run WMDtdGenerator.sh

The DTD generator provides both a command line interface and an interactive interface. Use the following syntax for the command line interface:

run WMDtdGenerator.sh
-h <host> -p <port> -c <client group> -b <broker name>
-e <event name> -f <output file name> -l -noDTD 

The following table describes the options you can define on the command line:

The DTD generator prompts for any information it needs that you do not provide on the command line. To run the DTD generator in interactive mode, do not include any options and it will prompt you for them.

Security

The webMethods software provides support for authentication using digital certificates. The webMethods adapter supports communicating with the webMethods Enterprise server through SSL and certificates. Authentication is optional depending on how you configure the webMethods adapter and the webMethods Enterprise server to meet user security requirements. For information about SSL support of the webMethods Enterprise server as well as how to obtain a certificate, see the webMethods documentation.

For information about configuring the security parameters (certificate file, password, distinguished name), see Configuring the webMethods Publisher Adapter and Creating a webMethods Subscriber Adapter Configuration.

For the webMethods adapter to use SSL to communicate with the webMethods Enterprise server, you must also specify the SSL shared library file. For information about installing the SSL shared library, see Installing the webMethods Adapter.

Internationalization

You can specify language, country, and variant in the GPM. These parameters define the internationalization rules the webMethods Publisher adapter uses when translating the input and output documents. If you do not specify language, country, or variant, the adapter uses English.

For information about how the adapter translates input and output documents, see Structure of Input and Output Data.