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
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.

/opt/universal/bin/uemload -add -deffile event_definition.txt

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:

/opt/universal/bin/uemload -update -deffile event_definition.txt

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.

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
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.