Install and Configuration

Install

The integration is provided via a Resource Project which needs to be installed to your web application codebase. Once the library has been installed and deployed to your environment, its content should be imported via the icm-content folder generated in the custom share. No further steps are required to install the product at this time and it can now be configured ready for use.

Configuration

Using the standard getConfig End Point convention the product is able to retrieve all of its required configuration settings in one place. To set this up, you should find an "example" namespaced getConfig End Point under the Zendesk application name. Copy this End Point into a new Zendesk group under the applicable environmental name, for example:

config.dev.Zendesk.getConfig

The following settings can be set within the getConfig endpoint:

Field Mappings

A more complicated area of Zendesk is its way of handling "custom fields". These are arbitrary fields that allow for values to be set which can give Requests/Tickets more context. These fields are identified by an ID number, this means I could create a custom field, within Zendesk, called "Colour" which would be given the id of 12345. If I wanted to set that custom field when I create a request, let's say with the value "Red", then I would need to send `"12345": "Red"` to Zendesk. If I were to look at the created request, I should see that the field "Colour" has the value Red.

This is slightly tricky when interacting between systems as we will be given a list of custom field IDs which mean little without some sort of context. To make this more transparent, we've created a mapping utility so we can map IDs to friendlier names via configuration End Points. Following the pattern above, we now have the following End Point namespace pattern:

"config.<environment>.Zendesk.<mapName>.getConfig"

This allows the environment to define a number of mapping types, for each "mapName" you require, as these could be different per request Type.

Inside this config End Point we return an array of objects. Each object is constructed as follows:

{
    "id": 45245349,
    "values": ["typeOfLicence"]
}

The id is set in Zendesk. The values array allows us to give one, or more, friendly names for this field. In this instance, we will map the value of anything called typeOfLicence to that id when it is passed to Zendesk. The reason multiple values can be set is because there is a chance custom field is made up of multiple individual values, an Address block for example might be address line 1, line 2, postcode etc.

Field map selection and custom field values are parameters that are sent into the request end points which you will see within the relevant article for that area. This is part of the payload to a request from a form which would select a config called "scaffoldingAndHoarding" and attempt to set the value of "typeOfLicence", which we have set above, to the value "Test"

{
    "fieldMapName": "scaffoldingAndHoarding",
    "custom_fields": [{
        "key": "typeOfLicence",
        "value": "Test"
    }]
}