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.
- 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.
- 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.
- 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.
Posts
