SOAP Internal Design

Contents ShowHide

This section will explain the system-to-system integration process and the methods used to accomplish the integration. With the need for integration between the old and new system a non-intrusive method of data transfer is needed. This transfer method will be SOAP - Simple Object Access Protocol.

The following sections will describe how the SOAP protocol will be implemented.

General

The SOAP protocol defines the use of XML (Extensible Markup Language) and HTTP (Hyper Text Transport Protocol) to access services, objects, and servers in a platform-independent manner. The SOAP Protocol is based on a Request /Response pattern. A request is made from the client application and a response is returned by the called method.

The request will contain the method name that will be called to process the data sent with the request. The called method runs and returns a response that will indicate the success or failure of the called method. The client application and called method do not need to reside on the same server but in our implementation they will.

The SOAP request is made up of three components the HTTP header information the SOAP envelope and the SOAP payload. The SOAP envelope and payload are encoded using XML. The SOAP envelope will contain the method name that is being called to process the SOAP payload (there is no special XML identifier for the method name. The SOAP specification indicates that the method name is a positional parameter and that it should immediately follow the SOAP:Body tag). The SOAP payload will contain the data element(s) that will be processed by the called method (see Sections 40.1.1 and 40.2.1 for a list of the data elements).

Example - SOAP Request:

POST //HTTP/1.0

Host: 127.0.0.1

SoapMethodName: #soapStringReverse

Content-Length: 292

Content-Type: text/xml

<SOAP:Envelope xmlns:SOAP="urn:schemas-xmlsoap-org:soap.v1">

<SOAP:encodingStyle="urn:schemas-xmlsoap-org:soap.v1">

<SOAP:Body>

<p:soapStringReverse xmlns:p='www.pdainc.com/VbXml'>

<text>Hello World!</text>

</p:soapStringReverse>

</SOAP:Body>

</SOAP:Envelope>

The SOAP response is also made up of three components they are the HTTP response header the response SOAP envelope and the response SOAP payload. The SOAP envelope will contain the method name from the SOAP request (with the word "response" concatenated to the end of the method name) and the SOAP payload will contain the response from the method called from the SOAP request. The SOAP payload response may contain data element(s) or just a simple response regarding the outcome of the called method from the SOAP request. The response should be enclosed by the <Return> and end </Return> tags.

Example - SOAP Response:

HTTP/1.0 200 OK

Content-Type: text/xml

Content-Length: 275

<SOAP:Envelope xmlns:SOAP='urn:schemas-xmlsoap-org:soap.v1'>

<SOAP:encodingStyle = 'urn:schemas-xmlsoap-org:soap.v1'>

<SOAP:Body>

<p:soapStringReverseResponse xmlns:p='www.pdainc.com/VbXml'>

<Return>!dlroW olleH</Return>

</p:soapStringReverseResponse>

</SOAP:Body>

</SOAP:Envelope>

Soap File Methods

This section will describe the SOAP file import (coming in to the SPIRIT WIC system) and file export (going out of the SPIRIT WIC system) file transfer methods. The SOAP file Import/Export process will be run once a day as part of the End of Day process.

The SOAP file export (Vendor file) will be created and written out as part of the End Of Day process. The Vendor file will take the form of a SOAP Request, once written out it will need to be retrieved and processed by the State to load the States vendor data. Once processed by the State it will need to write a SOAP Response indicating the success or failure of their Vendor data load.

The SOAP file import (Food Instrument file) will be created and written out by the State as a SOAP Request. The End Of Day process will read and process the SOAP Request. The Food Instrument records will be inserted into the SPIRIT database. A SOAP Response indicating the success or failure of the load will be written and will need to be checked by the State before creating the next Food Instrument import file. The Food Instrument import file will contain all the Food Instrument data from the State and will be an update to the data in the SPIRIT database.

The following directory structure on the State Office application server will support these processes.

|--SOAP-

|--FOODINST

|--ARCHIVE -archive of previous runs request files

|--LOG -log files for Food Instrument imports

|--REQUEST -SOAP Food Instrument Request file(s)

