Overview

Vivantio's webhooks and web methods are a powerful feature which can be used to integrate Vivantio with other applications with minimal programming knowledge. Webhooks send data from Vivantio to an external system and Web Methods receive data from external systems to create or update tickets using the information. 

In the example below we have created a Webhook available to our front line worker role. When certain ticket conditions are met, the technician can select a button to Send to Client to raise a ticket in an external system.

Vivantio can request customised additional information from the technician at this point, as shown in the green box below. 

The above stages can be also be automated using trigger rules acting on ticket conditions.

When Vivantio receives a response from the external system it records the reference number and ebonding status in a read only custom form. Here we are collecting both the external ticket id (the friendly number for communications with the client) and the external id (which are used by the Webhook to locate the correct ticket). The final field we are using to control the status of the bonding. Web Methods receiving information have filters which ensure they will not be fired if the Active Bond is set to No. 

Subsequent updates will automatically trigger Webhooks to send the information to the receiving system. Web Methods in Vivantio will likewise add any updates sent automatically from the customer to the ticket. If the customer closes, merges or deletes the ticket we have a Web Method which resolves the ticket and changes the Active Bond field to No so that no further updates are applied to the ticket.  

Vivantio advise keeping the data sets you send and receive minimal and avoid field mappings as much as possible. This minimises the risk of system changes, such as new categories, adversely impacting your integration.

Setting up and testing new integrations 

Initial set up and testing are best done from a separate sandbox system, this is not essential but reduces the risk of errors impacting a live system. Talk to your account manager if you would like to discuss getting a Vivantio sandbox system set up. Another alternative is to set up a Test ticket area only visible to Vivantio admins. 

If you are integrating with a system not owned by your company make sure all those involved know what will be required to set up and maintain the integrations, (Webhooks for all the data they wish to send and Web methods for all the data they need to receive). We have a template attached to this article to help you plan this. 

Make sure you manage your processes carefully after integration, for example deleting, promoting or merging the e-bonded tickets in either system may break the integration if you don't have suitable safeguards in place. Likewise if the Priorities change in the external system and they are mapped to your Webmethod, it will no longer work.  

Example: Integration with an external ITSM application

One of the most common examples of an integration set up with web hooks and webmethods is integrating to third party ticketing systems so that you can communicate with each other directly. For example, maybe when you assign a ticket to a third party you would like to be able to create a ticket in that third parties application with all the details of the issue. When the third party updates or resolves the ticket, you want to see that information fed back to Vivantio. This works well when you have clients that you work with on a frequent basis. 

For full integration Vivantio will need four web hooks:

• Vivantio to send data to a third party system to trigger creation of a ticket
• Vivantio to update a ticket in the third party system
• Vivantio to close/resolve a ticket in a third party system and break the ebond
• Vivantio to update the ticket on deletion and break the ebond

And four Webmethods:

• Vivantio to create new ticket in response to data sent from third party
• Vivantio to update a ticket in response to data sent from a third party
• Vivantio to close/resolve or break the bond with a third party ticket in response to data.
• Vivantio to update ticket and remove ebond in response to ticket deletion

Things to consider when sending data from Vivantio

• What fields need to be sent to the external system to create a ticket? E.g. Title, Description, Priority, ticket id, ticket display id 
• When and how should data be sent? This can be done manually by a technician or automatically when certain conditions are met.
• What data do you need in return, typically you will want to update a custom form with read only fields for the ticket reference and bonding status. 
• What fields need to be sent to the external system? E.g. do you want to send notes only or do you need to communicate status or priority changes. Remember simple is best, the more information you exchange the greater the risk of the integration breaking due to system changes.
• How will you ensure the correct ticket is updated? You will need to communicate the ticket details based on the receiving system requirement, this might mean adding an expression to the request url to make it dynamic e.g. https://externalsystemurl/{{ticket.thirdparty.sysid}}
• When should the bond be broken and what actions should be taken at that time, for example when the ticket is closed you might want to send an update to the external system and break the bond. 
• Vivantio can use the following HTTP methods to send data: POST, GET, PUT, DELETE, PATCH (we typically use POST to send, PUT or PATCH to update and close)
• Vivantio can use the following requests content types to send data: json, xml, json-patch_json (we typically use JSON)

Things to consider when receiving data to Vivantio

• What fields does Vivantio need to create a ticket? What is mandatory in the ticket you are creating, what do you need from the customer and what can you automate?
• What data should Vivantio send in response? The ticket ID is essential for e-bonding but other data might be useful, for example the ticket display ID
• How will the sending system Authenticate against Vivantio. Do you need an extra license or will access key authentication be better?
• What HTTP methods will the sending system use to create, update and close tickets?
• What Request Content Type will the sending system be using?

Vivantio have a template which can help you think about and prepare for your integration, see the attached document.

Reviewed: 21 April 2022