The goal of this document is to explain how to use the NCS ContextData API. This API allows reading and writing different kinds of data hosted by the Nixxis Application Server.
The API allows accessing the ContextData application through HTTP communication. The HTTP base URI can be constructed as follow and allows reaching the API by many ways as Web Browser, Http Request, etc…
Where:
· <AppServer> is the CrAppServer Ip or Host name
· <Port> is the CrAppServer communication port
· <Application> is the ContextData application name as defined in http.config, usually “Data”
This base URI must be followed by the instruction to the API as HTTP parameter. These instructions are composed of an action part specifying the requested action and, if needed, variables containing the action parameters.
The complete URI must look like this:
API methods accept several specific parameters. Some parameters are common to a big part of the methods. These parameters are: context (which define a campaign), activity (which define an activity) and contact (which define a call). They are all three allowing the identification of a precise context associated to the impacted data. Therefore, using those three parameters together to get campaign information make no sense.
Indeed, a contact defines the activity and the campaign. In the same way, specifying the activity implies the campaign choice. When more than one parameter is provided, the system always use the one giving the more details (contact first, then activity and at last, campaign).
This section describes precisely methods provided by the API.
This method allows creating a record.
|
Parameter |
Description |
|
context |
Identifies the campaign on which to perform the CreateContextData action. |
|
activity |
Identifies the activity (and consequently the campaign) on which to perform the CreateContextData action. |
|
contact |
Identifies a contact (and consequently the activity and campaign) on which to perform the CreateContextData action. |
|
id |
An internal record identifier. |
This method allows creating data information in the registered external applications.
|
Parameter |
Description |
|
xapp |
An identifier for an external application that is defined in the HelperAssemblies. |
|
xkey |
A search key for the external application indentified by xapp. |
This method allows getting information from internal and/or from external applications.
Retrieve the information describing the campaign data record for the contact identified by the provided context identifier and the internal record identifier.
|
Parameter |
Description |
|
context |
Identifies the campaign on which to perform the GetCompleteData action. |
|
activity |
Identifies the activity (and consequently the campaign) on which to perform the GetCompleteData action. |
|
contact |
Identifies a contact (and consequenctly the activity and campaign) on which to perform the GetContextData action. |
|
id |
An internal record identifier. |
|
xapp |
An identifier for an external application that is defined in the HelperAssemblies. This parameter is taken into account only when the id parameter is not specified. |
|
xkey |
A search key for the external application identified by xapp. This parameter is only meaningful when used in conjunction with xapp |
|
{fieldName} |
A dynamic parameter indicating a field in the context database which can be set to perform a search action on the indicated field. This parameter is taken into account only when id and xapp are not specified. |
This method allows getting information on a campaign and its activities based on the provided context identifier.
|
Parameter |
Description |
|
context |
Identifies the campaign on which to perform the GetContext action. |
This method allows getting the ContextData element describing the campaign data record for the contact identified by the provided context identifier and the internal record identifier.
|
Parameter |
Description |
|
context |
Identifies the campaign on which to perform the GetContext action. |
|
activity |
Identifies the activity (and consequently) the campaign on which to perform the GetContextData action. |
|
contact |
Identifies the contact (and consequently the activity and campaign) on which to perform the GetContextData action. |
|
id |
An internal record identifier. This cannot be used along with the parameter {fieldName}. |
|
xapp |
An identifier for an external application that is defined in the HelperAssemblies. This parameter is taken into account only when the id parameter is not specified. |
|
xkey |
A search key for the external application identified by xapp. This parameter is only meaningful when used in conjunction with xapp |
|
{fieldName} |
A dynamic parameter indicating a field in the context database which can be set to perform a search action on the indicated field. This cannot be used along with the parameter id. |
|
history |
Number of contact's history to include in the result. |
This method allows getting the name and the MS SQL database connection string for the campaign identified by the provided context identifier.
If available a fieldsconfig element describing the campaign data table layout is included.
|
Parameter |
Description |
|
context |
Identifies the campaign on which to perform the GetContext action. |
This method allows getting data record information in the registered external applications.
|
Parameter |
Description |
|
xapp |
An identifier for an external application defined in the HelperAssemblies. |
|
xkey |
A search key for the external application identified by xapp. |
This method allows getting the internal identifier of a specific client from a given application. This means that you can find the identifier on one or many applications.
|
Parameter |
Description |
|
xapp |
An identifier for an external application that is defined in the HelperAssemblies. |
|
xkey |
A search key for the external application identified by xapp. |
|
context |
Indetifies the campaign on which to perform the GetContext action. |
|
activity |
Indetifies both the activity and the campaign on which to perform the GetContextData action. |
|
contact |
Indetifies all of contact, activity and campaign on which to perform the GetContextData action. |
|
{fieldName} |
A dynamic parameter indicating a field in the context database which can be set to perform a search action on the indicated field. This cannot be used along with the parameter id. |
|
|
The emailing inbound activity. |
|
cli |
The calling inbound activity. |
This method allows getting the identity of a record for the given application. Unlike the GetInternalIdentity method, here search can be done on all columns.
|
Parameter |
Description |
|
xapp |
An identifier for an external application that is defined in the HelperAssemblies. If the search is based on the internal id it must be equal to InternalId |
|
xkey |
A search key for the external application identified by xapp. |
|
tapp |
An identifier for an application different from the external application identified by xapp. |
This method allows getting information about the qualifications for the campaign identified by the provided activity identifier..
|
Parameter |
Description |
|
activity |
Indetifies both the activity and the campaign on which to perform the GetQualifications action. |
|
contact |
Indetifies all of contact, activity and campaign on which to perform the GetQualifications action. |
This method allows getting the fieldsconfig element describing the campaign database layout for the campaign identified by the provided context identifier.
|
Parameter |
Description |
|
activity |
Indetifies both the activity and the campaign on which to perform the GetQualifications action. |
|
contact |
Indetifies all of contact, activity and campaign on which to perform the GetQualifications action. |
This method allows getting information on the available campaigns and their activities.
This method allows getting information about identities based on the given application with the given search key.
|
Parameter |
Description |
|
xapp |
An identifier for an external application that is defined in the HelperAssemblies. |
|
xkey |
A search key for the external application identified by xapp. |
This method allows getting information about external application.
This method allows getting the contact data of a campaign or an external application that match the given
This method can also be used as a “list all record” instruction, by setting a % as searching value. Anyway be careful to no set a too large maxcount to avoid request timeout.
|
Parameter |
Description |
|
context |
Indetifies the campaign on which to perform the ListMatchingData action. |
|
activity |
Indetifies both the activity and the campaign on which to perform the GetContextData action. |
|
{fieldName} |
A dynamic parameter indicating a field in the context database which can be set to perform a search action on the indicated field. |
|
returnfields |
List of the returned fields to extract from the entire response. |
|
maxcount |
Number of records to retrieve from the response. Default is 100. |
This method allows getting the data from a given stored procedure including or not the XML schema in the response.
|
Parameter |
Description |
|
source |
The identifier used in the Http.config file: remember the point configuration – http.config. |
|
exec |
The name of the stored procedure to execute. |
|
{fieldName} |
A dynamic parameter indicating a field in the context database which can be set to perform a search action on the indicated field. |
|
@parameter(s) |
The parameter(s) for the given stored procedure. |
|
schema |
A boolean parameter, true by default, which indicates whether or not to include the xml schema with the returned xml document. |
|
db |
The database to use. Not needed if it is written in the Http.config file. |
|
output |
Get the response formatted in a csv format. Value to indicate is csv. |
|
skip |
Number indicating how many first records from the received result are not included for the final result. Default is 0. |
|
nonull |
A boolean value indicating to include or not the fields that contains null values. Default is false. |
|
timeout |
Set the number of seconds for the time out. Default is 0. |
|
encoding |
Set the encoding type for the result. Default is Unicode. |
This method connect a contact to a data record of an activity.
|
Parameter |
Description |
|
contact |
Indetifies all of contact, activity and campaign on which to perform the chosen action. This is the minimum parameter requiered. |
|
id |
An internal record identifier. |
|
dispatch |
A boolean parameter, true by default, which indicates whether or not to update the dispatcher. |
This method allows to update the current data(s).
|
Parameter |
Description |
|
context |
Indetifies the campaign on which to perform the UpdateContextData action. |
|
activity |
Indetifies both the activity and the campaign on which to perform the UpdateContextData action. |
|
contact |
Indetifies all of contact, activity and campaign on which to perform the UpdateContextData action. |
|
id |
An internal record identifier. |
This method allows to update data information in the registered external applications.
|
Parameter |
Description |
|
xapp |
An identifier for an external application that is defined in the HelperAssemblies. |
|
xkey |
A search key for the external application indentified by xapp. |
In order to manage your campaign data, you need to know the id of your campaigns and activities. The method allowing that is ListContexts which’s returning the list of campaign and their child activities.
|
Uri |
/data/?action=ListContexts |
|
Methode |
GET |
|
Result |
<contexts> <context id="[id]"> <description>Campaign1</description> <activity type="InboundActivity" mediatype="2" id="[id]"> <description>Activity1</description> </activity> <activity type="OutboundActivity" mediatype="1" id="[id]"> <description>Activity2</description> </activity> </context> <context id="[id]"> <description>Campaign2</description> <activity type="OutboundActivity" mediatype="1" id="[id]"> <description>Activity1</description> </activity> </context> </contexts> |
You can extract the id of a campaign or an activity by reading the attribute id of context or activity key depending if you want to get the campaign or activity data.
If you already know the id of the campaign but want to list its child activities. The method GetContext is more effective.
|
Uri |
/data/?action=GetContext&context=[id] |
|
Methode |
GET |
|
Result |
<contexts> <context id="[id]"> <description>Campaign1</description> <activity type="InboundActivity" mediatype="2" id="[id]"> <description>Activity1</description> </activity> <activity type="OutboundActivity" mediatype="1" id="[id]"> <description>Activity2</description> </activity> </context> </contexts> |
This method allows getting the information of a record
|
Uri |
/data/?action=GetContextData&context=[id]&id=[InternalID] or /data/?action=GetContextData&context=[id]& {fieldName}=[value] |
|
Methode |
GET |
|
Result |
<contextdata> <campaigndata> <key>value</key> </campaigndata> <key>value</key> </contextdata> |
In the second Url, {fieldname} could be any key of the record that indetifies it uniquely:
If a unique constraint is applied on Phone_Number, you can be sure that it identifies one and only one record so you can use for example:
If you do not have a unique identifier you can use ListMatchingData to get a list of record and then select the one which’s interesting.
The other feature of list matching is the possibilities to use MS SQL “like patern”.
|
Uri |
/data/?action=ListMatchingData&context=[id]& {fieldName}=[value]&returnfields=[fieldname] or /data/?action=ListMatchingData&context=[id]& {fieldName}=%[value]%&returnfields=[fieldname] |
|
Methode |
GET |
|
Result |
<resultset> <element internalid="[InternalId]"> <Name>[Name]</Name> <Phone>[Phone]</Phone> </element> <element internalid="[InternalId]"> <Name>[Name]</Name> <Phone>[Phone]</Phone> </element> </resultset> |
Value for ReturnFields accepts multiple fields name separated by a coma.
This method allows to replace existing record data by new ones, as modify the name or set it excluded
|
Uri |
/data/?action=UpdateContextData&context=[id]&id=[InternalID] or /data/?action=UpdateContextData&context=[id]& {fieldName}=[value] |
|
Methode |
POST |
|
Data |
<contextdata> <campaigndata> <key>value</key> </campaigndata> <systemdata> <key>value</key> </systemdata> </contextdata> |
In the second Url, {fieldname} could be any key of the record that indetifies it uniquely:
For example if a unique constraint is applied on Phone_Number, you can be sure that it indetifies one and only one record so you can use for example :
This method allows creating a new record in the database.
|
Uri |
/data/?action=CreateContextData&context=[id] |
|
Methode |
POST |
|
Data |
<contextdata> <campaigndata> <key>value</key> </campaigndata> <systemdata> <key>value</key> </systemdata> </contextdata> |
A XML document is returned containing data of the new record.