Communication between client and server is through HTTP/S and XML. 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.example.com/Service.do path
2. The Host specified with the host name that is used to access the web application; like www.example.com
3. Content-Type set to "text/xml"
4. Content-Length set to the number of characters of the XML being submitted
5. Two (2) empty lines
6. The XML string, defined in the next section
7. Optional Cookie information so that additional requests are handled quicker

POST http://www.example.com/Service.do HTTP/1.0
Host: www.example.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:

• clientId- The client's assigned Id by the server
• code- The \.code value set in the database
• systemId- A Server assigned id to map transactions to, typically 1

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 data, update an object, or query a list of objects. Depending on the transaction type, meta data can be included to request additional 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:

1. 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.
2. objectName- the object on which an action is to be performed
3. action- the action to be performed on the object

3. Example Client XML Request

<?xml version="1.0" encoding="UTF-8"?>
<app>
  <authentication>
    <clientId>1</clientId>
    <code>plaintext-code-in-database</code>
    <systemId>1</systemId>
  </authentication>
  <transaction id="1">
    <service action="getDateTime"/>
  </transaction>
  <transaction id="2">
    <meta>
      <property>id</property>
      <property>title</property>
    </meta>
    <projectList action="select">
      <uniqueId>main-profile</uniqueId>
    </projectList>
  </transaction>
</app>

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" standalone="no"?>
<concursive>
  <response id="1">
    <status>0</status>
    <errorText/>
    <recordSet count="1" name="service">
      <record action="info">
        <dateTime>2010-04-20 13:59:39.505</dateTime>
      </record>
    </recordSet>
  </response>
  <response id="2">
    <status>0</status>
    <errorText/>
    <recordSet count="1" name="projectList">
      <record>
        <id>3995</id>
        <title>Main Profile</title>
      </record>
    </recordSet>
  </response>
</concursive>