Telephone

+44 (0) 207 624 4991

› Tel

iCasework is able to share customer and case information with your chosen CRM system through interface points made available at each stage of the case capture and submission process.

Each interface point allows for information to be pulled from or pushed back to the CRM system so that a CRM record of each customer interaction carried out through iCasework is created and kept synchronised between the two systems. As a form is launched in iCasework, customer details can be retrieved from the CRM system; on submission, form details case can be sent back to the CRM system to create a case record; as case-work is undertaken, any status changes made can be shared between the two systems.

Each interface point expects an HTTP resource or REST web service to which input information will be posted and output information received in response. The content and format of the information passed will vary depending on the interface point in question. The CRM integration wizard found in the Administration menu allows the HTTP resource for each interface point to be configured. If required, XSL style-sheets to manipulate the data sent to, or received from, each resource can also be configured through this wizard.

If the CRM system provides interfaces which expect communication in forms other than an HTTP post, then an adapter must be used between the iCasework interface point and the CRM interface. For example, iCasework comes pre-installed with an adapter that can invoke SOAP web-services using information HTTP posted to it by an interface point.

Capturing a case

There are three approaches to capturing case details when using iCasework in conjunction with a CRM system:

The first would be to record all customer and case details in the CRM system and then have the CRM submit those details to iCasework via the createcase REST web-service (as defined in our REST API).

The second would be to use a hyperlink from within the CRM to launch the iCasework form and pass in customer details as URL parameters (as described in the section on URL Linking).

The third option is to use the CRM system as an external customer database within iCasework, so that searching for a customer on the iCasework Find Customer screen will search for and retrieve customer details from CRM, a case can then be recorded against that customer using the standard iCasework form. When a customer is selected from the search screen, a iCasework customer record is created, or if the customer has been used before in iCasework their existing record updated, using the details retrieved from CRM.

Note that it is quite possible to utilise the third option together with the first or second option.

In order to implement option three, the CRM system must provide a resource which can accept as input the search terms entered on the iCasework Find Customer screen and will return customer details in an XML format in response. To achieve this, in the CRM integration wizard, the Customer search URL should be configured to point at the resource to which the search request should be submitted.

In order to send the search terms entered by the user through to the HTTP resource configured, placeholders should be used to indicate where in the Customer search URL the search terms should be included.

A placeholder is simply the name of one of the search fields made available on the Find Customer screen, when a user searches for a customer, the placeholder in the URL is replaced with the actual value the user typed in that field on the Find Customer screen.

For example, if the CRM HTTP resource resides at

http://crm/search

and takes in the customer surname as a parameter called ‘surname’, the Customer search URL would be configured to point at

http://crm/search?surname=$$name$$

If the user then typed in the name ‘Jones’ in the Surname field of the Find Customer screen, the search would be submitted to the CRM resource by invoking the URL:

http://crm/search?surname=Jones

Each field that can be searched on through the iCasework Find Customer screen can be included in the Find Customer URL using the following place-holder strings:

PLACEHOLDER VALUE TAKEN FROM FIND CUSTOMER SCREEN FIELD
$$ref$$ Reference
$$name$$ Surname
$$forename$$ First name
$$phone$$ Phone
$$email$$ Email
$$postcode$$ Postcode
$$address$$ Address

iCasework requires that the customer details returned by the search resource are in the standard iCasework customer XML format. If the search resource does not automatically output in this format, the CRM integration wizard allows a Customer search output style-sheet to be configured that will be used to transform the data returned into the required format.

Submitting a case

The second interface point that should be configured to link iCasework with your chosen CRM system is used on submission of a new case in iCasework Case details are sent to the CRM system to create a corresponding case record in CRM linked to the record in iCasework.

In order to use this interface point the CRM must provide a resource which accepts as input any or all details of the case submitted and will respond with an indication of whether or not the case record was successfully created in CRM and, optionally, with the reference number of the case record created in CRM. If the CRM reference is returned, it will be stored against the case record in iCasework so that the two records are linked. It will also allow iCasework users to find a case by that reference.

In the CRM integration wizard, the Create case URL should be configured to point at the CRM resource to which case details will be submitted. The Create case input style-sheet option in the wizard allows an XSL style-sheet to be set that will be used, before submitting the case details to the Create case URL, to transform the case details from the iCasework form XML format into the format accepted by the CRM resource.

