SOAPDoc Class

This chapter provides an overview of SOAPDoc class and discusses the following topics:

SOAP message exchange model.
SOAP message document.
The SOAPDoc class.
SOAPDoc object creation.
The ValidateSOAPDoc method.
SOAPDoc objects and methods.
Data type of a SOAPDoc object.
Scope of a SOAPDoc object.
SOAPDoc built-in functions.
SOAPDoc class methods.
SOAPDoc class properties.

Understanding SOAPDoc Class

The Simple Object Access Protocol (SOAP) is a lightweight protocol for defining synchronous messages in a distributed Web environment. It's an XML based protocol that can be used in combination with other protocols such as HTTP using URLs as endpoints for a message. SOAP is an application of XML and XML namespaces and optionally uses XML Schemas.

SOAP is an industry standard, defined by the World Wide Web Consortium (W3C), that defines an XML grammar for identifying a method name and the method parameters and for returning the results.

More specific information about SOAP can be found in the W3C specification on SOAP. The SOAP serialization rules can also be found in the complete specifications and aren't outlined in this chapter. Also included in the W3C specification are sections on using SOAP with HTTP, which is also outside the domain of this chapter. You can also send and receive HTTP messages through the Integration Gateway.

SOAP is an application built with XML and HTTP technologies

See Also

http://www.w3.org

Sending and Receiving Messages

SOAP Message Exchange Model

SOAP messages are always synchronous. They can implement Request/Response synchronous messages with the response having the output parameters returned in another SOAP document to the sender.

SOAP supports HTTP-POST and HTTP-GET formats. PeopleSoft supports only HTTP, using the Integration Gateway.

Processing the message requires validation of the mandatory sections of the SOAP XML document and understanding SOAP namespaces.

SOAP Message Document

A SOAP Message is an ordinary XML document that consists of the following parts:

A mandatory SOAP envelope.
An optional SOAP header.
A mandatory SOAP body.

SOAP Message Part	Description
SOAP Envelope	Is the top element of the XML document representing the message. It defines the content of the message, as well as the framework of what is in a message, how to process it, who should deal with it and whether it is optional or mandatory.
SOAP Header	Contains header information, and attributes that can be set to encode and further identify the type of processing as well as additional features of the message. This portion is optional.
SOAP Body	Contains the call and response information intended for the recipient of the message. A SOAP Fault element can appear in the body of the SOAP message to carry error or status information.

SOAP parts in an XML document

The following are required for a SOAP message:

Encoded using XML.
Have a SOAP envelope.
Have a SOAP body.
Use the SOAP encoding and envelope namespaces.

The following are optional for a SOAP message:

SOAP Header.
XML Schema use.

The following are invalid for a SOAP message:

DTD references.
XML Processing Instructions.
XML CData Sections.

The SOAPDoc Class

The SOAPDoc class is a separate class in PeopleCode that works similarly to the XmlDoc and XmlNode classes. Many of the same methods and properties that work with an XmlDoc or XmlNode work with a SOAPDoc. However, there are also methods and properties that don't apply to a SOAPDoc.

The following XmlDoc and XmlNode methods do not apply to a SOAPDoc:

AddCDataSection
AddProcessInstruction
CopyToPSFTMessage
CreateDocumentType
InsertCDataSection
InsertProcessInstruction
LoadIBContent

If a Merchant Profile has been created it can be used with the SOAPDoc class and the Message class. You can use the XmlDoc property to convert the message object to an SOAPDoc object, then use the SOAPDoc methods and properties, as well as the XmlDoc methods and properties that are applicable.

You can only use the message object when the XmlDoc object is structured.

It should be noted that a SOAPDoc object is really an extension of the XmlDoc class. You have the option of getting portions of the SOAPDoc–like the body node–and accessing it or manipulating it as if it were a standard element in an XML document, because in actuality it is.

SOAPDoc Object Creation

There are a few steps to creating a SOAPDoc. The following is an overview of these steps. More detail about the methods and properties mentioned in this section can be found in the reference section of this chapter.

SOAP Header Section

Because the SOAP header is optional, the header is not validated when you use the ValidateSOAPDoc method.

A SOAP header must be added before any other parts of the SOAPdoc.

Use the AddHeader method to add a header to a SOAPDoc.

