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
<?xml version="1.0" encoding="UTF-8"?> <sb:UAC xmlns:sb="http://com.stonebranch/UAC/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://com.stonebranch/UAC/ UAC.xsd"/ <!-- $Id$ --> <sb:SOAPConnection> <sb:URI>/axis2/services/UACInbound</sb:URI> <sb:Listeners> <sb:SOAPListener> <sb:Operation>process</sb:Operation> <sb:Actions> <sb:SOAPFileWriter> <sb:Directory>/export/home/control/indesca/soap_listener/</sb:Directory> <sb:FilenamePattern>process_%Seq%.xml</sb:FilenamePattern> <sb:StartSequenceNumber>1</sb:StartSequenceNumber> <sb:WriteEnvelope>true</sb:WriteEnvelope> </sb:SOAPFileWriter> </sb:Actions> </sb:SOAPListener> </sb:Listeners> </sb:SOAPConnection> </sb:UAC>
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.
<?xml version='1.0' encoding='utf\-8'?><soapenv:Envelope xmlns:soapenv= "http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/ XMLSchema-instance" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soapenv:Body><NS1:process xmlns:NS1="http://inbound.uac.stonebranch.com"> <NS1:identitySourceApplicationId>RBS</NS1:identitySourceApplicationId><NS1:identitySourceUserId /> <NS1:identitySourcePassword /><NS1:identitySourceToken /> <NS1:activityRequestId>AUT4210021109265970293000</NS1:activityRequestId> <NS1:activityStatus>PROCESS CLOSE ACCOUNTING YYYY MM</NS1:activityStatus> <NS1:activityState>ACCOUNTING MONTH CLOSING INPROGRESS</NS1:activityState> <NS1:activityStateReason>INFO</NS1:activityStateReason> <NS1:activityAction>ODPT0001</NS1:activityAction> <NS1:activityStartDate>2010-02-24</NS1:activityStartDate> <NS1:activityStartTime>08:35:42.397382</NS1:activityStartTime></NS1:process></soapenv:Body></soapenv:Envelope>
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.
BEGIN_EVENT EVENT_ID "ABC SOA EVENT" EVENT_TYPE FILE COMP_NAME UEMS STATE ENABLE TRACKING_INT 10 TRIGGERED_ID "ABC SOA HANDLER" FILESPEC "/export/home/ control/indesca/soap_listener/*.*" MIN_FILE_SIZE 0 RENAME_FILE YES RENAME_FILESPEC "/export/home/ control/indesca/soap_listener/$(origname).$(origext)" END_EVENT
Event Definition Options
The Event Definition options used in this example are:
Option | Description |
---|---|
Identifier that uniquely identifies an event definition record. | |
Type of system event represented by the event definition record. | |
Event-driven UEM Server responsible for monitoring the event. | |
Event definitions that should be processed or ignored by UEM. | |
Event definitions that should be processed or ignored by UEM. | |
ID of an event handler record that UEM will execute when an event occurrence is triggered. | |
Name of a file to monitor. | |
Size a file must be in order to be considered complete by UEM. | |
Specifies whether or not UEM should rename a monitored file when an event occurrence is triggered. | |
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.
/opt/universal/bin/uemload -add -deffile event_definition.txt
Command Line Options
The Event Definition options used in this example are:
Option | Description |
---|---|
Writes one or more new event definition and/or event handler records to the appropriate database. | |
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:
/opt/universal/bin/uemload -update -deffile event_definition.txt
Command Line Options
The Event Definition options used in this example are:
Option | Description |
---|---|
Changes one or more existing event definition and/or event handler records. | |
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.
BEGIN_HANDLER HANDLER_ID "ABC SOA HANDLER" ACTION_TYPE CMD MAXRC 0 USERID "control" PWD "UACL" BEGIN_SCRIPT STMT "#!/usr/bin/ksh" STMT "exec > /export/home/control/indesca/abc.log 2>&1" STMT "set -xv" STMT "/opt/universal/bin/ucmd -script /export/home/control/indesca/abc.rexx \" STMT "< $UEMRENAMEDFILE \" STMT "-HOST mvstcp5 -USERID CTLMNT -PWD UACL " STMT ">> /export/home/control/indesca/abc.log \" STMT "2>&1" STMT "if [ $? -gt 0 ]" STMT " then" STMT " mv $UEMRENAMEDFILE $UEMORIGFILE" STMT " else" STMT " rm $UEMRENAMEDFILE" STMT "fi" STMT "exit $rc" END_SCRIPT END_HANDLER
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.
/* REXX */ TRACE R ABC.XML = LINEIN() parse value ABC.XML with "<NS1:activityAction>" ABC.ACTN "</NS1:activityAction>" parse value ABC.XML with "<NS1:identitySourceApplicationId>" ABC.APID "</NS1:identitySourceApplicationId>" parse value ABC.XML with "<NS1:activityRequestId>" ABC.RQID "</NS1:activityRequestId>" ABC.UWTO = "EIEOSRAT "ABC.ACTN ABC.APID ABC.RQID '/usr/lpp/universal/bin/uwto -msg "'ABC.UWTO'"' ABC.RC = RC EXIT ABC.RC
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.
BEGIN_EVENT EVENT_ID "ABC LOG FILE CLEANUP" EVENT_TYPE FILE COMP_NAME UEMS STATE ENABLE TRACKING_INT 10 TRIGGERED_ID "ABC LOG FILE CLEANUP" FILESPEC "/export/home/control/indesca/abc.log" MIN_FILE_SIZE 10M END_EVENT BEGIN_HANDLER HANDLER_ID "ABC LOG FILE CLEANUP" HANDLER_TYPE CMD MAXRC 0 USERID "control" PWD "UACL" CMD "rm /export/home/control/indesca/abc.log" END_HANDLER
Event Options
The Event options used in this example are:
Option | Description |
---|---|
Identifier that uniquely identifies an event definition record. | |
Type of system event represented by the event definition record. | |
Event-driven UEM Server responsible for monitoring the event. | |
Event definitions that should be processed or ignored by UEM. | |
Event definitions that should be processed or ignored by UEM. | |
ID of an event handler record that UEM will execute when an event occurrence is triggered. | |
Name of a file to monitor. | |
Size a file must be in order to be considered complete by UEM. | |
Identifier that uniquely identifies an event handler record. | |
Type of process executed for the event handler. | |
Highest value with which a handler can exit to still be considered as having executed successfully. | |
ID of a user account in whose security context the handler process will be executed. | |
Password for the user account specified by userid. | |
Command to execute on behalf of the event handler. |