Case details are sent to the Create case resource in much the same way that search terms are sent to the Customer search resource, by using placeholder strings to mark where in the URL the details should be included. If the CRM resource accepts the case details as a single string or document (the format of which is determined by the Create case input style-sheet mentioned above), that string can be included in the Create case URL using the placeholder $$formXml$$. For example:

http://crm/create?case=$$formXml$$

When the case is submitted, the iCasework form XML will first be transformed using the Create case input style-sheet and then the result of that transformation will be included in the Create case URL in place of the $$formXml$$ placeholder and the URL invoked to send the case details to CRM.

If, however, the CRM resource requires that case details are sent as separate parameter values, individual pieces of information can be extracted from the form XML using references to named XML elements. For example,

if the CRM resource accepts the date of case creation as a parameter named ‘caseCreated’ and the reference number of the customer the case is related to as a parameter named ‘customerId’, then the Create case URL could be configured as something similar to:

http://crm/create?caseCreated=$$formXml.createdDate$$&customerReference=$$formXml.customerId$$

where ‘createDate’ and ‘customerReference’ refer to the names of XML elements holding the relevant values in the XML document containing the case details (after transformation by the Create case input style-sheet).

The response from the Create case URL is expected to contain a success/failure flag and the CRM case reference in the iCasework success XML format. The Create case output style-sheet can be set in the CRM integration wizard to transform the output of the CRM resource into this format if it is not already.

Synchronising case status

Once a case has been created in both iCasework and CRM, there are several ways of keeping both records up to date and in sync with each other. If case notes are added to the CRM record, the same notes can be made accessible in iCasework by submitting them to the addcasenotes REST web-service (see REST API). Additionally, CRM can link to the iCasework case progress page to make all details of the iCasework record available (see the documentation for URL Linking).

The third interface point allows changes in case status made through iCasework to be fed back to the CRM in order to keep the CRM record up to date with those actions taken. When any status changes take place on a iCasework case record that is known to be linked to an case record in an external CRM, this interface point will automatically invoke an HTTP resource to transmit those changes to the external record.

In order to use this interface point the CRM must provide a resource which accepts as input some or all of the status details listed below and will respond with an indication of whether the update request has been received successfully.

In the CRM integration wizard, the Update status URL should be configured to point at the resource to which status details will be submitted. As with previous interface points, status information is passed into the CRM resource by means of place-holders in the configured URL. Before the Update status URL is invoked for a particular case, the place-holders are replaced with live status information. The following status details can be passed to the CRM resource.

PLACEHOLDER MEANING
$$reference$$ The iCasework! case reference
$$externalId$$ The reference number of the CRM case record
$$status$$ The current case status
$$today$$ The current date in the iCasework! date format
$$todayXml$$ The current date in the XML date format

The response from the Update status URL is expected to contain a success/failure flag in the iCasework success XML format. The Update status output style-sheet can be configured through the CRM integration wizard to transform the response into this format if it is not already.

Closing the CRM case

Once a case has been closed (or re-opened) in iCasework, the related case in the CRM can also be closed (or re-opened). To implement this interface point the CRM must provide a resource which accepts as input some or all of the status details listed below and will respond with an indication of whether the update request has been received successfully.

In the CRM integration wizard, the Close Case URL should be configured to point at the resource to which the closure will be submitted. As with previous interface points, information is passed into the CRM resource by means of placeholders in the configured URL. Before the Close Case URL is invoked for a particular case, the placeholders are replaced with live case information. The following details can be passed to the CRM resource.

PLACEHOLDER MEANING
$$reference$$ The iCasework! case reference
$$externalId$$ The reference number of the CRM case record
$$open$$ True or false
$$today$$ The current date in the iCasework! date format
$$todayXml$$ The current date in the XML date format

External customer database example

In the following example, we will show how the interface points described above can be used to link a iCasework system to a CRM account on Salesforce.com. As explained, the interface points in iCasework are designed to post information as parameters to HTTP resources.

Salesforce CRM provides a SOAP web-service interface in its Partner API. Therefore, in order for iCasework to interact with the Salesforce Partner API, a preconfigured adapter is provided to enable HTTP posting.