Use the HeaderNode property to access an existing SOAPDoc header.

After you have a reference to the header, you can use XmlDoc methods to read the contents of the header (like any node.)

See Also

AddHeader

HeaderNode

SOAP Envelope Section

A SOAP envelope is a required portion of the XML Message and is generated automatically using the SOAP schema as specified by SOAP W3C.

A SOAP envelope must be added before you add a SOAP body or a SOAP method. This is an optional method. You need to use this method only if you need to set any additional attributes for the Envelope section. The default SOAP schemas are added automatically.

To set additional custom attributes or schemas on the Envelope element, use the AddEnvelope method. This method adds the envelope element tags and the default schemas for either SOAP or UDDI depending on the value of the parameter passed in. The default encoding styles are also set here. Only one envelope section can be set within one PeopleSoft SOAP XmlDoc.

The SOAPDoc adds only a default URL to the envelope. For some UDDI sites, you may need to add a specific schema yourself. To do this, generate the envelope with no schema, then access the envelope section and add the specific schema URL using the AddAttribute method.

See Also

AddEnvelope

SOAP Body Section

The body is the XmlDoc where the method is defined. The method AddBody starts the body section of the XML SOAPDoc and must be in the XmlDoc before adding in method sections of the message. Only one body section can be set within one SOAPDoc. This is an optional method and must called only if you need to set any additional attributes for the body section. Otherwise the body section is automatically generated in the XmlDoc.

The SOAP body must be added after you add the SOAP envelope, and before you add any methods.

See Also

AddBody

SOAP Method Section

The AddMethod method adds the name of the method element being processed. Additional attributes for this method can be set using the AddAttribute and InsertAttribute XmlNode methods.

You don't have to specifically add a SOAP body section. The body is automatically added when you call the AddMethod method.

The AddParm method sets the parameters for the parameter element of the method as a name, value pair. Multiple parameters can be set and are used in the order that this method is called. If an XML Schema is defined, types can be used using the AddAttribute XmlNode method. Any number of parameter name-value pairs can be added for a method and are added to the XmlDoc in the order that the AddParm methods are called.

You can add parameters to a method only after you add the method. The parameters are added in the order you add them in the PeopleCode program.

See Also

AddMethod

AddParm

AddAttribute

SOAPDoc Section Access

Use the following properties to access the different parts of a SOAPDoc object. All of these properties return an XmlNode object.

BodyNode
EnvelopeNode
MethodNode

After you have access to the portion of the SOAPDoc that you want, use the XmlNode properties and methods to manipulate the SOAPDoc.

Use the XmlDoc property to convert a SOAPDoc object to an XmlDoc object, and vice-versa.

The MethodName property returns the name of the method in the SOAPDoc object.

Note. If you use the MethodName property, you receive only the method name, as a string, not a reference to an XmlNode object that represents the method.

Use the GetParmName and GetParmValue methods to get the name and the values in a SOAPDoc object for each output parameter. You must use the index number of the parameter you want with these methods. You can determine the total number of parameters with the ParmCount property.

See Also

PeopleCode to Create a SOAPDoc

The following is the order in which the Soap methods must be called in order to create a valid SOAPDoc.

&SOAPDoc = CreateSOAPDoc(); /* required */
&SOAPDoc.AddEnvelope(0); /* optional */
&SOAPDoc.AddBody(); /* optional */
&SOAPDoc.AddMethod("GetQuote", 1); /* required */
&SOAPDoc.AddParm("symbols", "PSFT");
&SOAPDoc.AddParm("format", "l1c1d1t1");
&OK = &SOAPDoc.ValidateSOAPDoc(); /* optional */

SOAPDoc Fault Section

In the body of a SOAP XML response document, you can define a fault section. Generally this is used if in an inbound message has been processed and some sort of error occurred. The text of the message gives further information about the error.

Use the AddFault method to add a fault code and a fault string to the body of a SOAPDoc. Only one fault section can be set within one SOAP XML document.

If you receive a response message that contains a fault, use the FaultCode and FaultString methods to return these values.

See Also

AddFault

FaultCode

FaultString

The ValidateSOAPDoc Method

Use the ValidateSOAPDoc method to validate the SOAP document for correctness as follows:

