Soap Api

What is SOAP API ??

1.      SOAP Stands for  Simple Object Access Protocol

2.      SOAP is a W3C recommendation for communication between two applications

3.      SOAP is an open-standard,

4.      SOAP  is a XML-based protocol for accessing web services..

5.      SOAP is platform independent.

6.      SOAP is language independent.

7.      SOAP is simple and extensible.

8.      SOAP is a stateless protocol

9.      Salesforce provides programmatic access to your organization’s information using simple, powerful, and secure application programming interfaces. 

10.  SOAP API to create, retrieve, update, or delete records.

SOAP Elements

A SOAP message is an ordinary XML Document

1.       Envelope − Defines the start and the end of the message. It is a mandatory element.

2.       Header − Contains any optional attributes of the message used in processing the message, either at an intermediary point or at the ultimate end-point. It is an optional element.

3.       Body − Contains the XML data comprising the message being sent. It is a mandatory element.

4.       Fault − An optional Fault element that provides information about errors that occur while processing the message.

All these elements are declared in the default namespace for the SOAP envelope −

SOAP Syntax

SOAP Message Structure

<?xml version="1.0"?>

<soap:Envelope  >

<xmlns:soap=http://www.w3.org/2001/12/soap-envelope soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Header> …..   </soap:Header>           

<soap:Body>

            <soap:Fault> ... ... </soap:Fault>

</soap:Body>

</soap:Envelope>

Note : A SOAP message MUST

Be encoded using XML

Use the SOAP Envelope namespace

Use the SOAP Encoding namespace

Not contain a DTD( Document type definition) reference

NOT contain XML Processing Instructions

SOAP Envelope

The SOAP envelope indicates the start and the end of the message so that the receiver knows when an entire message has been received. The SOAP envelope solves the problem of knowing when you're done receiving a message and are ready to process it. The SOAP envelope is therefore basically a packaging mechanism.

SOAP Envelope element can be explained as:

1.The root element of a SOAP message.

2.Defines the XML document as a SOAP message.

3.Envelope element is mandatory part of SOAP Message.

4.Every Envelope element must contain exactly one Body element.

5.If an Envelope contains a Header element, it must contain no more than one, and it                

    must  appear as the first child of the Envelope, before the Body.

6.The envelope changes when SOAP versions change.

7.The SOAP envelope is specified using the ENV namespace prefix and  

   the Envelope element.

8. The optional SOAP encoding is also specified using a namespace name and the       

9.optionalencodingStyle element, which could also point to an encoding style other than

   the SOAP one.

SOAP Header

The optional Header element offers a flexible framework for specifying additional application-level requirements.

 For example, the Header element can be used to specify a digital signature for password-protected services; likewise, it can be used to specify an account number for pay-per-use SOAP services.

SOAP Header element can be explained as:

1.      Header elements are optional part of SOAP messages.

2.      Header elements can occur multiple times.

3.      Headers are intended to add new features and functionality.

4.      The SOAP header contains header entries defined in a namespace.

5.      The header is encoded as the first immediate child element of the SOAP envelope.

6.      When more than one header is defined, all immediate child elements of the SOAP header are interpreted as SOAP header blocks.

SOAP Header element can have following two attributes

1.      Actor attribute:
The SOAP protocol defines a message path as a list of SOAP service nodes. Each of these intermediate nodes can perform some processing and then forward the message to the next node in the chain. By setting the Actor attribute, the client can specify the recipient of the SOAP header.

2.      MustUnderstand attribute:
Indicates whether a Header element is optional or mandatory. If set to true ie. 1 the recipient must understand and process the Header attribute according to its defined semantics, or return a fault.

The SOAP actor attribute is used to address the Header element to a specific endpoint.

EXAMPLE:

   <?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Header>
  <m:Trans xmlns:m="http://www.w3schools.com/transaction/"
  soap:actor="http://www.w3schools.com/appml/">234
  </m:Trans>
</soap:Header>
...
...
</soap:Envelope>

SOAP Body

The SOAP body is a mandatory element which contains the application-defined XML data being exchanged in the SOAP message. The body must be contained within the envelope and must follow any headers that might be defined for the message. The body is defined as a child element of the envelope, and the semantics for the body are defined in the associated SOAP schema.

 The body contains mandatory information intended for the ultimate receiver of the message.

Immediate child elements of the SOAP Body element may be namespace-qualified.

EXAMPLE:

  Request

<?xml version="1.0"?>

<soap:Envelope

            xmlns:soap="http://www.w3.org/2001/12/soap-envelope"             soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

            <soap:Body>

                        <m:GetPrice xmlns:m="http://www.w3schools.com/prices">                                                <m:Item>Apples</m:Item>

                        </m:GetPrice>

            </soap:Body>

</soap:Envelope>

Response

<?xml version="1.0"?>

<soap:Envelope

            xmlns:soap="http://www.w3.org/2001/12/soap-envelope"             soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

            <soap:Body>

                        <m:GetPriceResponse  xmlns:m="http://www.w3schools.com/prices">

                                    <m:Price>1.90</m:Price>

                        </m:GetPriceResponse>

            </soap:Body>

</soap:Envelope>

SOAP Fault

