Inbound SOAP Implementation

Inbound SOAP requests are handled via Universal Event Monitor for SOA.

When Universal Event Monitor for SOA detects an inbound SOAP message, it writes the message payload to a file. Universal Event Monitor detects the file and initiates an action.

The SOAP message payload is parsed to extract information that is used to build a z/OS console message. Universal Command delivers the message from the Linux server to the z/OS mainframe.

Universal Event Monitor for SOA is configured via the /etc/universal/UAC.xml file.

Inbound SOAP Request UAC.xml

If required, additional SOAP connections can be defined to the UAC.xml.

Universal Event Monitor for SOA writes the payload of the inbound SOAP message to the following directory / file mask:

/export/home/control/indesca/soap_listener/process_%Seq%.xml

The variable %Seq% is resolved to a sequence number generated by Universal Event Monitor. The sequence number is incremented by one for each file created and is reset to 1 each time Universal Event Monitor for SOA is started.

Inbound SOAP Request - Message Payload Written to process_%Seq%.xml File

The following shows an example of the inbound message payload written to the process_%Seq%.xml file.

The following fields in the process_%Seq%.xml file are used to create the z/OS console message:

<NS1:identitySourceApplicationId>RBS</NS1:identitySourceApplicationId>
<NS1:activityRequestId>AUT4210021109265970293000</NS1:activityRequestId>
<NS1:activityAction>ODPT0001</NS1:activityAction>

Inbound SOAP Request - Universal Event Monitor Event Definition

The following figure illustrates the event definition that Universal Event Monitor uses to detect the file created by Universal Event Monitor for SOA.

Event Definition Options

The Event Definition options used in this example are:

Option	Description
EVENT_ID	Identifier that uniquely identifies an event definition record.
EVENT_TYPE	Type of system event represented by the event definition record.
COMP_NAME	Event-driven UEM Server responsible for monitoring the event.
STATE	Event definitions that should be processed or ignored by UEM.
TRACKING_INT	Event definitions that should be processed or ignored by UEM.
TRIGGERED_ID	ID of an event handler record that UEM will execute when an event occurrence is triggered.
FILESPEC	Name of a file to monitor.
MIN_FILE_SIZE	Size a file must be in order to be considered complete by UEM.
RENAME_FILE	Specifies whether or not UEM should rename a monitored file when an event occurrence is triggered.
RENAME_FILESPEC	Specifies how a file should be renamed when an event occurrence is triggered.

Loading the Event Definition

The event definition is loaded to Universal Event Monitor using the following command issued on the Linux server running Universal Command Agent for SOA.

Command Line Options

The Event Definition options used in this example are:

Option	Description
-add	Writes one or more new event definition and/or event handler records to the appropriate database.
-deffile	Name of a file that contains event definition and/or event handler parameters.

Changing the Event Definition

Alternatively, changes to the event definition can be effected using the following command:

Command Line Options

The Event Definition options used in this example are:

Option	Description
-update	Changes one or more existing event definition and/or event handler records.
-deffile	Name of a file that contains event definition and/or event handler parameters.

Inbound SOAP Request - Universal Event Monitor Handler Definition

The event definition 'moves' each Process_%Seq$.xml file to a staging directory and invokes a SOA HANDLER.

The following Universal Event Monitor handler definition processes each Process_%Seq%.xml file.

The Event Handler executes under the authority of the USERID control. To allow this userid to authenticate without a password, the following UACL definitions were made to /etc/universal/uacl.conf:

uem_handler control,allow,noauth

Changes to the configuration files require the Universal Broker to be refreshed (see Configuration Refresh).

The Event Handler invokes Universal Command to:

1	Connect to the z/OS mainframe.
2	Execute a REXX script to parse the required information from the process_%Seq%.xml file.
3	Execute the Universal Write-to-Operator utility to write the required console message.

The Event Handler appends logging information to the following file: /export/home/control/indesca/abc.log.

If the Event Handler does not complete successfully, the process_%Seq%.xml file is moved back its original location so that processing can be retried. Otherwise, this file is deleted.

Outbound SOAP Request - abc.rexx

The REXX script executed by the Event Handler is stored on the Linux server running Universal Command Agent for SOA.

The REXX script is executed under the z/OS USS environment under the authority of the USERID CTLMNT. To allow this userid to authenticate without a password, the following UACL definitions were made to TEST.SYS5.UNV.UNVCONF(ACLCFG00):

ucmd_access ALL,*,CTLMNT,allow,noauth

Changes to the configuration files require the Universal Broker to be refreshed (see Configuration Refresh).

The REXX script executes the Universal Write-to-Operator utility in order to write the required message to the z/OS console.

The abc.log file is appended to each time a process_%Seq%.xml is processed. This file is useful as an audit trail and for problem diagnosis.

Outbound SOAP Request - Event and Handler to purge abc.log

In order to ensure that this file does not grow to an unreasonable size, additional Universal Event Monitor Event and Handler have been implemented to purge this file when it reaches 10mb in size.

Event Options

The Event options used in this example are:

Option	Description
EVENT_ID	Identifier that uniquely identifies an event definition record.
EVENT_TYPE	Type of system event represented by the event definition record.
COMP_NAME	Event-driven UEM Server responsible for monitoring the event.
STATE	Event definitions that should be processed or ignored by UEM.
TRACKING_INT	Event definitions that should be processed or ignored by UEM.
TRIGGERED_ID	ID of an event handler record that UEM will execute when an event occurrence is triggered.
FILESPEC	Name of a file to monitor.
MIN_FILE_SIZE	Size a file must be in order to be considered complete by UEM.
HANDLER_ID	Identifier that uniquely identifies an event handler record.
HANDLER_TYPE	Type of process executed for the event handler.
MAXRC	Highest value with which a handler can exit to still be considered as having executed successfully.
USERID	ID of a user account in whose security context the handler process will be executed.
PWD	Password for the user account specified by userid.
CMD	Command to execute on behalf of the event handler.