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.

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>

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

Field or Control	Definition
`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 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.

Numeric Value

Constant Value

Description

%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/"

%SOAP_UDDI

Use the UDDI schema. Specifying this value adds the following attribute to the SOAP envelope:

xmlns:SOAP-ENV= "urn:uddi-org:api"

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

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

Field or Control	Definition
`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>

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 SOAPDoc &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");

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

Field or Control	Definition
`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

Field or Control

Definition

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>

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

Field or Control	Definition
`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>

Syntax

GetParmName(Index)

Description

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

Parameters

Field or Control	Definition
`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;

Syntax

GetParmValue(Index)

Description

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

Parameters

Field or Control	Definition
`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;

Syntax

ValidateSOAPDoc()

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.

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;