Overview

If you want to connect Vivantio to an external tool that isn’t supported out-of-the-box, Webhooks and Web Methods are the first point of call. Rather than developing custom middleware that uses the API, Webhooks and Web Methods allow you to set up both ingoing and outgoing data transfer between Vivantio and the system of your choice, without writing any code or deploying additional applications. An overview of this and other integrations in Vivantio can be found at the bottom of this article. 

Web Methods support data coming into Vivantio from external systems. You can set up a Web Method to accept data in the format your other system is capable of sending and use Vivantio to manipulate or extract that data as required.

Before you start building a web method you will need the following information:

• What data is going to be received from where and when?
• How should it be processed (e.g. should it create a new ticket or update an existing ticket)
• What data should be returned in response (e.g. ticket display ID)?
• How will the external system authenticate against Vivantio?

Admin > Integration & API > Web Methods

Creating the request url

Click on the Add button to create a new Web Method. You will need to do this early in the process of setting up the integration so that you can supply the request url details for the Web Method in the sending external system.

Basic Details Tab

Access Key Authentication. Decide how you would like the web method from the sending system to authenticate:

* Please check with Vivantio Support to ensure your API account has been enabled for use with Webmethods

Start IP: and End IP: these options are only presented if Access Key Auth is ticked. Vivantio recommend you define these ranges to increase security. 
HTTP Method: Select the request method that the Web Hook will be using.

• GET – if the system you are sending to cannot use post, use this. When using GET data transferred in the URL will not be encrypted so don’t send sensitive data. 
• POST – used to send data to create or update a ticket, data in sent in the request body. 

Request content type: select the type of content that you expect to receive from the external system.

• Application/xml – extensible markup language 
• Application/json – Javascript object notation, script is more lightweight and intuitive than xml
• Application/x-www-form- urlencoded – url encoded form. If you are putting text values into the Request URL, and the text values are likely to contain special characters – such as & or ? – you should check the Encode URL Parameters box to ensure they get correctly encoded before the request is sent (for example, & characters will be encoded to %26)

Once the Basic Details have been completed click the Save button to generate the request url. You will need to provide this to the web method in your external system. 

When you have the details of the parameters that the external system will be sending, update the Web Method by selecting the appropriate item and clicking Edit. 

Parameters Tab

You can choose to set up parameters although this is often not required as they will be provided by the incoming request. If you want to take different actions based on the value you are receiving then you will need to map the parameters here.

Name: The name you choose for your parameter

Source Type: Is this field provided in the incoming Request Body, Query String or HTTP header

Source Path: What is the path of the data which you are receiving, e.g. title or details.title

Default Value: If no value is received you can add a default value here e.g. No title received.

How you set up the parameters varies based on the content type of the request.

XML

XML parameters can be extracted using XPath. There are many great resources available on XPath, such as the tutorial at W3 Schools.

JSON

To extract values from a JSON request, you can use simple ‘.’ notation as though you were accessing the object in JavaScript. For example, if your incoming JSON looks like:
{
                “someObject”:  {
                                “someProperty”: “someValue”
                }
}
You can enter ‘someObject.someProperty’ to get to the value ‘someValue’.

You can use square brackets to access properties in arrays, for example in the following JSON:
{
                “someObject”:  [{
                                “someProperty”: “someValue1”
                }, {
                                “someProperty”: “someValue2”
                }, {
                                “someProperty”: “someValue3”
                }]
}
You can enter ‘someObject[1].someProperty’ to get to the value ‘someValue2’.

If your JSON includes field names with spaces in, then you should use double quotes around the field name. For example:
{
                “someObject”:  {
                                “some Property”: “someValue”
                }
}

You can enter ‘someObject.”some Property”’ to get to the value ‘someValue2’.

Actions tab

Click the Add button and choose what type of ticket you would like to create or update when the web method is fired. You can add multiple actions here, for example you may choose to create tickets with different priorities depending on a value you receive in the parameters you have defined. 

Select appropriate Create or Update option.

Conditions

Select the appropriate conditions, for example, maybe if the value of Type is Computer you want to create a service request, for all other values you want to create an incident.

New Record Details tab (for Creating a new ticket)

Set up the ticket details as required, you should map all your mandatory fields at this point.

Type values which you want to set internally, for example, we want the Category set to Hardware for all these tickets, so we have typed in our pre-existing category value.

To populate parameters with fields you have received use the syntax {{parametername}}, for example we have mapped the callers name as the parameter we are receiving from the Webhook. 

We also want to add the description. If this is being sent as html make sure you tick the Treat Description as HTML box and then add the parameter being sent.

Important: Any parameters which contain html formatting must be added to this field if you want the formatting to be displayed.

Finally, we can populate any custom forms and fields by clicking on the + button under Custom Forms and selecting the appropriate Form and Field and adding a our values as described above. When you first create a ticket this will probably include the integration details such as the Ticket ID of the sending system and an indication that the ticket is currently e-bonded. 

Records to Update Tab - (for Updating Existing Ticket)

Use this to add the conditions that must be met for a ticket to be updated. For example, we only want to update the ticket where the Ticket ID matches the ID being sent by the external Webhook and the e-bonding is currently active.

Important: We recommend using the Ticket ID and not the Display ID to match records for maximum efficiency.

Actions tab - (for Updating Existing Tickets)

There are lots of options here, as discussed below. Reference any parameters with double brace brackets {{parametername}} as described above:

Change the Owner - reassign the ticket based on received parameters

Change the Status - update the status based on received parameters - for example when an update is received you might want to change the status from Awaiting Customer to Open or when you get notification that the ticket in the sending system is closed or deleted you might want to change the status to Resolved. 

Change the Priority - update the Priority based on received parameters

Add Note - add a Note to the history based on received parameters - one of the most commonly used actions in Webmethods

Send Email - send an email based on received parameters

Close Ticket - Close a ticket based on received parameters

Update Title and Description

Update mailbox address

Add/Update Custom Form - update a custom form based on received parameters - for example if you recieve notification that the ticket in the sending system is closed or deleted you may want to change the Active Bond field to No to prevent further updates being sent from your system.  

Click Save to save the action. 

Response tab

Use this tab to select the information you are going to return to the sending system. In the example below we are returning both the ticket id (for future ebonding) and the ticket display ID (for the technicians reference). 

Response type: Content - select the response content type (we are using application/json) and the response template (we are returning the values for the Ticket ID as "ticketid" and the Ticket Display ID as "ticketref". The expressions refer to values on the new/updated ticket. 

Response type: Redirect - to create a template url to return values to the sending system e.g. http://your.web.site/ ?ticketid={{ticket.displayid}}

Further information regarding REST API's can be found in Swagger

Reviewed: 28 March 2023