Configuring on SAP PI

When you wish to create a communication path from the Integration Server or the PCK to a program or subprogram on the remote host, some configuration steps are required, as described below.


Overview

You use the Software AG PI Adapter for EntireX to connect the Integration Server to back-end applications. It enables messages to be exchanged by converting the PI message format to an EntireX RPC call and converting the result of the RPC call back to a PI message. You configure the adapter in the configuration part of the Integration Builder or the PCK.

To convert PI messages from the Integration Server/PCK to an EntireX RPC call, you configure the Receiver Adapter.

To convert calls from a Software AG RPC client to PI messages for the Integration Server or the PCK, you configure the Sender Adapter.

Constraints

Note the following restrictions:

  • Only the payload of a received PI message is evaluated. Additional attachments are ignored and not forwarded.

  • Each message contains one RPC call; conversational RPC calls are not possible.

Configuring the Receiver Adapter

Use

You need to configure the receiver adapter to be able to convert PI messages from the Integration Server or the PCK into EntireX RPC calls to the corresponding RPC Server.

Integration

You configure the adapter on the Parameters tab page during the definition of a communication channel in the Integration Builder or in the PCK.

Prerequisites

  • You have created a new communication channel or have opened an existing one.

  • On the Parameters tab page you have selected the adapter type EntireX.

  • You have selected the Receiver radio button to define the adapter as a receiver adapter.

  • You have created an XMM file using the EntireX Workbench and stored it in a location accessible (either via file or HTTP access) by the machine which runs the Integration Server or the PCK.

Activities

To configure the adapter, make sure the following values are specified:

Protocol Value
Transport Protocol TCP/IP
Message Protocol EntireX RPC
EntireX Reliable RPC

Select "EntireX Reliable RPC" to use asynchronous reliable messaging for RPC. The RPC server needs to support Reliable RPC.

Adapter Engine

Select the Adapter Engine on the Integration Server, or select a non-centrally installed Adapter Engine. This selection is not available in the PCK.

Connection Parameters

Parameter Selection
Host IP name or address of the host machine where the broker is running. This parameter is mandatory.
Port The corresponding port number. If omitted the default port 1971 is used.
Use Logon Authentication Set this indicator if the broker is running with security.
Logon User The user ID used for authentication. This parameter is mandatory if Use Logon Authentication is enabled.
Logon Password The corresponding password for this user ID. This parameter is mandatory if Use Logon Authentication is enabled.

RPC Client Parameters

Parameter Selection
Location of XMM File

Specify the location of the XMM file (generated by the EntireX Workbench).

The location can be either an absolute file name, or a file URL or an HTTP URL.

Note that this location is evaluated during adapter runtime so it must be accessible by the machine where the Adapter Engine is running.

If you are running the Adapter Engine in a clustered environment, make sure that the XMM file is accessible at the same location on all machines in the cluster.

This parameter is mandatory.

RPC Server Address

The address the EntireX RPC server used to register itself.

The server address can be specified either:

  • as a triplet of ServerClass/ServerName/ServiceName (for example RPC/SRV1/CALLNAT), or

  • using the ServerName only. In this case RPC is used as the default for ServerClass and CALLNAT is used as the default for ServiceName, for example RPC/ServerName/CALLNAT.

This parameter is mandatory and is case sensitive!

RPC User The user ID used for authentication. This parameter is mandatory if Use EntireX RPC Server Authentication is enabled.
RPC Password The corresponding password for this user ID. This parameter is mandatory if Use EntireX RPC Server Authentication is enabled.

Parameters for Quality of Service Exactly Once (in Order)

The following parameters are only used when the PI message which is received by the Adapter has one of the Quality of Service attributes Exactly Once or Exactly Once in Order.

Parameter Selection
First Parameter of RPC Program is used as Message ID (UUID / GUID) The called RPC program will receive the unique message ID of the PI message in the first parameter. The format of this parameter has to be A36. The RPC program may use this parameter for duplicate message detection. This parameter is not available for Reliable RPC.
Time Period for Duplicate Check for EO(IO) (secs) To check for duplicate messages, message IDs must be saved in the database. To prevent the database from getting unnecessarily large, these message IDs must be deleted after a certain amount of time. Specify in seconds the time period after which you want message IDs to be deleted (after one day, for example, if you check message monitoring daily). The default is 86400 seconds (1 day).