Encoded using XML.
Has SOAP envelope.
Has SOAP Body.
Has a SOAP Method.
Used SOAP encoding and envelope namespaces.

See Also

ValidateSOAPDoc

SOAPDoc Objects and Messages

To publish the data of a SOAPDoc, you must first transform the SOAPDoc into an XmlDoc object by using the XmlDoc property. After you do this, you can use the XmlDoc object with the SyncRequestXmlDoc, PublishXmlDoc, or GetXmlDoc functions, to publish the data either synchronously or asynchronously.

All XmlDoc messages must be associated with a message definition. An XmlDoc message must be associated with an unstructured message, that is, a message definition that's created without any record definitions.

Use the SOAPDoc class if all of the following are true:

Your third-party source or target node requires SOAP-compliant messages.
Your third-party source or target node requires synchronous transactions.
Your message conforms to the SOAP specification.

See Also

XmlDoc Class

Sending and Receiving Messages

Data Type of a SOAPDoc Object

SOAPDoc objects are declared as type SOAPDoc. For example,

Local SOAPDoc &MyDoc;

Global SOAPDoc &SOAPDoc;

Scope of a SOAPDoc Object

A SOAPDoc object can only be instantiated from PeopleCode.

This object can be used anywhere you have PeopleCode, that is, in message subscription PeopleCode, Application Engine PeopleCode, record field PeopleCode, and so on.

Note. Do not extend a SOAPDoc with an application class. This is currently not supported.

SOAPDoc Built-In Functions

CreateSOAPDoc

SOAPDoc Class Methods

In addition to the methods listed here, most of the XmlDoc and XmlNode class methods can be used with a SOAPDoc object. The methods are discussed in alphabetical order.

See Also

XmlDoc Class.

AddBody

Syntax

AddBody()

Description

Use the AddBody method to add the body section of the SOAP XML document.

This method is optional when you're creating a SOAP document. Use it only if you must set any additional attributes for the body. Otherwise, the body section is automatically generated in the XML document.

If you're going to add a body section, you must do it after you've added the envelope section. If you are going to modify the body section, you must do this before you add the method sections of the SOAP XML document by calling the BodyNode property and using XmlNode methods and properties.

Note. Only one body section can be set within one Peoplesoft SOAP XML document.

Parameters

None.

Returns

None.

Example

From the following code:

&MyDoc.AddBody();

the following XML is created:

<SOAP-ENV:Body >

</SOAP-ENV:Body>

See Also

SOAPDoc class: AddMethod method, AddEnvelope method.

AddAttribute

AddEnvelope

Syntax

AddEnvelope(SOAP_Schema)

Description

Use the AddEnvelope method to add the envelope element tags and the default schema. The default encoding styles are also set with this method.

Note. Only one envelope section can be set within one Peoplesoft SOAP XML document.

If you're going to be adding an envelope section, you must do this before you add the body section or any methods by calling the EnvelopeNode property and using XmlNode methods and properties.

Parameters

SOAP_Schema

Specify whether to use the default SOAP schema or the UDDI schema. You can specify either a numeric value or a constant for this property. The values are:

Numeric Value	Constant Value	Description
0	%SOAP_Schema	Use the SOAP schema. Specifying this value adds the following attributes to the SOAP envelope: xmlns:SOAP-ENV= "http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENV= "http://schemas.xmlsoap.org/soap/encoding/"
1	%SOAP_UDDI	Use the UDDI schema. Specifying this value adds the following attribute to the SOAP envelope: xmlns:SOAP-ENV= "urn:uddi-org:api"
2	%SOAP_Custom	Specify this value to add custom Namespace schemas to the SOAP envelope instead of the default SOAP schemas. Note. You must create the custom schema before you use it. See http://www.w3.org/XML/Schema You must add the SOAP_ENV URI (as an attribute, using AddAttribute) before adding any other SOAP attributes. Note. For highly customized SOAP documents, PeopleSoft recommends using the XmlDoc class and creating the tags yourself.

Returns

None.

Example

The following example uses the default SOAP schema. The following PeopleCode program:

&MyDoc.AddEnvelope(%SOAP_Schema);

Creates the following XML:

<?xml version="1.0"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV= "http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV= "http://schemas.xmlsoap.org/soap/encoding/">

</SOAP-ENV:Envelope>

The following example creates an envelope and validates it.

