Formpak Soap Web Services Connection Object (ue_soap_formpak)

Contents

Functionality:

This object allows Beas to establish a connection to a server that runs SOAP Web Services and execute requests that post data to those services, usually the server will return XML formatted responses, the XML response buffer is then accesible to be read by the script that is invoking the object. This objects implements WS-Security headers as it is a requirement from Formpak services.

Requirements:

- Required libraries for SOAP/XML processing: pbdom115.pbd (PBDOM), InternetResult object (n_cst_internet)

Methods:

declare=soap=ue_soap_formpak

Instantiates the ue_soap SOAP Object

send

Parameters:

soap=send=[remote-method]=[endpoint-action]=[xml-body-buffer]

Example:
soap=send=executeGetFormulation=FormulationWebServices=soapbody

Posts the request to the SOAP Web Services:

Example parameters explanation:

executeGetFormulation = Remote method that will be executed
FormulationWebServices = Action that will be attached to the endpoint URL
soapbody = XML buffer that contains the SOAP Request

Properties:

is_post_request	Variable that holds the Post Request that will be sent to the WS server
is_endpoint_action	Soap action: name of the remote action that will be attached to the endpoint URL
is_usernametoken	Username token that is embedded directly on the SOAP request headers
is_soap_string_response	Variable that holds the XML Post Response received from the server
ib_successful	Boolean variable that indicates if the soap response has been succesful, true for success
ib_hasattach	Boolean variable that indicates if the soap response has attachments to be processed, true for success
ib_attachsuccess	Boolean variable that indicates if the attachment has been successfully written to file, true for success
ib_attachmentdata	Blob variable that holds the raw data of the attached file
is_attachment_name	Name of the attachment that has been written to file

Runtime Configuration in Beas:

Before using the SOAP object the following vars must be set on Beas Main Menu > Extras > Configuration Wizard > Formpak Sub-menu:

- SOAP Endpoint

- SOAP Environment URL

- XMLNS Web URL (Namespace Variable)

- Attachments Download directory

- Attachment Extension (Type of files that will be processed as attachments)
- SOAP Services username that will be used to invoke remote services

- SOAP Services password to grant access to the WS

Important Note: these variables can be easily obtained by using a tool like SoapUI, first importing the WSDL files provided by our WS provider (in this case Formpak), then generating test requests, and after that extracting them from the XML/SOAP code that has been automatically generated. This technique should too be used to construct the parameters of the send method in Beasscript (See examples section)

Screenshot:

Example:

Important note: In order to construct the[xml-body-buffer] we use a tool like SoapUI to generate a test request after importing the WSDL file, then we analize the XML request and we only take/use the code that is surrounded by the <web:remotemethod></web> tags, for example in the following SOAP request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://webservices.formpak.formpak-software.com/">

<soapenv:Header/>

<soapenv:Body>

<web:executeGetFormulation>

</web:executeGetFormulation>

</soapenv:Body>

</soapenv:Envelope>

We only take the <code>PW00073</code> part and create a HEREDOC variable that contains the placeholders that will be filled with system variables:

#define soapbody

<code>@itemcode@</code>

#end

Example 1: Calling the executeGetFormulation remote method on the FormulationWebServices endpoint action using soapbody buffer in order to get PW00073 item data:

#define soapbody

#end

declare=soap=ue_soap_formpak

soap=send=executeGetFormulation=FormulationWebServices=soapbody

// Check request execution results

messagebox=Request status:<ib_successful>

// Check if request returned attachments

messagebox=Has attachments:<ib_hasattach>

messagebox=Sucessfully processed attachment:<ib_attachsuccess>

messagebox=File Name:<is_attachment_name>

// XML response is now saved on the following variable:

<is_soap_string_response>

Example 2: Calling the executePrintDocument remote method on the PrintDocumentWebServices endpoint action using soapbodyprint buffer (this example executes a PDF download to the defined directory)

#define soapbodyprint

<itemCode>@itemcode@</itemCode>

<documentTypeName>@doctype@</documentTypeName>

<language>@language@</language>

</PrintDoucumentParameter>

#end

soap=send=executePrintDocument=PrintDocumentWebServices=soapbodyprint

// Check request execution results

messagebox=Request status:<ib_successful>

// Check if request returned attachments

messagebox=Has attachments:<ib_hasattach>

messagebox=Sucessfully processed attachment:<ib_attachsuccess>

messagebox=File Name:<is_attachment_name>

// XML response is now saved on the following variable:

<is_soap_string_response>

XML parsing functionality has been embedded within this object, there is no need for an external process to be executed in order to obtain the variables values.

Suppose we have received the following XML response buffer:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<ns2:executeGetFormulationResponse xmlns:ns2="http://webservices.formpak.formpak-software.com/">

<identityData>Formulation: PW00073</identityData>

<messages>You have queried successfully!</messages>

<name>lavender & geranium</name>

<active>Active</active>

<state>Liquid</state>

<originalDevJobName>Data Transfer Job</originalDevJobName>

<preventExplosion>false</preventExplosion>

<documentType>Address Label(LH)</documentType>

<version>Document not added</version>

</documentVoList>

<compositionStatus>Normal</compositionStatus>

<simplified>false</simplified>

<lastDevelopmentJobName>Data Transfer Job</lastDevelopmentJobName>

</componentCompositionVo>

<lastModifier>Administrator</lastModifier>

</itemPropertyVersionVo>

<propertyCode>Availability</propertyCode>

<propertyDeterminationMethod>Calculated</propertyDeterminationMethod>

<constraintType>Equality</constraintType>

<ignoreResult>false</ignoreResult>

<estimate>false</estimate>

<withNoValue>false</withNoValue>

<propertyName>Availability</propertyName>

<propertyTypes>CLP Supplemental Information</propertyTypes>

<propertyTypes>Commercial Usability</propertyTypes>

<canBeEstimate>false</canBeEstimate>

</itemPropertyVoList>

<propertyCode>ADDINGDETAILS</propertyCode>

<propertyDeterminationMethod>Calculated</propertyDeterminationMethod>

<ignoreResult>false</ignoreResult>

<estimate>false</estimate>

<withNoValue>false</withNoValue>

<propertyName>Additive Ingredient Details</propertyName>

<propertyTypes>Food Information</propertyTypes>

<canBeEstimate>false</canBeEstimate>

<displayPropertyValue>0 entries</displayPropertyValue>

</itemPropertyVoList>

<hasBeenSold>false</hasBeenSold>

<lastModifier>Administrator</lastModifier>

</formulationVo>

</responsesList>

</return>

</ns2:executeGetFormulationResponse>

</soap:Body>

</soap:Envelope>

Variables can now be obtained in the following way:

if <ib_successful> = 'true' then

messagebox=unitOfMeasures: <xml.unitOfMeasures> // returns kg

messagebox=itemPropertyVoList: <xml.itemPropertyVoList:node:[2]> // returns true, used to verify if a node exists

messagebox=propertyName: <xml.propertyName:[2]> // Returns Additive Ingredient Details - value for propertyName tag in second itemPropertyVoList node

messagebox=propertyTypes: <xml.propertyTypes:[1]> // Returns CLP Supplemental Information - value for propertyTypes tag in first itemPropertyVoList node

messagebox=propertyName: <xml.propertyName:[1]> // Returns Availability - value for propertyName tag in first itemPropertyVoList node

else

messagebox=No succesful XML response was received: <xml.messages>

end if