The Salesforce adapter is an HTTP resource published on iCasework called callSalesforce. callSalesforce deals with any complexities of the Partner API such as the Salesforce session login process. Salesforce credentials are required to authenticate each API request, so each time the callSalesforce adapter is invoked, those credentials must be included as parameters, along with two other pieces of configuration information. While example URLs shown below leave out these parameters for the sake of simplicity, it is implied that these values are always included on any URL pointed at the callSalesforce adapter. Those required parameters are as follows:

Parameter Usage
username The username with which to access a Salesforce CRM account, usually in the form of an email address.
password The password for the above Salesforce CRM account.
loginMessageUrl The URL used to connect to Salesforce. Since this varies per account it must be configured. See below for instructions of how to find this URL.
timeoutMinutes The length of time that a Salesforce login session is valid. Again, this can be varied per Salesforce account so must be configured. See below for instructions of how to find this value in Salesforce.

So each callSalesforce URL used, as well as the parameters included specific to the web-service call being made must also include these parameters. For example:

…&username=user@email.com&password=abC123&loginMessageUrl=

http%3A%2F%2Fwww.salesforce.com%2Fservices%2FSoap%2Fu%2F18.0&timeoutMinutes=30

Interface point one

The first interface point we can configure is in linking the iCasework Find Customer screen to the Query operation of the Salesforce Partner API web-service, allowing us to carry out a customer search from iCasework against the Salesforce contact records. To do so, we would open the iCasework CRM integration wizard from the administration menu and set the Customer search URL to the following value (remembering the additional parameters detailed above that are left out here for clarity)

…/salesforce.callSalesforce?type=search&includeAccounts=y&id=$$ref$$&name=$$name$$&foreName=

$$forename$$&phone=$$phone$$&email=$$email$$&postcode=$$postcode$$

&address=$$address$$

This will pass any values entered by the user in the reference, surname, first name, phone, email, postcode or address fields of the Find Customer screen through to the callSalesforce adapter, which will in turn submit them to the Salesforce web-services to search for contact records matching the search terms given. The Address id field is not used since there is no equivalent field for Salesforce contact records.

The callSalesforce adapter has been built to return any search response from Salesforce into the iCasework customer XML format so it is not necessary to configure a Customer search output style-sheet in the CRM integration wizard. This setting alone will allow Salesforce contact records to be used as customer records in iCasework

Interface point two

The second interface point, sending out details of new cases submitted through iCasework, can be connected to the Create operation of the Salesforce web-service and used to create a new Case object in the Salesforce account.

To do so, we need to consider what case details Salesforce requires as input when creating a case and how those details can be taken from the iCasework form XML. Salesforce will not accept a single XML document of case details as input, we need to pull out individual values from the case XML and submit them as separate parameter values. To do this, in the CRM integration wizard we would set the Create case input style-sheet to an XSL style-sheet that would transform the iCasework form XML into a more simple structure such as the following:

<?xml version=”1.0″ encoding=”UTF-8″?>

<complaint>

<contactId>exampleContactId</contactId>

<subject>exampleCaseSubject</subject>

<description>exampleCaseDescription</description>

</complaint>

We could then use individual values from that XML structure in the callSalesforce resource that is configured in the Create case URL field of the CRM integration wizard, such as the following

…/salesforce.callSalesforce?type=createCase&contactId=$$formXml.contactId$$&subject= $$formXml.subject$$&description=$$formXml.description$$

As mentioned above, the callSalesforce adapter has been built to return any response information from Salesforce in the correct formats for iCasework to interpret, so it is not necessary to configure the Create case output style-sheet option in the CRM integration wizard.

Interface point three

The third interface point in iCasework, sending updated case status information, can be connected to the Update operation provided by the Salesforce web-services. To do so, open the CRM integration wizard and set the Update status URL to the following

../salesforce.callSalesforce?type=updateCase&caseId=$$externalId$$&status=$$status$$

The Salesforce web-service automatically set the date that the status update was made so it is not necessary to include any date information in the call. The callSalesforce adapter will return any response from Salesforce in to the correct iCasework format so neither is it necessary to set the Update status output style-sheet option.

Take the first step to doing a better job of case management

Our software combines the knowledge and skills of experts in case management and software design

We consult with our clients to ensure we fully understand the issues our software needs to address

Get user friendly, secure and compliant case management software to meet today’s challenges

Call now ›