Pivotal CRM Integration Model using Web Services

Cloud computing has ushered an increased demand for applications to inter-operate using the Internet. Web services make this possible.

 

This article describes an approach for using web services to integrate Pivotal CRM with other applications. A web service component in this approach is generated by the CDC Software Pivotal CRM free download called Web Service Generator (WSG) WSG facilitates the creation of web services that abstract the complexity of interfacing with the Pivotal CRM platform and satisfying platform requirements.

 

Web service capabilities have existed for more than a decade. Regardless, Internet application innovators such as Salesforce.com, Facebook, Twitter, LinkedIn, Google, and Microsoft have popularized the benefits of web services with their successful Internet application platforms.

 

Web services are a key component of a Service Oriented Architecture (SOA). A SOA relies on web services to provide inter-operation between application systems. I'm currently working on a notable SOA implementation you can ask me about. This SOA implements the common messaging framework Universal Lexical Exchange (ULEX), enterprise service bus Mule ESB, and Java platform application server JBoss AS. For more on SOA, read "Service-oriented architecture" on Wikipedia, http://en.wikipedia.org/wiki/Service_oriented .

 

Even if you do not have an enterprise-wide SOA to plug into, the benefits of implementing web services are well worth considering. Some of the benefits of implementing Web services are the following:

 

• - Provide a means for loosely-coupled communication between applications
• - Rely on standard Internet protocols for communication
• - Pass data in a well-defined, easily understood format
• - Expose a simple interface to an application platform
• - Abstract underlying complexity
• - Facilitate reuse by other applications

 

To best describe Pivotal CRM integration using web services, let me describe an example that closely resembles how I implemented one for a client of mine. At this client, there is an application we will call Apex Trade & Commission Manager (ATCM). A feature of ATCM is that it tracks equity trades made on behalf of account holders.

 

The integration between ATCM and Pivotal CRM is to share data bi-directionally and initiate Pivotal CRM work flow. More specifically, the integration requires the following:

 

• - ATCM Trade information needs to be shared with Pivotal CRM
• - Pivotal CRM is to qualify Trades for initiating scheduled Call Activities
• - Pivotal CRM account information needs to be shared with ATCM

 

The integration is implemented using three web service components. One web service is dedicated to each application, abstracting application specific interface requirements. Another web service is generated and published by Pivotal WSG, abstracting Pivotal CRM platform complexities. This generated web service is necessary only for inbound data to comply with Pivotal CRM platform requirements that initiate AppServer Rules/Server Tasks.

 

 

 

Each dedicated application web service mediates inbound and outbound data. In our example, outbound data is read from database tables containing queued and archived items. The tables are populated by table Triggers. The outbound data is transformed to the target web service's defined format. After processing items, data is archived by an update that either sets the item as successfully processed or with a descriptive error. 

 

Inbound data is validated and transformed to its target destination by the web service dedicated to its application. In our example, the ATCM web service processes inbound data and directly updates the ATCM database. Inbound data consisting of new and updated accounts from Pivotal CRM are created and updated in ATCM.

 

 

 

Towards the other end-point, the Pivotal CRM web service validates and transforms inbound data to the defined format required by the Pivotal CRM generated web service. This format includes an object representing essential fields on an Active Form. After transforming the inbound data for the object, the object is sent to the Pivotal CRM generated web service.

 

 

 

The Pivotal CRM generated web service then processes the object and submits the data to Pivotal CRM, referencing the appropriate Active Form. Following Pivotal CRM convention, the Active Form is used to enter data and call its AppServer Rule/Server Task. In our example, the Trade Active Form AppServer Rule/Server Task qualifies the Trade and determines whether a scheduled Call Activity is created.

 

And there you have it, an approach for integrating Pivotal CRM with another application using web services. You now have some insight on how your Pivotal CRM implementation can reap the benefits of a web services. "Loosely-coupled", easier to change, move, and re-use; communication using standard Internet protocols; well-defined data format, easily shared, understood; simplified application interface, abstracting underlying complexity; these are some of the benefits of implementing web services.

 

