The Pivotal XML Interface – Getting Started

Well, it’s been quite some time since my last post regarding the Pivotal XML Interface. I have had a few comments from readers asking for more details. So let me first start by providing a few technical links to references available on the net (I had to start my own R&D from somewhere… right?)

Pivotal’s latest XML API reference guide is available from the their eService website as part of the following API Reference document (this will require a valid login to the eService/ePartner site). I refer to this guide from time to time for the exact syntax/XML schema of the command to be sent to the Pivotal Business Server.

With that part over, lets take a look at what I will be covering in this post. As I mentioned in my earlier post as well, the XML interface is quite vast and has a lot of possibilities. However, it is not as documented and known as the regular COM/Assemblies interface of the PBS. With this post, I will help take the first step into creating your own XML command call to the PBS and show the return value.

For the purpose of this post, we will create an application which will authenticate the user name and password with the PBS to validate the user is a valid user of the system and then return the Data from the Employee Form for Cathy Green.

Before we start building this application, lets first identify the various tiers of our solution and how they will work together.

1. Our Custom Application: This tier is responsible to create a XML document which has a specific XMLCommand for the PBS. This application will also be sending this command to the PBS and getting a return value to show to the user.
2. XMLServices.asp Page: This page is located on the Pivotal Business Server. If you installed using the default properties, the page should be available at: http://yourservername/epower/xmlservices.asp. The purpose of this page is to take the XML document that the application is sending and pass it to the PBS after creating an instance of it.
3. The Pivotal Business Server: This, as everyone will know, is where the command will get executed and a return value sent back to the application in much the same way that it was received. We will not delve too much into this tier as you would already know a lot about this… :)

One important point to now here is that as an external application, you do not have control over the XMLServices page and PBS (… though you can debate that I can create ASRs in PBS and thus modify it, but from the interfaces perspective, you can’t change it). All you can do is work within your custom application tier and have PBS do what you want it to do… which mind you can be quite a lot when you get into more details.

Lets take this conversation one level deeper then (shall we?). What does our custom application need to do? Well, the answer is “Not much really, but quite a lot… all at the same time.”

For the purpose of this post, we will try to keep the functionality limited and focused for us to understand the structure of the XML streams and architecture of the PBS interface. So lets start with what is one of the most basic tasks… “Validating the Login user has an account in Pivotal”.

Now, in this interface, there is no direct function to call to authenticate a user. However, if you are able to call the PBS (using the interface of course) and get the user properties, then it implies that the user does in face have an account in the Pivotal system. (Whether he has permissions to do anything is a different question…) So we will build our first application to get the user profile for a particular user.

The first task of the application is to create an XML string that is compatible with the Pivotal Business Server. We can divide this XML into three sections (viz. the Header, the Content and the Footer).

The Header is constant data for all XML commands for any one system on any specific Pivotal Business Server. This section defines which system to access and the version of the Pivotal Business Server. A sample of the code to create the header part of the XML string is below.

The xmlns attribute indicates the version of the Pivotal Business Server and the SystemName element the Pivotal System name on the Pivotal Business Server.

The interesting element here is the LoginType. This element is used to identify which connection type in the security settings in Pivotal would be used for determining whether the user has permissions to certain functionality or not (I have successfully been able to use “Active Client” and “Extranet” for this element). You should choose which login type you want to use based on the user credentials and security settings specific to your environment.

After the header section comes the real tricky part of the XML command. This can be very simple (as in this particular case) and can also be quite complex as we need more complex functionality like running searches, reports, letter expresses, forms, server tasks (ASRs in earlier versions), etc.

To keep things simple, we will keep to our example of getting the userID from the system for the login user. For this, we just need to add a simple element in the content section of the XML Command as per the below code snippet.

The element getUserID is the actual command that we want to run and retrieve the Hexadecimal UserID of the current user who is running the XML application. To user a pre-configured user, you can run your application using impersonation or anonymous login.

Like the header, the footer section is also constant in that is is one simple line.

This closes the XML string and completes the input command.

The next step is to call the PBS and pass this XMLCommand to the XMLServices.asp page. As I mentioned in my previous post, the XMLServices.asp page gets installed with the PBS/Rich Client installation. This acts as the receiver for the XML Command string from external applications. We should note here, that this intermediary is only used in case your application is running on a separate machine from the PBS (which was one of the advantages of the XML interface… :) )

The XMLServices.asp page expects a POST request with the XMLCommand string. Here is a typical code snippet that can be used to send the XMLCommand to the PBS.

The last statement gets the response into a HTTPWebResponse object where we can further work with to extract the output XML string.

I won’t delve too much into the explanation of the above code as it is quite standard for HTTP web requests and responses.

So lets focus on the returned XML string. This contains the CommandResult element with information from the PBS. For our example to get the UserID, the expected XML String would look something like this:

The important part of the CommandResult lies in the Data Element. The information in this element varies depending on the command that has been sent to the PBS. In this case, we asked for the UserID, so only the UserID is returned.

Notice, that the “0x” is not prefixed with the UserID. Apart from this, the complete Hexadecimal ID is returned in string format. You can use this data further in your application and to further run queries where you are looking for current user based information, but remember to add the “0x” prefix.

It is important to note that in some cases where ID values are returned by the PBS, the “0x” is infact present. Thus it is always a good idea to have a look at the XML output before you decide what your parsing function should do.

This is getting to be a rather lengthy article so I will leave it at this. I know this is a very simple (rather too simple) implementation of the interface and many of you may not ever need this functionality. I will follow up this article with one focused towards calling a Server Task (earlier ASRs) using the XML interface. That will be more beneficial to more of the world.

I am open to questions/comments you may have about the interface regarding feasibility, approach, syntax, etc. Feel free to contact me directly with your specific questions and I will try to reply back at the earliest convenience.

Like I said, there is a lot that can be done using this interface. If you have any specific scenarios that you would like to see a post on, please feel free to let me know. I will try to address those scenarios in the next posts.

Using the Pivotal XML Interface

Looking at the integration strategies with Pivotal CRM for third party applications, I found that a lot of us still use the DCOM interface provided by the Business Server. This means that a lot of times we either host our application on the Pivotal Business Server or create web services to expose the Pivotal functionality to the third party application. With the new enhancements provided by CDC Software around the lines of templates and Web Services Generators, this strategy is becoming easier to implement.

In this post, I will not delve into which strategy is best and should be used as this would largely depend on the specific solution architecture and infrastructure/functional limitations of the implementation environment for Pivotal CRM or the third party application. Having said this, I would like to spend some time elaborating the XML interface that is available to third party applications to integrate with Pivotal CRM.

For those who have not yet worked with ePartner and eService, the XML interface is what is the back bone of these access methods into Pivotal CRM. All data and functional transactions between the ePartner and eService sites and the Pivotal Business Server have been built on the foundation of the XML interface. Surprisingly, even though it is used quite extensively in these access methods, there is not much documentation available regarding it's use... (I know this may not come as a surprise to some... :) ).

Over time, I have had to work with this method to integrate third party applications with Pivotal CRM. I had a tough time getting the correct command format, but at the end I got it and it worked wonderfully. Thus I have dedicated this post to give an insight to how you can get started with this XML interface and get some basic work done for your third party application.

So first things first... what is the architecture of this XML interface? Here is a diagram depicting what this interface is all about and how you can implement this with your Pivotal Implementation. For simplicity, I have only shown the functional components of the interface.

As you can see, the third party application interfaces with the Pivotal Business Server via an HTTP request. The content of the HTTP request is essentially a XML document which follows the Schema set by Pivotal. The request is managed by the Pivotal Business Server XMLServices.asp page and used to run the DoXMLCommand function. We will delve into the schema in more detail in further posts as the discussion can get very lengthy for one post, however the basic architecture of the XML document can be split into two parts.

1. The Command: The command element of the XML document contains basic header information regarding the Pivotal System Name, login credentials, connection type as well as the action that is being requested from the server. These action include (but are not limited to) getFormData, saveFormData, getSearchData, getTableData, executeAppServerRule, executeScript, and many more. All these commands give you the ability to perform almost all actions that a Pivotal Client would perform using the Pivotal Business Server.
   
2. The Command Result: The command result element has the content of the data returned from the Pivotal Business Server based on the action required. Thus if the command requested was getFormData, then the result would contain all the data for the form (inclusive of secondary data) as per the active form definition in the Pivotal system. Any errors that occur during the action are also reported in this element.

With the above two top level elements the third party application can request almost any action that a Pivotal Client would request from the Pivotal Business Server.

Before I close this post and start on the more technical explanation of the Command element, let me mention a few notes about the security and connection types used in the XML interface. As we all would know, when we define the security groups in our Pivotal systems, there are many connection types that are present. We define the security settings based on the type of connection used by the user. For example, if the Pivotal user is using the Windows Client, we would ensure that the security settings are on the LAN connection type. Similarly, Client for SmartClient access, Mobile connection type for synchronized systems, Extranet for ePartner and eService and so on.

With the XML interface, we can select which connection type we want to use for our security settings as this connection type is defined as part of the header section of the XML command. The two connection types I have been successfully using are "extranet" and "active client". With these we get the same security for the third party application that the same user would get using ePartner or Rich Client respectively. This would include access to Tables, Active Forms, Searches, Search Result Lists, etc. My recommendation is always to create a separate group for your Application and make the security settings to the group according to the business requirements and integration requirements. One point to note here is that since all the business logic of the server side will run for each of the relevant command actions, the security needs to be complete to handle any business logic dependencies.

In the next post regarding the XML interface, I will go deeper into the XML Command element and discuss the structure of the XML document for a few typical actions.