Adapter Status

Set the adapter to Active to enable messages to be exchanged.

Advanced Mode

To specify additional parameters, set the Advanced Mode indicator.

Parameter Selection
EntireX RPC Library Name The RPC Library Name is used by many RPC Servers to locate the called subprogram. The default is the library name specified in the IDL file. Use this parameter to specify a library name different from the default one.
Timeout Override the default for the wait timeout for the RPC call. The default is 60s. Values can be specified in hours, minutes, or seconds (e.g. 1h, 10m, 30s).
Transport Compression Specify if transport compression should be used. For details see the EntireX documentation.
Table

Enter the parameter names and parameter values in the Additional Parameters table.

Use the parameter entirex.encoding to specify the encoding for the data of the RPC call. The standard platform encoding of the JVM is used as default.

Use the parameter entirex.timeout to specify the value for the TCP/IP timeout in seconds. The default value is 5 seconds. Note that this is a channel-independent setting used for all TCP/IP host connections.

Configuring the Sender Adapter

Use

You need to configure the sender adapter to be able to receive calls from an EntireX RPC client and convert them to PI messages for the Integration Server or the PCK.

Integration

You configure the adapter on the Parameters tab page during the definition of a communication channel in the Integration Builder or in the PCK.

Condition for Sender Agreement

The adapter determines the payload of the PI message according to how it is configured. However, the message header information is determined from the sender agreement corresponding to the communication channel.

The following conditions apply to the adapter for the definition of the sender agreement:

  • The communication channel defined here must have exactly one sender agreement.

  • At least the interface name and the sender service must be qualified in the sender agreement. All other fields are optional in accordance with the general rules for defining sender agreements.

Prerequisites

  • You have created a new communication channel or have opened an existing one.

  • On the Parameters tab page you have selected the adapter type EntireX.

  • You have selected the Sender radio button to define the adapter as a sender adapter.

  • You have created an XMM file using the EntireX Workbench and stored it in a location accessible (either via file or HTTP access) by the machine which runs the Integration Server or the PCK.

Activities

To configure the adapter, make sure the following values are specified:

Protocol Value
Transport Protocol TCP/IP
Message Protocol EntireX RPC
EntireX Reliable RPC

Select "EntireX Reliable RPC" to use asynchronous reliable messaging for RPC. The RPC client needs to support Reliable RPC and must use Reliable RPC when sending messages to the PI Adapter.

Adapter Engine

Select the Adapter Engine on the Integration Server, or select a non-centrally installed Adapter Engine. This selection is not available in the PCK.

Connection Parameters

Parameter Selection
Host IP name or address of the host machine where the EntireX Broker is running. This parameter is mandatory.
Port The corresponding port number. If omitted the default port 1971 is used.
Use Logon Authentication Set this indicator if the EntireX Broker is running with security.
Logon User The user ID used for authentication. This parameter is mandatory if Use Logon Authentication is enabled.
Logon Password The corresponding password for this user ID. This parameter is mandatory if Use Logon Authentication is enabled.

RPC Server Parameters

Parameter Selection
Location of XMM File

Specify the location of the XMM file (generated by the EntireX Workbench).

The location can be either an absolute file name or a file URL or an HTTP URL.

Note that this location is evaluated during adapter runtime so it must be accessible by the machine where the Adapter Engine is running.

If you are running the Adapter Engine in a clustered environment, make sure that the XMM file is accessible at the same location on all machines in the cluster.

This parameter is mandatory.

RPC Server Address

The EntireX RPC Server used to register itself.

The server address can be specified either:

  • as a triplet of ServerClass/ServerName/ServiceName (for example RPC/SRV1/CALLNAT), or

  • using the ServerName only. In this case RPC is used as the default for ServerClass and CALLNAT is used as the default for ServiceName, for example RPC/ServerName/CALLNAT.

This parameter is mandatory and is case sensitive.

Processing Type

With this parameter you can define a generic channel which will process all programs (RPC client requests) for this server address. Alternatively you can define a specific channel which will process only the defined RPC program.

Process all Programs: use this channel as a generic channel

Process a specific Program: use this channel as a specific channel

RPC Program

The program name if this channel is defined as a specific channel. This parameter is mandatory if the processing type Process a specific Program is selected.

Routing of Client Requests to Channel Configurations