The following PeopleCode program:

&soapReq = CreateSOAPDoc(); /* required */
/* manually add SOAP XML envelope, header, body, method and parameters */
/* &soapReq.AddHeader(); MUST come before any other section, but is optional */
&soapReq.AddEnvelope(%SOAP_Custom);
&EnvNode = &soapReq.EnvelopeNode;
&AddEnvelopeAttribute = &EnvNode.AddAttribute("xmlns:SOAP-ENV", "urn:MyCustomSchema.org");
&AddEnvelopeAttribute = &EnvNode.AddAttribute("xmlns:xsi", http://www.w3.org/2001/XMLSchema-instance);
&AddEnvelopeAttribute = &EnvNode.AddAttribute("xmlns:xsd", http://www.w3.org/2001/XMLSchema);
&AddEnvelopeAttribute = &EnvNode.AddAttribute("xmlns:soap", http://schemas.xmlsoap.org/soap/envelope/);
&soapReq.AddMethod("requestAccessCode", 1);

/* Validate the message */
MessageBox(%MsgStyle_OK, "", 0, 0, "Validate the message");
&OK = &soapReq.ValidateSOAPDoc();
MessageBox(%MsgStyle_OK, "", 0, 0, "Message Validated and &OK = " | &OK);

/* Convert SOAP XML to XML */
MessageBox(%MsgStyle_OK, "", 0, 0, "Sending the message next");

&string = &soapReq.GenXmlString();
MessageBox(%MsgStyle_OK, "", 0, 0, "SOAP XML = " | &string);

Creates the following XML:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:xsd= "http://www.w3.org/2001/XMLSchema"
xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance"
xmlns:soap= "http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENV= "urn:MyCustomSchema.org">
<SOAP-ENV:Body>
   <requestAccessCode/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

See Also

SOAPDoc class: AddBody method.

AddFault

Syntax

AddFault(Fault_Code, Fault_String)

Description

Use the AddFault method to add a fault code, with its corresponding fault string, to a SOAPDoc. Use this method only in a Response SOAP XML Document. The Envelope and Body sections of the XML Document are automatically added if they don't exist.

Parameters

Fault_Code	Specify the fault code to add, as a string.
Fault_String	Specify the fault string to add, as a sting.

The following fault codes are supported:

Fault Code	Fault String	Description
100	Version Mismatch	The XML version or SOAP version is not supported by the current implementation.
300	Client error	An error occurred on the client while processing the SOAP document.
400	Server error	An error occurred on the server while processing the SOAP document.

Returns

None.

Example

The following example program:

&SOAPDoc = CreateSOAPDoc(); 
SOAPDoc.AddFault("400", "Server Error");


/* ===> The following statement executes this instance: */
&FaultCode = &SOAPDoc.FaultCode;
&FaultString = &SOAPDoc.FaultString;
&OK = &SOAPDoc.ValidateSOAPDoc();

Creates the following XML:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
- <SOAP-ENV:Body>
- <SOAP-ENV:Fault>
  <faultcode>400</faultcode> 
  <faultstring>SOAP Server Error</faultstring> 
  </SOAP-ENV:Fault> 
  </SOAP-ENV:Body> 
  </SOAP-ENV:Envelope>

See Also

SOAPDoc class: FaultCode property, FaultString property, FaultCodeS property.

AddHeader

Syntax

AddHeader()

Description

Use the AddHeader method to add the header section of the SOAP XML document.

This method is optional when you're creating a SOAP document. Use it only if you want to include a header in your SOAP XML document.

If you're going to add a header, you must do it before you've added any other sections, such as the envelope or the body.

After you've created the header, you can access it using the HeaderNode property. Once you have a reference to the node, you must use the XmlDoc methods to add specifics to the header section such as encription, as well as any required child nodes.

Note. Only one header section can be set within one Peoplesoft SOAP XML document.

Parameters

None.

Returns

None.

Example

The following test adds a header section into a SOAP XML document where all sections are created explicitly:

Local SOAPDocs &Sdoc;
Local XMLNode &Node;

/* ===> Add inputs: */
&Sdoc = CreateSOAPDoc(); /* required */
&Sdoc.AddEnvelope(0); /* optional */
&Sdoc.AddHeader(); /* optional */
&Sdoc.AddBody(); /* optional */
&Sdoc.AddMethod("SOAPXml", 1); /* required */
&Sdoc.AddParm("symbols", "PSFT");

&OK = &Sdoc.ValidateSOAPDoc();

/*Append to TEMP file*/
&Xstring = &Sdoc.GenXmlString();
&myfile = GetFile("cmsDoc.xml", "A");
&myfile.WriteLine(&Xstring);
&myfile.Close();

&METHOD = &Sdoc.MethodName;
&ParmCnt = &Sdoc.ParmCount;
&HdrNode= &Sdoc.HeaderNode;

&HdrName = &HdrNode.NodeName; //returns SOAP-ENV:Header

/* Echo out the Returned Outputs */
out_BI_results("SOAP Header test 1");
out_BI_results(" ");
out_BI_results("Validated: " | &OK);
out_BI_results("Method: " | &METHOD);
out_BI_results("Parm Count: " | &ParmCount);
out_BI_results("Header : " | &HdrName);

out_BI_results("End-of-Test");

See Also

HeaderNode

AddMethod

Syntax

AddMethod(MethodName, IsRequest)

Description

Use the AddMethod method to set the name of the method element being processed. Additional attributes for the added method can be set using the AddAttribute and InsertAttribute method. Executing AddMethod automatically adds any missing Envelope and Body sections.

Note. Only one method can be set within one Peoplesoft SOAP XML document.

The SOAPDoc method can be used only after the envelope and body sections have been added.

Set the parameters for the method using the AddParm method.

Parameters

MethodName

Specify the name of the method element being added.

IsRequest

Specify if the message is a request message. This parameter takes a numeric value:

1 if the message is a request message
0 if the message is a response message

Returns

None.

Example

The following sample program:

&MyDoc.AddMethod("GetPrice", 0);

Creates the following XML:

<GetPrice>

</GetPriceResponse>

The following sample program:

&MyDoc.AddMethod("GetPrice", 1);

Creates the following XML:

<GetPrice>

</GetPrice>

See Also

SOAPDoc class: AddParm method, MethodName property, MethodNode property.

AddAttribute

AddParm

Syntax

AddParm(ParmName, ParmValue)

Description

Use the AddParm method to set the parameters for the parameter element of the current method. To set more than one parameter, use the method more than once. The parameters are set and used in the order that this method is called. Any number of parameter name-value pairs can be set for a method and are added to the XML document in the order that this method is called from the PeopleCode program.

Parameters

ParmName	Specify the name of the parameter as a string.
ParmValue	Specify the value of the parameter as a string.

Returns

None.

Example

The following PeopleCode:

&MyDoc.AddParm("Item", "Apples");

Creates the following XML:

<Item >Apples</Item>

See Also

SOAPDoc class: AddMethod method.

GetParmName

Syntax

GetParmName(Index)

Description

Use the GetParmName method access the parameter names for a method.

Parameters

Index

Specify the number of the parameter that you want to access. Values start at 1.

Returns

A string.

Example

For &I = 1 to &SOAPDoc.ParmCount

&ParmName = &SOAPDoc.GetParmName(&I);
&ParmValue = &SOAPDoc.GetParmValue(&I);

	   /* Do processing */

End-For;

See Also

SOAPDoc class: GetParmValue method, ParmCount property.

GetParmValue

Syntax

GetParmValue(Index)

Description

Use the GetParmValue method to access the parameter values for a method.

Parameters

Index

Specify the number of the parameter you want to access. Values start at 1.

Returns

A string.

Example

For &I = 1 to &SOAPDoc.ParmCount

&ParmName = &SOAPDoc.GetParmName(&I);
&ParmValue = &SOAPDoc.GetParmValue(&I);

   /* Do processing */

End-For;

See Also

SOAPDoc class: GetParmName method, ParmCount property.

ValidateSOAPDoc

Syntax

ValidateSOAPDoc([1])

Description

Use the ValidateSOAPDoc method to validate the SOAP document for correctness as follows:

SOAP message is:

Encoded using XML.
Has SOAP envelope.
Has SOAP body.
Used SOAP encoding and envelope namespaces.

If you want to validate whether your SOAP document uses the SOAP-ENV namespace prefix, use ValidateSOAPDoc without any parameters. If you want to ignore namespace prefixes during SOAP validation, specify 1.

Parameters

1	Specify whether to check for namespace prefixes. This parameter is optional.

Returns

This method returns either a number or a constant. The values are:

Numeric Value	Constant Value	Description
0	%SOAP_Valid	The SOAPDoc is valid.
1	%SOAP_NoEnvelope	Missing or invalid envelope section in XML document.
2	%SOAP_InvalidEnvelope	Envelope has improper Namespace used. Should be: SOAP-ENV or SOAP-ENC
3	%SOAP_NoBody	Missing body section in XML document.
4	%SOAP_NoMethod	Missing or invalid method section in XML document.
6	%SOAP_InvalidXml	Invalid XML syntax in SOAPDoc.

Example

&Return = &MyDoc.ValidateSOAPDoc();
If &Return <> 0 Then
   /* do error processing */
End-if;

See Also

SOAPDoc class: FaultCode property, FaultString property.

SOAPDoc Class Properties

In addition to the properties listed here, most of the XmlDoc and XmlNode class properties can be used with a SOAPDoc object. The properties are discussed in alphabetical order.

See Also

XmlDoc Class.

BodyNode

Description

This property returns a reference to the body section of a SOAPDoc, as an XmlNode.

This property is read-only.

See Also

XmlDoc Class.

EnvelopeNode

Description

This property returns a reference to the envelope section of a SOAPDoc, as an XmlNode.

This property is read-only.

See Also

XmlDoc Class.

FaultCode

Description

Use the FaultCode property to return the fault code if the SOAP message has one. Not every message has a fault code. It is returned only when the SOAP method has had an error in processing and the SOAP method supports fault codes.

This property is read-only.

Example

&Fault = &MyDoc.FaultCode;

See Also

SOAPDoc class: FaultString property, FaultCodeS property, AddFault method.

FaultCodeS

Description

Use the FaultCodeS property to return the fault code string that was added using the AddFault method.

This property is read-write.

See Also

AddFault, FaultCode, FaultString.

FaultString

Description

Use the FaultString property to return the fault string if the reply has one. Not every SOAP message has a fault string. It is only returned when the SOAP method has had an error in processing and the SOAP method supports fault strings.

Example

&Fault = &MyDoc.FaultString;

See Also

SOAPDoc class: FaultCode property, FaultCodeS property, AddFault method.

HeaderNode

Description

Use the HeaderNode property to return a reference to the header node. After you have a reference, you can use the XmlDoc methods to read and make changes to the node.

This property is read-write.

Example

The following test adds a header section, validates the SOAPDoc, then access the header.

Local SOAPDocs &Sdoc;
Local XMLNode &Node;

/* ===> Add inputs: */
&Sdoc = CreateSOAPDoc(); /* required */

&Sdoc.AddHeader(); /* optional */
&Sdoc.AddMethod("SOAPXml", 1); /* required */

&OK = &Sdoc.ValidateSOAPDoc();

/*Append to TEMP file*/
&Xstring = &Sdoc.GenXmlString();
&myfile = GetFile("cmsDoc.xml", "A");
&myfile.WriteLine(&Xstring);
&myfile.Close();

&METHOD = &Sdoc.MethodName;
&ParmCnt = &Sdoc.ParmCount;
&HdrNode= &Sdoc.HeaderNode; //returns SOAP-ENV:Header

&HdrName = &HdrNode.NodeName;

/* Echo out the Returned Outputs */
out_BI_results("SOAP Header test 1");
out_BI_results(" ");
out_BI_results("Validated: " | &OK);
out_BI_results("Method: " | &METHOD);
out_BI_results("Parm Count: " | &ParmCount);
out_BI_results("Header : " | &HdrName);

out_BI_results("End-of-Test");

See Also

AddHeader

MethodName

Description

This property returns the name of the method of the SOAPDoc, as a string.

If you want a reference to the method that you can work with, as an XmlNode, use the MethodNode property.

This property is read-only.

MethodNode

Description

This property returns a reference to the method section of a SOAPDoc, as an XmlNode.

If you want only the name of the method returned, use the MethodName property.

This property is read-only.

See Also

XmlDoc Class.

ParmCount

Description

This property returns the total number of parameters for the method section in a SOAP XML document as a number.

This property is read-only.

Example

For &I = 1 to &SOAPDoc.ParmCount
   &ParmName = &SOAPDoc.GetParmName(&I);
   &ParmValue = &SOAPDoc.GetParmValue(&I);
   /* do processing */
End-For;

XmlDoc

Description

This property transforms a SOAPDoc object to an XmlDoc object. This is necessary only when sending or receiving a response message. You do not need to do this conversion to use the XmlDoc or XmlNode methods and properties.

This property is read-write.

Example

The following is an example of sending a SOAP message and receiving the response:

Local XmlDoc &request, &response;
Local string &strXml;
Local SOAPDoc &soapReq, &soapRes;

/* create the SOAP XML Document */
&soapReq = CreateSOAPDoc();
&soapReq.AddMethod("GetPrice");
&soapReq.AddParm("Item", "Apples");

/* convert SOAP to XmlDoc */
&request = &soapReq.XmlDoc;

/* Send the Request */
&response = SyncRequestXmlDoc(&request, Message.QE_SOAP_REQ, Node.UNDERDOG);

/* Get the SOAP response from the XmlDoc response */
&soapRes = CreateSOAPDoc();
&soapRes.XmlDoc = &response;
&OK = &soapRes.ValidateSOAPDoc();
&strXml = &soapRes.GenXmlString();

SOAPDoc Class Examples

The following are typical example of how you would use a SOAPDoc object.

Creating a SOAP Document

The following is the minimal PeopleCode you need to create a SOAP XML document:

Local SOAPDoc &SOAPDoc;

&SOAPDoc = CreateSOAPDoc();
&SOAPDoc.AddMethod("GetPrice");
&SOAPDoc.AddParm("Item", "Apples");

The following is an example of creating a SOAP XML document with a simple method.

Local SOAPDoc &SOAPDoc;

&SOAPDoc = CreateSOAPDoc();

&SOAPDoc.AddEnvelope(0);
&SOAPDoc.AddBody();
&SOAPDoc.AddParm("symbols", "PSFT");
&SOAPDoc.AddParm("format", "l1c1d1t1");

&OK = &SOAPDoc.ValidateSOAPDoc();

Reading an Existing SOAP Document

The following code loads an SOAP XML document from a URL, then finds the method name and parameters to call that method.

Local SOAPDoc &SOAPDoc;
Local Number &ParmCount;
Local Boolean &Result;

&SOAPDoc = CreateSOAPDoc();
&SOAPDoc.ParseXmlFromURL("C:\ptdvl\840S2\files\inputSOAP.xml");

&ParmCount = &SOAPDoc.ParmCount;
For &I = 1 to &ParmCount

	   &ParmName = &SOAPDoc.GetParmName(&I);
   &ParmValue = &SOAPDoc.GetParmValue(&I);

/* Do processing */
End-for;

Using SOAP XML Text

The following shows a SOAP XML Document text for the following pseudo-code:

Item = "Apples"
Price = GetPrice(Item);

Example of SOAP Request Header

Here’s the HTTP Header for a SOAP message. This Host URL is the server where the method defined in the SOAP envelope is processed:

POST /GetPrice HTTP/1.1 Host: www.farmersmarket.com Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction:"GetPrice"

This is a simple example of a SOAP XML Document, requesting the price of Apples. It uses the default SOAP schemas. The name of the method is GetPrice with the parameter Item which has a value of "Apples".

<SOAP-ENV:Envelope 
  xmlns:SOAP-ENV="http://schemas.SOAP.org/soap/envelope/"
  xmlns:SOAP-ENC="http://schemas.SOAP.org/soap/encoding/"
>
    <SOAP-ENV:Body>
        <m:GetPrice xmnls:m="SomeURI">
        <Item>Apples</Item>
        </m:GetPrice>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example of SOAP HTML Reply Header

Here’s the HTTP Header for a SOAP message Reply with a 200 return code that the message was processed OK.

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

This simple example of a SOAP XML Document reply returns the price of Apples as 34. The SOAP reply always codes the name of the requested method with the Response tag attached to it, GetPriceResponse in this case.

<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.SOAP.org/soap/envelope/"
  xmlns:SOAP-ENC="http://schemas.SOAP.org/soap/encoding/"
>
   <SOAP-ENV:Body>
       <m:GetPriceResponse xmlns:m="Some-URI">
          <Price>34</Price>
       </m:GetPriceResponse>
     </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Using SyncRequestXmlDoc Example

The following converts the SOAPDoc object into an XmlDoc object, then uses the XmlDoc object to send the data. The response comes back as an XmlDoc object, which is then converted back into a SOAPDoc object.

Local XmlDoc &request, &response;
Local string &strXml;
Local SOAPDoc &soapReq, &soapRes;

&soapReq = CreateSOAPDoc();
&bool = &soapReq.ParseXmlFromURL("C:\\ptdvl\\appserv\\QE840U2\\files\\inputSOAP.xml");

&strXml = &soapReq.GenXmlString();
&MY_FILE = GetFile("c:\temp\syncInput.txt", "w", "a", %FilePath_Absolute);
&MY_FILE.WriteLine("YEAH!");
&MY_FILE.WriteLine(&strXml);
&MY_FILE.Close();

&request = &soapReq.XmlDoc;
&response = SyncRequestXmlDoc(&request, Message.QE_SOAP_REQ, Node.UNDERDOG);

&soapRes = CreateSOAPDoc();
&soapRes.XmlDoc = &response;
&OK = &soapRes.ValidateSOAPDoc();
&strXml = &soapRes.GenXmlString();

&MY_FILE = GetFile("c:\temp\sync.txt", "w", "a", %FilePath_Absolute);
&MY_FILE.WriteLine(&strXml);
&MY_FILE.Close();

SoapDoc Class Outbound Synchronous Example

The following example uses the SyncRequestXmlDoc built-in Function.

Note. Because SyncRequestXmlDoc is an XmlDoc function, you must convert your SoapDoc request message to an XmlDoc object before sending it. Likewise, the response message will be an XmlDoc object, so you must convert it to a SoapDoc object to process it using SOAP methods.

Local File &MY_FILE;

Local XmlDoc &request, &response;
Local string &strXml;
Local SoapDocs &soapReq, &soapRes;

&soapReq = CreateSoapDoc();
&bool = &soapReq.ParseXmlFromURL("C:\\ptdvl\\appserv\\QE840U2\\files\\inputSoap.xml");
&strXml = &soapReq.GenXmlString();
&MY_FILE = GetFile("c:\temp\syncInput.txt", "w", "a", %FilePath_Absolute);
&MY_FILE.WriteLine("YEAH!");
&MY_FILE.WriteLine(&strXml);
&MY_FILE.Close();

&request = &soapReq.XmlDoc;
&response = SyncRequestXmlDoc(&request, Message.QE_SOAP_REQ, Node.UNDERDOG);

&soapRes = CreateSoapDoc();
&soapRes.XmlDoc = &response;
&OK = &soapRes.ValidateSoapDoc();
&strXml = &soapRes.GenXmlString();

&MY_FILE = GetFile("c:\temp\sync.txt", "w", "a", %FilePath_Absolute);
&MY_FILE.WriteLine(&strXml);
&MY_FILE.Close();

SoapDoc Class Inbound Synchronous Example

The following example uses the GetMessageXmlDoc built-in function.

Note. Because GetMessageXmlDoc is an XmlDoc function, you must receive the inbound request message as an XmlDoc object, then convert it to a SoapDoc object to process it using SOAP methods. Likewise, because the request was sent using SyncRequestXmlDoc, you must convert your SoapDoc response message to an XmlDoc object before returning it.

Local XmlDoc &request, &response;
Local string &strXml;
Local SoapDocs &soapReq, &soapRes;

&soapReq = CreateSoapDoc();

&request = GetMessageXmlDoc();
&soapReq.XmlDoc = &request;
&OK = &soapReq.ValidateSoapDoc();
&parmN = &soapReq.GetParmName(1);
&parmV = &soapReq.GetParmValue(1);

&soapRes = CreateSoapDoc();
&soapRes.AddEnvelope(0);
&soapRes.AddBody();
&soapRes.AddMethod("StockPrice", 1);
&soapRes.AddParm(&parmN, &parmV);
&soapRes.AddParm("Price", "29");
&OK = &soapRes.ValidateSoapDoc();

&response = &soapRes.XmlDoc;
ReturnToServer(&response);