Freely contact me if you have questions or would like more information, or even need some help. I would love to hear what you are doing. Oh, and follow-me on Twitter .

 

Service-oriented architecture http://en.wikipedia.org/wiki/Service_oriented

Enterprise Service Bus http://en.wikipedia.org/wiki/Enterprise_service_bus

Web service http://en.wikipedia.org/wiki/Web_Services

 

Pivotal Lifecycle Server XML Interface Error 800a0e7c Parameter object is improperly defined

Error 800a0e7c, 'Parameter object is improperly defined...', is one those errors that is practicely useless for troubleshooting.
 
Here is more of the error as logged by the Pivotal Lifecycle Server XML interface:

<error> <errorNumber>800a0e7c</errorNumber> <errorText>Parameter object is improperly defined. Inconsistent or incomplete information was provided.</errorText> <errorDetails> HRESULT = 800A0E7C -- Unknown error
...
</errorDetails> </error>

I've seen this error before when working with VB6, and you may have also.  The error is thrown by ADODB, an ActiveX Data Object. My most recent occurrance was in troubleshooting a web service implementing RXMLWriteSystem, a Pivotal Lifecycle Server XML interface.  The web service submits an XML payload using the DoXMLCommand method. 

What is counter-intuitive when troubleshooting this Pivotal XML interface ADODB error is that whether the command is a record insert or update, the command correctly executes a transaction to insert or update a record.  However, instead of returning a command result containing a record id for an insert or nothing for an update, the aforementioned error is returned.  Since an error is returned to the calling program other errors may be thrown or the calling program does not perform as intended.

I remember troubleshooting this error years ago in a similar situation.  Back then I had documented the error, its circumstance and resolution.  This gave me an advantage in quickly resolving the issue. 

The resolution to this error from my experience is the following:

The application pool running the web service that implements the Pivotal XML Interface must use an account identity having sufficient security permissions in Pivotal.  The system account ‘Network Service’ can not be used for the application pool identity.

From the transaction result and the resolution, you can see that the error does not offer much help in providing insight to a resolution.

Pivotal CRM Web Service Generator

Recently I installed the Pivotal CRM Web Service Generator (WSG) tool provided by CDC Software.  With the tool, I quickly generated web services for an integration service I built between a custom developed finance application and Pivotal CRM.

Installation
Installing WSG includes an RDF import.  The RDF import is required to generate the web service.  The RDF import is not required to provide functionality to the web service after the web service is created.

WSG requires the security group 'Relationship Administrator' to successfully generate a web service.  If the 'Relationship Administrator' security group is missing, as it was for the Financial Services vertical I support, it can be imported from the out-of-the-box business module (BM).  Export the security group using the Toolkit Transporter and import it into the target BM.

Implementation
WSG can generate a Visual Studio .NET 2003 project containing the web service methods and a class for the Active/Rich Client form.  The methods can include Insert, Update, and Delete. The class representing the form contains fields for the form's primary field values.  Some primary fields may be missing in the class. To add the missing fields, either customize the generated web service or pass the missing field names and their values as a string array parameter.  If you pass a parameter you handle it as usual in the form's server rule.

Unfortunately, WSG web services do not support secondary form segments and fields.  Since WSG web services use the Pivotal CRM XML Interface, it is feasible to customize the generated web service to process secondary fields.  I chose to leave the code as-is and not customize it.  Instead, I created another web service to process the secondary fields using the secondary's Active/Rich Client form.  For the  integration service, I have the the web service for the secondary fields consumed after the web service for the primary fields.

Conclusion
Pivotal CRM Web Service Generator is a helpful tool for quickly generating web services that can insert, update, and delete Pivotal CRM records using the Pivotal CRM XML Interface.