When an error occurs during processing, the response to a SOAP message is a SOAP fault element in the body of the message, and the fault is returned to the sender of the SOAP message.

The SOAP fault mechanism returns specific information about the error, including a predefined code, a description, the address of the SOAP processor that generated

A SOAP Message can carry only one fault block

Fault element is an optional part of SOAP Message

For the HTTP binding, a successful response is linked to the 200 to 299 range of status codes;

SOAP fault is linked to the 500 to 599 range of status codes.

Organization -1 : Publishing Webservices Steps

1)      Create a Publishing Class which will create records in the Object

2)      Standing on that class,  select the button “Gernerate WSDL” and save xml output as “General.wsdl” file

3)      In Appsetup -> Develop -> API,  Generate “Partner.wsdl”  file

Note:  Give both General.wsdl and Partner.wsdl files to external team

Organization -2 : Consuming Webservices Steps

1)      Go to Apex Classes and select “Generate from WSDL” button and give input as imported “General.wsdl” file  (It will create one class)

2)      Again from Apex Classes select “Generate from WSDL” button and give input as imported “Partner.wsdl” file    (It will create three classes)

3)      Registering in remote access “GeneralWSDL”

4)      Registering in remote access “PartnerWSDL”

5)      Create a class to Invoke Publishing Class / Method

6)      Create a Trigger under the Object

Note:  Test Webservice by creating a record in Organization-2 and verify if this record is reflected in Organization-1 which is publishing organization

Web Services – Publishing steps in Org-1       (batch0248@capital.com)

1)      Create Publishing class and method

2)      After creating the class, select “Generate WSDL” button in class itself and save xml output as  “generalWSDL.wsdl” file

Select  “Generate WSDL” button

It will the give the following xml output

Right click and Save it as “Pub_GeneralWSDL.wsdl”

3)      Generate “Partner.WSDL”

Appsetup -> Develop -> API

Select “Generate Partner WSDL” url link

It will give the following xml output

Right click and save as “Pub_PartnerWSDL.wsdl”

Note: Give both WSDL files to Consuming Organization.

Web Services – Consuming steps in Org-2       (Integration49@capital.com)

7)      Go to Apex Classes and select “Generate from WSDL” button and give input as imported “General.wsdl” file  (It will create one class)

AppSetup(Build)  -> Develop -> Apex Classes

Select “Generate from WSDL” button.

It will ask for file name

Browse and select the Pub_GeneralWSDL.wsdl file as input.  Then select “Parse WSDL” button

It will show the following screen :

Change the Apex class name as “Con_OpportunitiesCLS” then select “Generate Apex code” button.

It will show the successful creation of class in this Org-2.

8)      Again from Apex Classes select “Generate from WSDL” button and give input as imported “Partner.wsdl” file    (It will create three classes)

Select “Generate from WSDL” button.

It will ask for input file:

Browse and select the second file “Pub_PartnerWSDL.wsdl” file as input.

Then select “Parse WSDL” button. 

Change all three class as above and then select “Generate Apex code” button.

It will show the following success screen

Verify the three classes in Appsetup -> Develop -> Apex Classes.

9)      Registering in remote access “GeneralWSDL”

Administration setup  -> Security Controls -> Remote Site Settings

Select “New Remote Site” button.

Enter the following

a)      Enter “Remote Site Name” as Opt_General_Site

b)      Enter “Remote Site URL” as given bellow (Endpoint url from Con_OpportunitiesCLS)

c)      Select “Save” button

Note: Copy the Endpoint url from Con_OpportunitiesCLS as show below

10)  Registering in remote access “PartnerWSDL”

Administration setup  -> Security Controls -> Remote Site Settings

Select “New Remote Site” button.

Enter the following:

a)      Enter “Remote Site Name” as “Opt_Partner_Site”

b)      Enter “Remote Site URL”    as End point URL from “Con_OptPartnerCLS” Class as shown in the note below

c)      Select “Save” button

Note: Copy Endpoint URL from

11)  Create a class to Invoke Publishing Class / Method

public class Con_Opt_Invoke_Class{
 @future(callout=true)
  public static void Con_Opt_Invoke_Ins_Mtd(Id d)
  {
    Opportunity optrec=[select name, description, account.name from Opportunity where id=:d];
  
    Con_OptPartnerCLS_3.Soap        obj1  = new Con_OptPartnerCLS_3.Soap();
    Con_OptPartnerCLS_3.LoginResult lr    = obj1.login('vizsri4.sfdc@gmail.com','xyz99992zD6Qlq3pV4hWWU0sfZFzIyT');

    Con_OpportunitiesCLS.Pub_OpportunitiesCls  obj = new Con_OpportunitiesCLS.Pub_OpportunitiesCls();

    obj.sessionHeader           = new Con_OpportunitiesCLS.sessionHeader_element();
    obj.sessionHeader.sessionid = lr.sessionId;

    obj.Pub_InsertOptMtd(optrec.name, optrec.description, '0019000000RcEWX');
  }
}

12)  Create a Trigger under the Object

trigger S2S_Opt_Webservice on Opportunity (after insert)

{

    Con_Opt_Invoke_Class.Con_Opt_Invoke_Ins_Mtd(Trigger.new[0].id);

}