|--RESPONSE -SOAP Food Instrument Response file(s)

|--VENDOR

|--ARCHIVE -archive of previous runs request files

|--LOG -log files for Vendor file imports

|--REQUEST -SOAP Vendor Request file

|--RESPONSE -SOAP Vendor Response file

Soap File Import

This SOAP Method will read and process the SOAP file containing all the Food Instrument records from the State System. This SOAP Food Instrument import file will be created by the State End of Day process and formatted as a SOAP Request. Once processed a SOAP Response will be created and written indicating the status returned from the method called from the SOAP Request. This Process will help guarantee that the Food Instrument data remains integrated. The following methods are called to read and process the Food Instrument SOAP import file.

RetrieveFISoapRequest

This method will retrieve/read the Food Instrument SOAP import file from the SOAP/FOODINST/REQUEST directory (see Section 40.4.2).

The SOAP/FOODINST/REQUEST directory will be read to pick up the latest file for processing (based on the files date and time.) The Food Instrument Soap import file is saved as a string.

If no file is present then processing will not take place and no standard error messages will be generated.

VerifySoapMethodHeader

This is a SOAP Utility method that is used to verify that the SOAP method name in the HTTP Header portion of the SOAP request matches the method name in the SOAP Envelope. This helps verify that the information in the SOAP HTTP Header and SOAP Envelope belong together.

If the method names do not match, the system displays the E0174 standard error message and processing is terminated.

RetrieveSoapBody

This is a SOAP Utility method that is used to strip off the HTTP Header data out of the SOAP Food Instrument import file leaving the SOAP XML envelope and SOAP XML payload.

With just the XML left the file can be loaded into the Document Object Model. The document object model will allow the XML file to be split apart (parsed) programmatically.

ProcessSoapRequest

This is a SOAP Utility method that is used to call the other methods to process the Food Instrument SOAP import file. This routine is the main function for processing the SOAP request. The input to this method is the SOAP Envelope from the previous step (See Section 40.4.3.1.3).

VerifySoapVersion

This is a SOAP Utility method that is used to verify that the SOAP request is using a version of SOAP that we can parse. The SOAP Envelope tag is checked to make sure that SOAP.V1 is specified as the SOAP version.

If the SOAP version is not V1, the system sendsthe E0175 standard error message and processing is terminated.

RetrieveSoapMethodName

This is a SOAP Utility method that is used to retrieve the method name that is being requested from the SOAP:Envelope. The placement of the method name is positional and based on the Soap specification. The method name is located immediately following the <SOAP:Body> tag. The method name contains the method that will be called to process the SOAP payload data (in this case to insert the Food Instrument records). If the SOAP method name is not found, the system sends the E0176 standard error message and processing is terminated.

RetrieveSoapObjectName

This is a SOAP Utility method that is used to retrieve the Object name associated with the method name from the SOAP envelope. The SOAP method name is passed into this routine as a parameter and is used to access the SOAP\SOAPXREF.XML file to retrieve the object named associated with the method. The SOAP\SOAPXREF.XML file is parsed to retrieved/read the object name.

The use of the SOAPXREF.XML file allows us to associate an object name to a method name which gives us the ability to have our methods in many different objects. The SOAP cross reference file will also allow us to assign an alias to the method name which will allow us some flexibility if a method name ever changes or we need to associate the alias to a different method. Following is an example of the SOAPXREF.XML file. The ServerName parameter is currently not used. The SOAPXREF.XML file is formatted as XML.

<SoapMethodName>UpdateFIRecords</SoapMethodName>

<ObjectName>SoapWrapper.clsSoapWrapper</ObjectName>

<MethodName>Update_FoodInst_Records_From_Agency</MethodName>

</SoapMethod>

<SoapMethodName>UpdateFIRecords</SoapMethodName>

<ObjectName>SoapWrapper.clsSoapWrapper</ObjectName>

<MethodName>Update_FoodInst_Records</MethodName>

</SoapMethod>

<SoapMethodName>UpdateVendorRecords</SoapMethodName>

