Following are some of the considerations in designing and implementing Webservice callouts from SFDC.
API vs Services:
Imagine consuming Salesforce Enterprise WSDL in Apex (WSDL2Apex). It is going generate a ton of classes for each object and public function for every API method exposed. The same case applies for consuming WSDLs from Manhattan, SAP, Eloqua, IBM MDM or any application specific SOAP API. These generally include all the methods, its input and output signatures. SFDC does not have a provision to select operations to generate Apex classes. This is when we encounter most of the limitations such as:
- Issue: External schema reference import
- Failed to parse wsdl: Found schema import from location —–. External schema import not supported
- Solution: This works most time when there is only one level of reference. If there nested schema reference and chameleon target namespaces then this method will not work.
- Open the WSDL in XML editor and locate the schema import section.
- Got to the URL which specific the xsd and download the full schema.
- Remove the schema import and copy paste the full schema
- Issue: WSDL Size limit – 1MB
- Solution: manually edit the WSDL before running it through WSDL2Apex (WSDL-hacking). NOTE: while this technically works, it puts an enormous burden on maintenance and future upgrades. In our experience, it takes 1-2 hours to correctly “hack” a WSDL and they will need to be manually “hacked” every time there is a new version to WSDL or any changes to signatures.
- Having a middleware significantly reduces the complexity. The APIs are consumed in the middleware and the methods which are required to SFDC is exposed as proxy/virtual services. This way the apex classes generated in SFDC are relevant and easy to maintain.
- Incase if middleware is not available, you can remove the WSDL operations, unwanted bindings, portypes, wsdl types using SOAP UI or any of the XML editor tools (XMLPad, XMLSpy). This way only the methods which are required are imported into SFDC.
Although WSDL is a standard there are several variations and vendors interpret it in more than one ways. Before consuming the WSDL into SFDC, following checks help on compliance and overcome SFDC limitations.
- SOAP 1.2 is not supported. Use SOAP UI to review the bindings. An enterprise service typically includes various bindings – SOAP, JMS, WCF etc. Remove the unwanted bindings and request the service provider to generate SOAP 1.1 bindings. Middlewares such as webMethods, Tibco, IBM Datapower has configuration to generate the right bindings.
- Also WS-I compliance helps to check there are no vendor specific elements or attributes. Using SOAP UI we can validate WS-I compliance.
- Supported data types
One of the key factors which could drive complexity is the input and output signatures of the operation. Although this cannot be controlled for public APIs from standard applications, custom WSDLs generated can take into consideration the following items:
Ideally a flat structure for input and output is easier to parse it may not be the case all the time. Avoiding complex/nested structures reduce the number of classes generated (For each complex type a new class is generated)
Once the Apex classes are generated review the HTTP Header and SOAP Header classes. Ideally you can create custom setting to store the values required to pass to the header objects.
- Search Use-cases: One of the common use cases is provide search services in SFDC. This could be Order search, Invoice search or any business intelligence available in an on-premise or other cloud applications. Following guidelines help in implementing search services
- All the Search service request have row count (configurable) and front end validation to enforce search parameters. Similarly the service provider has the strict enforcement on timeout, number of rows returned and provide pagination for the client to fetch more records by specific page number, number of records. The maximum callout limit is 120 sec. SFDC Callout limits and limitations Link
- Create/Update Use-cases: For use cases like creating an order, converting an opportunity to quote etc. Instead of passing the entire business data, its recommended to pass the identifier and have the client query back using SOQL to fetch the entire dataset. This way the WSDL structure is simple and the majority of the complexity will reside in the SFDC SOAP API which is more robust and scalable.