Inbound Implementation - SOAP

Inbound Implementation - SOAP

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 (UNIX)

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 UAC.xml (Windows)

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:

c:\tmp\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.

Components

Universal Event Monitor

UEMLoad

Universal Event Monitor for SOA

Universal Broker

Universal Write-to-Operator