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:
|
1 |
%SOAP_UDDI |
Use the UDDI schema. Specifying this value adds the following attribute to the SOAP envelope:
|
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. |
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 encryption, 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:
|
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;