<MethodName>Update_State_Vendors_List</MethodName>

</SoapMethod>

</SoapMethods>

</SOAPXREF>

If the SOAP method name is not found in the SOAPXREF.XML file, the system sends the E0177 standard error message and processing is terminated.

CallMethodByName

This is the actual method call that will execute the method that was specified in the SOAP Request (see Section 40.4.3.2.1 for a description of the Update_FoodInst_Records_From_Agency method). The results of this call will be the SOAP Response.

By using the SOAPXREF.XML file to associate the method to an object we can use the Visual Basic CallByName function which will allow us to instantiate the object and then call the method without having to know its name in advance. To instantiate the object we use the CreateObject Visual Basic function. If an error is detected while creating the object, the system sends the E0178 standard error message and processing is terminated.

The results of the CallByName function is the SOAP Response string which is then wrapped in the outer SOAP:Body Response element which is the completed SOAP Response (see Section 40.4.1). The SOAP Response is returned to the ProcessSoapRequest method.

ProcessSoapResponse

This is a SOAP Utility method that is used to process the SOAP Response. This method will parse the SOAP Response to see if a SOAP Fault was thrown. Check what type of result was returned from the backend method that was called from the SOAP Request. And call the necessary functions to process the SOAP Response.

This method will notify the client of the result of the method called by sending messages with the response returned from the method (notifies the client if the run was successful, failed or had errors).

The Response is written out to the SOAP\FOODINST\RESPONSE directory where the State will read the file to verify the status of the Food Instrument load before creating the next Food Instrument SOAP Request file.

Update_FoodInst_Records_From_Agency

This function is used to control the process of replacing all the Food Instrument records. The input to this function is a Food Instrument XML file. The file will contain the SOAP envelope as well as the Food Instrument XML payload.

The XML payload contains the Food Instrument records that will be inserted into the database. The Food Instrument tables are first truncated (deleted) and then the records are inserted. If a record is rejected for any reason it will be written to a log file and a message at the end of the process will be sent stating that errors where detected. It will be up to the State to review the log file and correct any errors.

Once the records have been inserted a backup (archive) of the input to this function is written to the SOAP/FOODINST/ARCHIVE directory for backup purposes.

This function can return one of three possible results.

Failed - Process was not completed and updates were rolled back.
Errors - Process was completed but errors were detected.
Success - Process was completed without errors.

The following functions are called to process the file.

Load the XML file so the data can be parsed.
Validate_FoodInstrument_XML_File
Validate_FoodInstrument_Agency
Truncate_FoodInstrument_Files
Insert_FoodInstrument_Records
Archieve_FoodInstrument_XML_File

The following is the layout for the Food Instrument XML file minus the Soap Envelope and HTTP header.

<FromMachine>string</FromMachine>

<ToMachine>string</ToMachine>

<Version>string</Version>

<Site_Information>

<Agency_ID>1234</Agency_ID>

<Local_Agency>4321</Local_Agency>

<Participant_Info>

<TransactionCode>string</TransactionCode>

<CurrentWICStatus>string</CurrentWICStatus>

<CreateUserID>string</CreateUserID>

<DateIssued>string</DateIssued>

<WICStatus>string</WICStatus>

<ParticipationMonth>string</ParticipationMonth>

<Priority>string</Priority>

<SubPriority>string</SubPriority>

<First_Date_To_Use>date</First_Date_To_Use>

<Last_Date_To_Use>date</Last_Date_To_Use>

<ComplianceBuy>boolean</ComplianceBuy>

<PC_Create_User>string</PC_Create_User>

<PC_Create_Date>date</PC_Create_Date>

<PC_Modified_User>string</PC_Modified_User>

<PC_Modified_Date>date</PC_Modified_Date>

<SerialNumber>string</SerialNumber>

<StateWICID>string</StateWICID>

<IssuedCode>string</IssuedCode>

<Rebate>string</Rebate>

<PharmacyAllowed>string</PharmacyAllowed>

<VoidedReason>string</VoidedReason>

<ReprintReason>string</ReprintReason>

<ProgramCode>string</ProgramCode>

