Pipeline configuration files

The configuration of a pipeline used to handle a web service request is specified in an XML document, known as a pipeline configuration file.

The pipeline configuration file is stored in the z/OS® UNIX System Services file system and its name is specified in the CONFIGFILE attribute of a PIPELINE resource definition. Use a suitable XML editor or text editor to work with your pipeline configuration files. The XML schemas for the pipeline configuration files are in the directory /usr/lpp/cicsts/cicsts52/schemas/pipeline/ (where /usr/lpp/cicsts/cicsts52 is the default install directory for CICS files on CICS® UNIX). When you work with configuration files, ensure that the character set encoding is UTF-8. If you import an existing configuration file that is encoded in EBCDIC, it is automatically converted to UTF-8.

When CICS processes a web service request, it uses a pipeline of one or more message handlers to handle the request. A pipeline is configured to provide aspects of the execution environment that apply to different categories of applications, such as support for web service security, and web service transactions. Typically, a CICS region that has a large number of service provider or service requester applications needs several different pipeline configurations. However, where different applications have similar requirements, they can share the same pipeline configuration.

Note:

When using CICS Explorer® to create a new PIPELINE configuration file as part of a bundle, there must not be a configuration file with the same name in the root of the bundle. End of change

There are two kinds of pipeline configurations: one describes the configuration of a service provider pipeline; the other describes a service requester pipeline. Each is defined by its own schema, and each has a different root element.

Pipeline	Schema	Root element
Service provider	`Provider.xsd`	`<provider_pipeline>`
Service requester	`Requester.xsd`	`<requester_pipeline>`

Although many of the XML elements used are common to both kinds of pipeline configuration, others are used only in one or the other, so you cannot use the same configuration file for both a provider and requester.

Restriction: Namespace-qualified element names are not supported in the pipeline configuration file.

The <provider_pipeline> and <requester_pipeline> elements have the following immediate sub-elements:

A <service> element, which specifies the message handlers that are invoked for every request. This element is mandatory when used within the <provider_pipeline> element, and optional within the <requester_pipeline> element.
An optional <transport> element, which specifies message handlers that are selected at run time, based upon the resources that are being used for the message transport.
For the <provider_pipeline> only, an optional <apphandler> element, which is used to specify channel-attached application handlers.
For the <provider_pipeline> only, an optional <apphandler_class> element, which is used to specify an Axis2 application handler.
An optional <service_parameter_list> element, which contains the parameters that are available to the message handlers in the pipeline.

Certain elements can have attributes associated with them. Each attribute value must have quotes around it to produce a valid XML document.

Associated with the pipeline configuration file is a PIPELINE resource. The attributes include CONFIGFILE, which specifies the name of the pipeline configuration file in z/OS UNIX. When you install a PIPELINE definition, CICS reads the information that it needs in order to configure the pipeline from the file.

CICS supplies sample configuration files that you can use as a basis for developing your own configuration files. They are provided in library /usr/lpp/cicts/cicsts52/samples/pipelines.

basicsoap11provider.xml: A service provider pipeline definition that uses the SOAP 1.1 protocol for a pipeline that does not support Java. The pipeline uses the <cics_soap_1.1_handler> message handler and is used when the CICS application has been deployed using the CICS web services assistant.
basicsoap11requester.xml: A service requester pipeline definition that uses the SOAP 1.1 protocol for a pipeline that does not support Java. The pipeline uses the <cics_soap_1.1_handler> message handler and is used when the CICS application has been deployed using the CICS web services assistant.
basicsoap11javaprovider.xml: A service provider pipeline definition that uses the SOAP 1.1 protocol for a pipeline that supports Java. The pipeline uses the <cics_soap_1.1_handler_java> message handler and is used when the application has been deployed using the CICS web services assistant. This configuration contains the element <jvmserver>. This message handler must be edited to specify the appropriate JVM server before the configuration can be used.
basicsoap11javarequester.xml: A service requester pipeline definition that uses the SOAP 1.1 protocol for a pipeline that supports Java. The pipeline uses the <cics_soap_1.1_handler_java> message handler and is used when the application has been deployed using the CICS web services assistant. This configuration contains the element <jvmserver>. This message handler must be edited to specify the appropriate JVM server before the configuration can be used.
jsonjavaprovider.xml: A service provider pipeline definition that uses the JSON message format for a pipeline that supports Java. The pipeline uses the <cics_json_handler_java> message handler and is used when the CICS application has been deployed using the CICS JSON assistant. This configuration contains the element <jvmserver>. This message handler must be edited to specify the appropriate JVM server before the configuration can be used.
kerberosprovider.xml: A service provider pipeline definition that adds configuration information for Kerberos support to basicsoap11provider.xml.
samlprovider.xml: A service provider pipeline definition that adds configuration information for SAML support to basicsoap11provider.xml.
samlrequester.xml: A service requester pipeline definition that adds configuration information for SAML support to basicsoap11requester.xml.
propagatesamlprovider.xml: A service provider pipeline definition that adds configuration information for SAML support with propagation of SAML information through a CICS transaction to basicsoap11provider.xml.
propagatesamlrequester.xml: A service requester pipeline definition that adds configuration information for SAML support with propagation of SAML information through a CICS transaction to basicsoap11requester.xml.
wsatprovider.xml: A pipeline definition that adds configuration information for web services transactions to basicsoap11provider.xml.
wsatrequester.xml: A pipeline definition that adds configuration information for web services transactions to basicsoap11requester.xml.

