Configuring a Call
Configuring a call using the Outbound Service Connector involves three steps:
- A service endpoint needs to be configured in the service registry.
- A message template needs to be created.
- OIPA needs to be configured to call the OSC extension and pass in data.
Service Definitions
A service endpoint identifies the technical details of where the message will be delivered and the template that should be used to create the message. This definition also contains the service ID that will be used elsewhere to identify the service.
There are several supported service types:
- SOAP services for invoking SOAP endpoints over HTTP
- file services for writing text to the file system
- Java Message Services for delivering text to JMS endpoints.
Each type of service requires different information to perform its function, but all services are defined in a common registry.
General Service Configuration
The root tag of the service-registry.xml file is <Services>. There are no XML namespaces used.
Each service is defined using a <Service> tag, a sub-element of <Services>. There are several elements common to every service definition.
Node | Required | Description |
---|---|---|
/Services/Service/@id | Yes | Used to identify service by the configuration. Must be unique. |
/Services/Service/@type | Yes | Defines the service type. Valid values are soap, file, and jms. |
/Services/Service/TemplateName | Yes | Defines the template key for this service. |
SOAP Service
A SOAP service allows for the delivery of XML messages to a SOAP endpoint over HTTP. The associated template is responsible for defining the contents of the SOAP Body, while the service manages construction of the SOAP message itself in accordance with a provided WSDL.
The service definition is required to provide a WSDL, and to identify the service and port to be invoked. Several additional options allow for overriding default parameters.
Node | Required | Description |
---|---|---|
/Services/Service/WSDLLocation | Yes | Specifies the URL of the WSDL for the service. |
/Services/Service/ServiceName | Yes | Specifies the name of the service (defined in the WSDL) to be called. Must be a valid QName. |
/Services/Service/ServicePort | Yes | Specifies the port of the service (defined in the WSDL) to be called. Must be a valid QName. |
/Services/Service/ServiceLocation | No | Overrides the service location in the WSDL with a specified value. Must be a valid URL. |
/Services/Service/SOAPAction | No | Overrides the SOAP Action specified in the WSDL. See note below before including this tag. |
/Services/Service/IgnoreResponse | No | Ignores the response from the service and returns success immediately. Valid options are true and false. The default is false. |
/Services/Service/SecurityType | No | Can be used to override WS-Security or WS-Policy information. |
Additional SOAP Considerations
The QName format is the text equivalent of the Java QName class. It specifies the Qualified Name of an element in a document. A QName is printed as {Namespace URI}Local Part. Also note that, in the case of a WSDL, the Namespace URI is the target namespace of the document, not the WSDL's namespace.
If a WSDL is not published for a service (or not available to the OIPA system online) it can be provided locally. Simply specify the WSDL URL location using a file:// prefix instead of http://.
SOAPActionIssues, the presence of the SOAP Action header in a SOAP message has meaning. Some services will expect to receive no header, some will expect a blank header, and some may expect a header with a value.For an absent SOAP Action header, neither the WSDL nor the service definition can include any reference to the header.For a blank SOAP Action header, provide the <SOAPAction> tag with no value in the service definition.In general, you can ignore this tag and omit it from service-registry.xml.
- Waiting for a Response: If the <IgnoreResponse> tag is used and has a value of true, then the OSC will not wait for a return value from the service. This means several things from an execution perspective:
- The plugin will still generate errors if there are issues opening a connection with the service or if a transmission error occurs while sending the message.
- The result of successful transmission will always be <Success/>.
- The plugin will not generate errors if the remote system was unable to understand or process the message.
There can be no assurance that the message was successfully received with a true value.
WebSphere-Specific Notes
Make sure the service name and port are identifying the correct namespace. The correct namespace is the XML namespace specified in the WSDL.
Add an empty SOAPACTION, since an empty SOAP action existed in the WSDL. The service being consumed may or may not have a SOAP action. Simply search for the SOAP action in the WSDL to see if one exists.
Modify the FreeMarker template to include the namespace in the template itself, as this gets injected directly into the body of the SOAP message.
It is helpful to use soapUI, as it gives the correct format of the SOAP packet.
It's recommended that TCPMon be used as an interceptor between the OSC extension and the service it is calling. This allows the user to inspect the SOAP packet that OSC is sending and compare it against the packet that soapUI is sending.
An example FreeMarker template that includes the XML namespace declaration:
<sayHello xmlns="http://osc.example.org/"/>
An example service-registry.xml file— notice the empty SOAPACTION tag:
<Service id="greetings" type="soap">
<TemplateName>Greetings.ftl</TemplateName>
<WSDLLocation>http://10.154.107.24:9999/osc/GreetingService.wsdl</WSDLLocation>
<ServiceName>{http://osc.example.org/\}GreetingService</ServiceName>
<ServicePort>{http://osc.example.org/\}GreetingServiceEndpointPort</ServicePort>
<SOAPAction/>
</Service>
File Service
A file service allows for the delivery of any textual data to the server's file system. In general, this should be leveraged with a remote file sharing protocol (NFS, Samba, etc.) or a scheduled FTP task to collate files between servers.
A service definition is required to provide a directory where files should be written. Several additional tags control the naming of files and replacement handling.
Node | Required | Description |
---|---|---|
/Services/Service/Directory | Yes | The directory where files will be written. |
/Services/Service/FileNameType | No | The type of naming scheme to use. Valid options are Random, Reference, and Simple. The default value is Random. |
/Services/Service/FileName | No | This element has no effect with the Random naming scheme. With Reference, it is the name of a variable in the context that holds the desired file name. With Simple, it is the name of the file. |
/Services/Service/ReplaceExisting | No | If this element has a value of true, then a file of the same name as the requested output name will be overwritten. With a value of false, an existing file of the same name will cause an error. The default is false. |
Reports
Using a Simple file name and ReplaceExisting makes it easier to export batch reports to the file system as part of Plan or Company level processing. Don't forget to ensure output names are unique between reports.
JMS Service
A JMS service allows for the delivery of any textual data to a JMS-mapped destination (queue or topic).
A connection factory and destination are both required for delivery. Optional requirements include the QoS specifications for time to live and priority. These values should map to their relevant JMS values.
Node | Required | Description |
---|---|---|
/Services/Service/ConnectionFactory | Yes | The JNDI name of the JMS Connection Factory. |
/Services/Service/Destination | Yes | The JNDI name of the JMS Destination. |
/Services/Service/TimeToLive | No | The message life time in milliseconds (0–Unlimited). |
/Services/Service/Priority | No | The priority of the message (Low: 0, High: 9, Default: 4). |