XML API Protocol
Both the Centric CRM Server and the Client (Sync Client or Centric CRM User) can communicate by sending XML packets. The Client is required to understand the structure of the XML response, so that it can process any records sent by the Server.
XML-HTTP
The Client initiates the data transfer procedure by establishing an HTTP/S connection with the Server. Once the connection is active, the client posts XML data to the Server using HTTP POST. The Server will process the data and return a status along with any data that was requested.
HTTP Packet
The raw HTTP must include the following:
1. Request Method set to "POST" along with http://www.your-centriccrm-server.com/ProcessPacket.do path.
2. The Host specified with the host name that is used to access the Centric CRM installation
3. Content-Type set to "text/xml"
4. Content-Length set to the number of characters of the XML being submitted
5. commit-level set to either "packet" or "transaction", defaults to 'packet'
6. object-validation set to "true" or "false", default to 'true'
7. Two (2) empty lines
8. The XML string, defined in the next section
POST http://www.your-centriccrm-server.com/ProcessPacket.do HTTP/1.0 Host: www.your-centriccrm-server.com Content-Type: text/xml Context-Length: 11 <xml></xml>
XML Request Packet
Each time a new HTTP request is made, the Client must include authentication information and one or more transactions in the body content. The encoding method provided by the Client in the request will be used in the reponse. If no encoding is specified, then UTF-16 is used by default.
1. Authentication
The Client identifies itself to the server by sending XML authentication information to the server. The server looks up the client information, and if successful processes the transaction. If authentication fails, a failed message is returned to the client.
The authentication information includes the following items:
- id - The host the client is connecting to
- code - If it is a sync client, then provide [sync_client].code else if user, the MD5(password) Hash
- systemId - A Server assigned id to map transactions to (allows for multiple systems to be interacting)
- clientId - Provide only if it is a Sync Client else dont include
- username - Provide only if it is a Centric CRM User else dont include
2. Transaction
Within the same request as the authentication information, one or more transactions must be specified. The transactions describe to the server an action to be performed. For example, the action could be to insert an object, update an object, or query a list of objects. Depending on the transaction type, meta data can be included to describe the requested information from the server.
Transactions include the following items:
- Meta information to describe data related to the action being performed
- The action to perform
An action is composed of the following items:
- id - a client supplied transaction id to reference the transaction status responses; the transaction id is valid only for the given request/response and does not affect other client's requests/responses.
- objectName - the object on which an action is to be performed
- action - the action to be performed on the object
3. Example Client XML Request
<?xml version="1.0" encoding="UTF-8"?> <app> <authentication> <id>www.your-centriccrm-server.com</id> <systemId>4</systemId> <username>XXX</username> <code>** User's MD5 Password
</authentication>
<transaction id="1">
<meta>
<property>id</property>
</meta>
<account action="insert">
<name>Dark Horse Ventures</name>
</account>
</transaction>
</app>
</code>
4. XML Response Packet
When the server completes the requested transactions, an XML HTTP response is sent back to the client. The response includes a status corresponding to each transaction requested by the client, and any other data pertaining to the requested action.
1. Status; 0 = Success, Non-Zero = Error
2. ErrorText; if no error then no text, otherwise a message is provided
3. Example XML Response
<?xml version="1.0" encoding="UTF-8"?> <aspcfs> <response id="1"> <status>0</status> <errorText/> <recordSet name="accountList" count="1"> <record action="insert"> <name>Dark Horse Ventures</name> </record> </recordSet> </response> </aspcfs>
Sign in to add your comment.