Example provider pipeline configuration file (JSON application handler)

This is a simple example of a configuration file for a service provider pipeline that uses the <cics_json_handler_java> element:

<p><?xml version="1.0" encoding="EBCDIC-CP-US"?>
<provider_pipeline xmlns="https://www.ibm.com//software/htp/cics/pipeline">
  <service>
    <terminal_handler>
      <cics_json_handler_java>
        <jvmserver>DFHAXIS</jvmserver>
        <repository>/usr/lpp/cicsts/cicsts52/lib/pipeline/repository</repository>
      </cics_json_handler_java>
    </terminal_handler>
  </service>
  <apphandler_class>com.ibm.cicsts.axis2.CICSAxis2ApplicationHandler</apphandler_class>
</provider_pipeline>

The pipeline contains just one message handler. The handler links to program DFHJSON.

The <provider_pipeline> element is the root element of the pipeline configuration file for a service provider pipeline.
The <service> element specifies the message handlers that are invoked for every request. In the example, there is just one message handler.
The <terminal_handler> element contains the definition of the terminal message handler of the pipeline.
The <cics_json_handler_java> element indicates that the pipeline is a Java-based pipeline and the service handler of the pipeline is a message handler that supports JSON messages.
The <apphandler> element specifies the name of the application handler that the terminal handler of the pipeline links to by default. In this case, the program is DFHJSON, which is the CICS-supplied program for applications deployed with the CICS JSON assistant.

Example provider pipeline configuration file (Channel-attached application handler)

This is a simple example of a configuration file for a service provider pipeline that uses the <cics_soap_1.1_handler> element:

<?xml version="1.0" encoding="EBCDIC-CP-US"?> 
<provider_pipeline 
   xmlns="https://www.ibm.com//software/htp/cics/pipeline"
    <service> 
    <terminal_handler> 
      <cics_soap_1.1_handler/> 
    </terminal_handler> 
  </service> 
  <apphandler>DFHPITP</apphandler> 
</provider_pipeline>

The pipeline contains just one message handler. The handler links to program DFHPITP.

The <provider_pipeline> element is the root element of the pipeline configuration file for a service provider pipeline.
The <service> element specifies the message handlers that are invoked for every request. In the example, there is just one message handler.
The <terminal_handler> element contains the definition of the terminal message handler of the pipeline.
The <cics_soap_1.1_handler> element indicates that the pipeline is not a Java-based pipeline and the terminal handler of the pipeline is a message handler that supports SOAP 1.1 messages.
The <apphandler> element specifies the name of the application handler that the terminal handler of the pipeline links to by default. In this case, the program is DFHPITP, which is the CICS-supplied program for applications deployed with the CICS web services assistant.

Example provider pipeline configuration file (Axis2 application handler)

This is a simple example of a configuration file for a service provider pipeline that uses the <cics_soap_1.1_handler_java> element:

<?xml version="1.0" encoding="EBCDIC-CP-US"?> 
<provider_pipeline 
   xmlns="https://www.ibm.com//software/htp/cics/pipeline"
    <service> 
    <terminal_handler> 
      <cics_soap_1.1_handler_java> 
      <jvmserver>DFHAXIS</jvmserver>
      </cics_soap_1.1_handler_java>
    </terminal_handler> 
  </service> 
  <apphandler_class>com.ibm.cicsts.axis2.CICSAxis2ApplicationHandler</apphandler_class> 
</provider_pipeline>

The pipeline contains just one message handler. The handler links to program DFHPITP.

The <provider_pipeline> element is the root element of the pipeline configuration file for a service provider pipeline.
The <service> element specifies the message handlers that are invoked for every request. In the example, there is just one message handler.
The <terminal_handler> element contains the definition of the terminal message handler of the pipeline.
The <cics_soap_1.1_handler_java> element indicates that the pipeline is a Java-based pipeline and the service handler of the pipeline is a message handler that supports SOAP 1.1 messages.
The <apphandler_class> element specifies the supplied Axis2 application handler.

Example requester pipeline configuration file

This is a simple example of a configuration file for a service requester pipeline that uses the <cics_soap_1.2_handler_java> element with Axis2 MTOM/XOP support:

<?xml version="1.0" encoding="EBCDIC-CP-US"?>
<requester_pipeline 
  xmlns="https://www.ibm.com//software/htp/cics/pipeline">
   <service>
     <service_handler_list>           
       <cics_soap_1.2_handler_java>
         <jvmserver>JVMSERV1</jvmserver>
         <mtom>
       </cics_soap_1.2_handler_java>
     </service_handler_list>          
   </service>
</requester_pipeline>

The pipeline contains just one message handler.

The <requester_pipeline> element is the root element of the pipeline configuration file for a service requester pipeline.
The <service> element specifies the message handlers that are invoked for every request. In the example, there is just one message handler.
The <service_handler_list> specifies a list of message handlers that are invoked for every request.
The <cics_soap_1.2_handler_java> element indicates that the pipeline supports Java and the service handler of the pipeline is a message handler that supports SOAP 1.2 messages.
The <jvmserver> element specifies the JVM server to be used.
The <mtom/> element specifies that outbound XOP documents are packaged into MTOM messages and sent. By default, inbound MTOM messages are accepted and unpackaged for Java-based pipelines.