From SpiceCSM

Contents 1 Introduction 1.1 Web Call Integrations 1.1.1 Account Search/Load 1.1.2 Account Update 1.1.3 Case Update 1.2 API 1.3 Telephony Screen Pop/Integration 1.3.1 Required Variables 1.3.2 Optional Variables

Introduction

SpiceCSM comes with two types of integration capabilities to allow SpiceCSM to interact with third party applications. Please refer to the Spice Help Desk user manual on implementation.

Web Call Integrations

SpiceCSM comes bundled with the ability to make web calls to allow for the exchange of data between SpiceCSM and third party applications without direct contact between the applications. This structure allows SpiceCSM to integrate with third party applications that are hosted/installed remotely. In addition this structure provides a secure method of integration as SpiceCSM has no direct contact with the external application.

SpiceCSM uses HTTP POST submissions to send data to third party applications and receives data from third party applications in a predefined format (currently XML). Because of this structure the only requirements of the receiving web call are that it be able to accept HTTP POST variables and output the predefined format (XML). Any language that can meet these two requirements may be used.

Two POST variables are always passed no matter the call. This variables are intended to be used for passing authentication credentials.

intUser

intPass

Account Search/Load

SpiceCSM uses two web calls to retrieve external data for account records, the search and load options. For both options SpiceCSM sends search parameters via the web as HTTP POST variables and expects to receive a predefined (XML) structure. The call is made to a specified URL that receives the variables, queries the appropriate data source, and returns the results.

While there are a number of HTTP POST variables that will be passed, the author of the receiving call may choose to limit which variables are used in the search query. In addition the author has full control over the type and amount of data that is returned.

Following are the variables that can be passed. Only variables that contain data will be sent.

Variable Name	Type	Description
Userkey	String	This refers to the account name.
FirstName	String
LastName	String
AddressOne	String
AddressTwo	String
City	String
Region	String
PostalCode	String
Country	String
PrimaryPhone	String
SecondayPhone	String
PrimaryEmail	String
SecondaryEmail	String
Fax	String
Modile	String
Password	String
Status	String
AccountID	String	This refers to an external ID not a SpiceCSM account ID.
CustFields	String	Comma Delimited list containing pairs of the form "ID\value" for custom data fields.

The return data must be presented in the following structure (XML) in order to be properly validated and parsed.

<?xml version="1.0" ?> <users>

 	<user status="Active" userkey=”jdoe" name="John%20Doe" email="johnd%40xyz%2Enet" phone="%28555%29%20555%2D5555" /> 

<user status="Active" userkey=”jdoe2" name="John%20Doe" email="johgnd%40xyz%2Enet" phone="%28555%29%20555%2D5555" /> <user … /> </users>

The search can return multiple records by adding <user /> child elements to the <users /> parent element. Should no matching records be found the parent element must be returned with no child elements.

When making a web call to load an account only one (currently) variable is passed.

Userkey

String

Refers to the account name.

The return data must be presented in the following XML structure in order to be properly validated and parsed.

<?xml version="1.0" encoding="UTF-8"?> <userdata>

  <user userkey="johnd" password="" status="Active" account="" />
  <contacts>
     <contact firstname="John" lastname="Doe" aone="123%20Fake%20St%2E" atwo="" city="Anywhere" region="ZZ" pc="123456" country="" pphone="%28555%29%20555%2D5555" sphone="%28555%29%20555%2D5555" pemail="johnd%40xyz%2Enet" semail="" mobile="" fax="" />
  </contacts>
  <fielddata>
     <field id="1" value="Anything" />
  </fielddata>

</userdata>

Multiple <contact /> child elements may exist for the <contacts /> parent element. Multiple <field /> elements may exist for the <fielddata /> parent element.

Account Update

The receiving web call will receive an HTTP Post containing a single variable labeled userXML.

This variable holds an XML string that can then be parsed to perform various tasks. The XML structure is identical to the account load structure, please refer to section Account Search/Load for further details.

Case Update

The receiving web call will receive an HTTP Post containing two variables labeled Userkey and caseXML.

The Userkey variable holds the account name while the caseXML variable holds an XML string that can then be parsed to perform various tasks.

The caseXML structure is:

<?xml version="1.0" ?>

  <tickets>
     <ticket cid=”6344” //the SpiceCSM parent case ID 
     id="7906"  //the SpiceCSM response ID
     tier="1" //the tier that the case is at
     date="1/27/06 1:27:51 PM" //date and time stamp of response creation
     status="In Progress" //current case status
     sid="2" //case status numeric ID
     issue="Browsing" //current case issue
     agent="Doe, John" //agent that entered the response
     aname="" //agent assigned to the case
     journal="13:28:41 - adding a second ticket for case dump testing " //journal entry text for the response
     email="" //e-mail text of the response
     article="" //knowledge base article text of the response
     treepath="" //process flow text of the response
     events="" //scheduled events for the case

/> </tickets>

API

SpiceCSM has at it's core a full low level API. This API is built using JSON RPC and allows for the direct manipulation of data in SpiceCSM.

This API can be used in many ways. Some examples of API usage would be creating a custom support portal, creating a real-time bidirectional integration with third party applications, or creating a custom plugin/module for SpiceCSM.

The API documentation can be found either in /spiceinstall/docs/api_client/ for Community and Enterprise installs or on the web at http://demo.spicecsm.com/docs/api_client/ .

Telephony Screen Pop/Integration

SpiceCSM comes with the ability to integrate with third party telephony solutions. It is required that the telephony solution have the ability to 'push' a web page with the call.

This integration will 'pop' a browser window/tab and display the greeting script to the agent. At the same time, the appropriate brand will be automatically selected in SpiceCSM (NOTE: this feature is not available in the Community edition as only a single brand is allowed.) In addition, optional variables can be passed for further integration options.

The URL that is used is /spiceinstall/integrations/telephony/telephonypop.php .

Al variables are passed as GET parameters.

Required Variables

There are two variables that are required for this integration to work:

  company - This is the ID of the company the call is for (this value is always 1 for Community edition).
  brand - This is the ID of the brand the call is for (this value is always 1 for Community edition).

Optional Variables

These variables are optional passed and can change the actions of the integration:

  callid - The unique ID of the call from the telephony system. This ID is recorded with the case/response for data mapping.
  ani - The caller ID of the caller. If this variable is passed SpiceCSM will search the database to try and match the number with an account. If an account can be matched, the system will automatically load the account.
  caseid - A case ID entered by the caller (via IVR). If this variable is passed SpiceCSM will search for a match and if found automatically load the account/case.