In general, multiple communication channels can be defined for the same server address. Two server addresses are identical if the combination of host, port and RPC server address are identical. The sender adapter routes an incoming request from an RPC client to the appropriate channel. If an appropriate channel cannot be found an error is returned to the RPC client application.

Routing is based on the program name in the RPC request. Note that the library name is ignored for routing. There is no need for the library name specified in the RPC client request to match the library name in the XMM file (or the IDL file from which the XMM file is generated).

The adapter first checks if a specific channel configuration for the program name exists. If a specific channel exists it is routed to this channel. Multiple channel configurations for the same program result in a configuration error.

A generic channel definition will process all RPC client requests for this server address independent of the program name. As a consequence more than one generic channel definition cannot be defined for the same server address. It is possible to process multiple different programs by the same generic channel definition. In this case a Sender Agreement has to be defined for each RPC program where the Interface Name is identical to the program name.

If both specific and generic channel configurations are defined for the same server address the adapter will first look for a specific channel to process the RPC call. If no specific definition is found the adapter routes the call to the generic channel configuration.

Processing Parameters

Parameter Selection
Quality of Service Specifies how the message is to be processed by the Integration Engine/PCK:
  • Best Effort (synchronous processing)

  • Exactly Once (asynchronous processing with guaranteed execution exactly once)

  • Exactly Once in Order (asynchronous processing using queues, in other words guaranteed execution exactly once and maintaining the sequence of successive messages)

Execution exactly once can be guaranteed only if Reliable RPC is used or if the client application sends a unique message ID.

This parameter is mandatory.

"Best Effort" is not available for Reliable RPC.

First Parameter of RPC Program is used as Message ID (UUID / GUID) The first parameter of the RPC program is used as a unique message ID. The format of this parameter has to be A36. The parameter has to be unique for a specific RPC program only (uniqueness is guaranteed within Adapter, Host/Port, and RPC Server Address).

If the RPC Client application sends a new message it must use a new message ID, if it resends a message it must reuse the same message ID.

This parameter is used for Quality of Service "Exactly Once" or "Exactly Once in Order".

This parameter is not available for Reliable RPC.

Time Period for Duplicate Check for EO(IO) (secs) To check for duplicate messages, message IDs must be saved in the database. To prevent the database from getting unnecessarily large, these message IDs must be deleted after a certain amount of time.

Specify in seconds the time period after which you want message IDs to be deleted (after one day, for example, if you check message monitoring daily). The default is 86400 seconds (1 day).

This parameter is used for Quality of Service "Exactly Once" or "Exactly Once in Order".

Queue Name Specify the queue name. This parameter is mandatory for Quality of Service "Exactly Once in Order". Maximum length is 16 characters (uppercase).

Adapter Status

Set the adapter to Active to enable messages to be exchanged. If the adapter status is set to "Inactive" the adapter will not forward received messages to this channel. If all channels for one server address are either inactive or have a configuration error the adapter will deregister the internal RPC server.

Advanced Mode

To specify additional parameters, set the "Advanced Mode" indicator.

Parameter Selection
Transport Compression Specify if transport compression should be used. For details, see the EntireX documentation.
Table

Enter the parameter names and parameter values in the "Additional Parameters" table.

Use the parameter entirex.encoding to specify the encoding for the data of the RPC call. The standard platform encoding of the JVM is used as default.

Use the parameter entirex.timeout to specify the value for the TCP/IP timeout in seconds. The default value is 5 seconds. Note that this is a channel-independent setting used for all TCP/IP host connections.

Use the parameter max.server.replicates to specify the maximum number of server replicates. The default value is 8 server replicates.

Use the parameter interface.prefix to specify a prefix for the Interface name in case of a generic channel definition.

Use the parameter reconnection.waittime to specify the socket reconnection wait time in seconds. The default value is 12 seconds.

Use the parameter server.receive.waittime to set the receive wait time for sender channels. The default wait time is 30 minutes.

Using SSL/TLS for the Host Connection

To use SSL/TLS instead of TCP/IP, add the following information to the Host and Port parameters:

Connection Parameters

Parameter Selection
Host "ssl://hostname" or "ssl://ipaddress".
Port "portnumber?ssl_parameters"
A description of the SSL parameters can be found in the webMethods EntireX documentation. A typical examples is:
"1958?trust_store=/usr/whatever/trust.jks&verify_server=no".