<StaffIDVoidStolen>string</StaffIDVoidStolen>

<ObligationAmt>number</ObligationAmt>

<PresentmentAmt>number</PresentmentAmt>

<PaidAmt>number</PaidAmt>

<VendorID>string</VendorID>

<PeerGroupID>string</PeerGroupID>

<Stampnumber>string</Stampnumber>

<FoodInstrumentType>string</FoodInstrumentType>

<CreateUserID>string</CreateUserID>

<ModifyUserID>string</ModifyUserID>

<UpdateRecord>string</UpdateRecord>

<SerialNo>string</SerialNo>

<RejectionCode>string</RejectionCode>

<ModifyUserID>string</ModifyUserID>

<UpdateRecord>string</UpdateRecord>

<CreateUserID>string</CreateUserID>

</Rejections>

<FoodItemCode>string</FoodItemCode>

<FoodItemQty>number</FoodItemQty>

<Food_RX_Item_Code>string</Food_RX_Item_Code>

</FoodItem>

</FoodInstrument>

</FoodInstrumentSet>

</Participant_Info>

</Site_Information>

</FoodInstruments>

The following list of edits is performed on the Food Instrument XML data before it is inserted into the Food Instrument tables in the database. In addition to the following edits database referential integrity constraints will also be enforced.

FoodInstrumentSet - Priority value must be 1 thru 7.
FoodInstrumentSet - WICSTATUS must be I, C, B, N, P, F.
FoodInstrument - PaidAmt, PaidDate and VendorID must all be present if any one has a value.
FoodInstrument - VoidedDate and VoidedReason must both be present if either has a value.
FoodInstrument - VoidedDate and ReportedStolenDate are mutually exclusive.

SOAP File Export

This SOAP method will create and write out a SOAP file that contains all the Vendors that are on the SPIRIT WIC system. This file once created will be read and processed by the State to load the State Vendor data. This process will help guarantee that the Vendor data remain integrated. The following methods are called to create the Vendor SOAP export file.

ValidateVendorSoapResponse

This method will read the Vendor SOAP response file from the States previous run of the load process to validate that the Vendor file was loaded successfully. The Vendor SOAP response file will be read from the SOAP/VENDOR/RESPONSE directory (see Section 40.4.2 above).

If the Vendor SOAP response file indicates that the load of the Vendor data by the State was not successful then the SOAP Vendor File Export process will terminate and a standard error message will be sent indicating that an error was detected and that the previous runs data did not get processed.

If the Vendor SOAP response file indicates that the load was successful then the following methods will be called to create the new Vendor SOAP file.

RetrieveVendorData

This method will retrieve the Vendor data from the SPIRIT Oracle table and save it as an XML string. The XML string contains all the Vendor data. All Vendor data in the table is retrieved, no Vendor records are dropped.

The XML element tag names will match the Oracle column names in the database. Following is an example of the XML generated minus the XML schema.

<SOAP:Envelope xmlns:SOAP='urn:schemas-xmlsoap-org:soap.v1'

<SOAP:encodingStyle = 'urn:schemas-xmlsoap-org:soap.v1'>

<SOAP:Body>

<p:Update_Vendor_Records xmlns:p='www.pdainc.com'>

<FROMMACHINE>ralphl</FROMMACHINE>

<TradeName>LIL GENERAL #10</TradeName>

<PhysicalAddress1>14-16 BOUND ROAD </PhysicalAddress1>

<PhysicalAddress2>LIL GENERAL #10 </PhysicalAddress2>

<PhysicalCity>WOONSOCKET</PhysicalCity>

<MailingAddress1>14-16 BOUND ROAD </MailingAddress1>

<MailingAddress2>LIL GENERAL #10 </MailingAddress2>

<MailingCity>WOONSOCKET</MailingCity>

</STAMPINFORMATION>

</VENDORDEMOGRAPHIC>

</VENDORDEMOGRAPHIC>

</VENDORS>

</p:Update_Vendor_Records>

</SOAP Body>

</SOAP Envelope>

Software Version: 2.40.00