Developers Guide

The XData API

XData is designed as a RESTFUL web interface for ACT , the XData API allows 3rd party applications to connect to an ACT database , perform standard CRUD methods on select ACT entities and also execute some CRM functions within ACT.

XData portal sites are referred to as XData providers, 3rd party applications which use XData are referred to as XData consumers.
 

Security and Access Control

There are a number of way in which an XData provider can apply security and consumer access control methods, for example communication with an XData provider can be secured through HTTPS in addition XData consumers are assigned unique API keys, each key has its own access control list. through access control an XData administrator can determine which functions a given key has access to.

In addition XData utilizes the access control features it inherits form ACT (since it is built using the ACT SDK) , as a result it is possible to further secure XData using ACT’s own user access model.

Data exposed by an XData providers can be filtered through the use of user access restrictions applied to the ACT user profile utilized by XData, it is also possible to use Remote database to further isolate the database exposed by an XData provider from the main ACT database.
 

The Request / Response Model

Communication with XData providers follows a Request / Response model , an XData consumer makes a request to an XData provider, the response is sent back to the consumer and its result is interpreted based on the XData protocol.

When a request is made the consumer specifies the function call and provides any parameters needed to the XData provider so that the call is executed successfully, the request also includes the API key (see below) which is used to verify that the consumer has access authorized access to the function being called.

XData responses can be analyzed to check if the call was successful or if the call resulted in an error, error messages can be logged or displayed to the end user etc.
 

API Keys

In order for an XData consumer to successfully communicate with an XData provider the consumer needs to supply an authorized key, this key is generated by the XData provider, a given key is unique to one and only one XData provider.

Key values can be embedded as an HTTP header called “key” when sending an XData request.
 

XData URIs

Calls to XData providers must comply with a specific URI format, a typical XData URI look like this:

• http://YourHost/XData/ACT/Contacts/
• http://YourHost/XData/ACT/Contacts?LookupField=City&LookupValue=Sydney
• http://YourHost/XData/ACT/Contacts/CreateContact/
• http://YourHost/XData/ACT/Contact/UpdateContact?ID=xxxx-xxxxxx-xxxxxx-xx

The XData URI is formatted as follows:

http(s)://HostName/XData/Platform/FunctionGroup/FunctionCall?Parameter=Value

• HostName, this is the Server name or the IP address of the machine hosting an XData provider
• XData, The XData portal
• Platform, typically this defaults to the ACT CRM although it is possible to create an XData provider for different platforms.
• FunctionGroup, Collections of related XData functions are grouped together in a function group (e.g. all Contact related functions are grouped under Contacts)
• FunctionCall, the identity of a specific function call (e.g. AddContactToGroup) , there is a number of different function call each with their own set of parameters, consult the API Functions Reference section for more details.
• Parameters and values , Some XData functions may require that the consumer supplies a parameter and value set when making a specific function call, there are functions that require no parameters, functions with optional parameters and functions with mandatory parameters.

For more information consult the API Functions Reference sections.

A Note on the default function calls: the default function calls in XData are used to list the entities belonging to a specific function group, for example the following call lists all the Contact Records for an ACT database using XData.

http://SomeHost/XData/ACT/Contacts/

Default function calls correspond to the Default page on a webserver (e.g. Default.aspx or Index.php etc) , unless otherwise stated all default calls return a records listing for the database entity represented by a given function group.
 

Reading Data & The XData Response Format

XData requests and responses are based on the XML language format, they are designed to be easy to construct and read, below is a description of the XData Response template.

• The first line in the response identifies the response data as being of type XML
• The XDataResponse tag denotes the response as of that belonging to XData
• The Status property is used to indicated whether the response was successful or not
• The Payload tag contains the result of the function call (e.g. a list of contacts, the details of an activity etc).
• The Messages tag is used to communicate any messages from the XData provider (e.g. Error messages)

An example of an XData response to a Contacts list function call would look like this:

 

Writing and Updating Data

In addition to exposing the ability to read data from an ACT database, XData also provides interfaces for writing and updating data in ACT.

Function groups which support Create and Update operations expose a CreateEntity and an UpdateEntity functions (e.g. CreateContact, UpdateContact). functions of this type expect an XML formatted data string which is included as the request body for XData requests.

The XML request body must contain a properly formatted XML string which conforms to the XData specification, the following is an outline of the XData xml request body.

The <Payload></Payload> section must contain the information needed to create or update an entity using XData, refer to individual XData function calls for further details.

As a general rule most CreateEntity types of functions do not have any parameters associated with them while UpdateEntity functions always expect an ID parameter with the value of the entity record which needs to be updated.