INTRODUCTION

In every company, it is crucial to have effective, efficient communication, such as the ability to alert your team about new urgent issues, or let a customer know you’ve responded. Thanks to API integration and webhooks, Vivantio makes sending messages to applications such as Microsoft Teams from your department easy. If your organisation uses Slack instead, you can find a tutorial on sending out communication from Slack here.

This tutorial will show you how to configure this in Microsoft Teams and provides two examples of using notifications in the Vivantio platform. Please note that Microsoft Teams transitioned to a new webhook URL format to enhance security on January 11, 2021. If you've configured this integration prior to that date, there are new set-up instructions included at the end of this blog for Step 7.  

To connect Vivantio to Microsoft Teams, you’ll need:

1. Vivantio ITSM
2. Admin access to your Vivantio Instance
3. Permissions in MS Teams to create, update and remove connectors for the Team you wish to post to

CONFIGURATION IN MS TEAMS

Step 1:

Begin by logging into Microsoft Teams (MS Teams). You will then go to:

Your teams » Click on the channel within MS Teams you want to send notifications to » More options » Connectors

Step 2:

If it’s not already installed for the selected MS Teams group, add and install Incoming Webhook. Otherwise, configure Incoming Webhook.

Step 3:

Enter a name for your webhook (this will be the username associated with messages sent into MS Teams), upload a custom image if desired, and select Create.

Step 4:

Next, copy the URL that is created, circled in red below. This will later be used to set up the webhook in Vivantio.

CONFIGURATION IN VIVANTIO

Step 5:

Log into Vivantio, open the Admin Area. Navigate to:

Integration & API » Webhooks » Add Webhooks

Then select the ticket type you want the webhook to be available for.

Step 6:

Enter a name for your webhook.

Step 7:

Next, navigate to the Basic Details tab and enter the following information (please refer to the Update at the end of this blog if you configured this integration prior to January 11, 2021):

• Request URL: Paste here the URL produced when you configured the incoming webhook in MS Teams.
• HTTP Method: POST
• Response Content Type: text/html

Step 8:

This next step, filling out the parameters tab, is optional. Set up parameters for the webhook by selecting Add. These are either values the technician will be prompted to complete, or populated automatically from the ticket. In this example, we have created a multi-line text field for a technician to enter the message that they wish to send into MS Teams.

Step 9:

Now, fill out the Request Body tab.

For the Request Content Type field, select application/json. The Body Template will contain the information you wish to send in MS Teams notification, such as specific text, details from the ticket or a webhook parameter. Screenshots from the Request Body of two example webhooks are given below.

Example 1:

A notification message sent into Teams that utilizes the webhook Parameter we created in the previous step.

{"text": ""}

Example 2:

A notification sent into Teams that includes details from the ticket. In this case, we use fields from the ticket. The “\n\n” signifies a line break. Note that Steps 1 through 8 were followed to create another webhook “Teams – High Priority Ticket.” Once the Request Body is filled in, click save.

{"Title": "High Priority Ticket Logged",
"text": "Ticket Details: \n\n ID: {{ticket.displayid}} \n\n Subject: {{ticket.title}}
\n\n Caller Name: {{ticket.callername}}"}

Step 10:

The last step before we can use our new webhook is to configure its roles. By default, there will be no roles assigned to the webhook. To update the roles, select the webhook and click Roles. Drag the roles you want the webhook available for into Current Roles.

Now let’s put the webhooks we set up into action!

You can use your webhook to send ad hoc notifications into MS Teams directly from a ticket window or you can execute your webhook through Trigger Rules. Two examples are given below:

Example 3:

An ad hoc message sent into MS Teams from a Vivantio ticket window

Actions » MS Teams Notification

The technician is prompted to fill in the “Notification to Teams” parameter we set up in the webhook. Recall that this webhook was configured so that the text entered here will be sent into MS Teams.

Press OK and voila! This message is sent into MS Teams.

Example 4:

Sending a notification to an IT team’s channel in MS Teams any time a high priority ticket is logged.

In this case, you can set up a trigger rule to automatically execute the webhook when a high priority ticket is logged. Go to:

Admin area » System Areas » Select the ticket type you created the Webhook for
» Business Rules » Trigger Rules

To add a trigger rule, click Add, then:

• Enter a Rule Name and select when the condition is to be executed, either when the ticket first meets the condition (for example, if you just want people to know the ticket was created) or when the matching ticket is updated (if you want everyone to see all updates to the ticket).

• Enter the condition(s) for the trigger. In this example, the trigger rule condition is for tickets with the priority name equal to “high.”

For the trigger rule “Actions” select

Webhooks » Webhook you want to fire; in this case, we chose

Teams – High Priority Ticket » Save

Once the trigger rule is set up, the “Teams – High Priority Ticket Webhook” will automatically send a notification with ticket details into MS Teams any time a “High Priority” ticket is logged.

CONCLUSION

There you have it! Now you can easily communicate to any team in MS Teams directly from Vivantio.

Update (as of January 11, 2021):

This step is for anyone who configured this integration prior to January 11, 2021. On this date, Microsoft Teams transitioned to a new webhook URL format to enhance security. You will need to update your webhook URL from within Microsoft Teams and copy the new URL into the webhook within Vivantio (Step 7).

To update your webhook URL within Teams, navigate to your webhook:

Your Teams >> Click on the channel your webhook is configured on >> More options >> Connectors

Select Configured. Find your webhook and select Manage.

If your webhook URL needs to be updated, an "Update URL" button will appear to the right of the URL. Select Update URL.

Once your URL is updated, it will say "URL is up-to-date" below the URL. Copy the new URL into your webhook within Vivantio (Step 7).

Azure DevOps–formerly named Visual Studio Team Foundation Server (TFS)–is a Microsoft product that allows developers to plan work, collaborate on code development and build and deploy applications. If your development teams are using Azure DevOps, integrating it with your service desk software can provide the following benefits:

• Create bugs directly from Incidents or Tickets
• Create Product Backlog Items from Service Requests or Change Requests

Vivantio includes an out-of-the-box, two-way integration with Azure DevOps, making it simple to have open communication and visibility between your support and development teams.

Our Azure DevOps integration helps you streamline your processes and keep everyone informed of what is going on, regardless of which tool they work in day-to-day, so there's no need for your developers to log into Vivantio, and no more phone calls to the development team to check on the status of bugs!

This tutorial will show you how to configure the integration and provides an example of creating a Work Item in Azure DevOps directly from Vivantio.

To connect Vivantio to Azure DevOps, you’ll need:

1. Vivantio ITSM
2. Admin access to your Vivantio Instance
3. Credentials to a user account for Vivantio in Azure DevOps
   

CONFIGURATION IN VIVANTIO

Step 1:

Log into Vivantio, open the Admin Area. Navigate to:

Integration & API >> TFS

Fill in your Azure DevOps login credentials:

• Version: Azure DevOps
• Organization Name: Enter your organization name. This will be used in your API URL, for example: https://dev.azure.com/OrganizationName/
• Username: The username for the Vivantio user account in Azure DevOps
• Password: The Personal Access Token for the Vivantio user account in Azure DevOps. For details on creating a Personal Access Token, see the Microsoft Documentation here.

The bottom of the screen will update to show a couple of different URLs: the Work Item Alert URL and the Service Hook URL. You will use the Service Hook URL to set up Azure DevOps to send information back into Vivantio.

Step 2:

Select IP Range in the top left corner of the screen and configure the IP Range for Vivantio to accept requests from.

Step 3:

Configure your ticket to Work Item Mapping settings. This allows you to control which types of Vivantio Tickets can be mapped to which types of Azure DevOps Work Items so that the correct type of information can be transferred to the correct type of records. Any number of necessary ticket-to-work item mappings can be configured.

Navigate to the Ticket to Work Item Mapping tab and select Add.

On the Basic Details tab, give the mapping a name and fill in the following information:

• Project Collection: The Project in Azure DevOps (If you’re using the hosted version of Azure DevOps, there will normally only be one option available here)
• Project: The Project in Azure DevOps
• Work Item Type: The Work Item Type in Azure DevOps
• Ticket Type: The type of ticket within Vivantio that you want to create the Work Item from

Step 4:

Navigate to the Sync Options tab. Here you can configure the settings relating to the sync of data from Vivantio to Azure DevOps. (Note that this option does not force Azure DevOps to update Vivantio–that is configured within Azure DevOps itself). You have the option to fill in the following fields:

• Link Work Item to Ticket: Checking this box will create a link to the Vivantio ticket from within the Azure DevOps ticket
• Action Sync: Selecting “All” or “Non Private” will automatically sync all (or only non-private) actions made in Vivantio to the “Discussion” section within the Work Item in Azure DevOps
• Attachment Sync: Selecting “All” or “Non Private” will automatically sync all (or only non-private) attachments added in the Vivantio ticket to the “Attachments” section within the Work Item in Azure DevOps

Step 5:

Select the Field Mappings tab and configure any additional field mappings. As standard, Vivantio will populate the Work Item Title and Description. If you want to add additional mappings, e.g., for custom fields, you can do so here. You can also choose to override the default mappings for Title and Description.

In the example below, we chose to map several custom fields from Vivantio to Azure DevOps.

After choosing the appropriate options, hit Save, and you’re ready to start creating Azure DevOps Work Items directly from Vivantio.

CREATING A NEW WORK ITEM FROM VIVANTIO

When viewing a Ticket in Vivantio, under the Actions menu item, you’ll see the option to “Create New TSF Work Item.”

Selecting Create New TFS Work Item will open a pop-up window where you can select the Work Item Type. Any mappings created for the ticket type, using steps 3 through 5, will appear as options.Selecting OK will cause a “TFS” Form to appear in the Vivantio Ticket Window and a Work Item to be created in Azure DevOps.

The TFS form provides a direct link to the Work Item in Azure DevOps and provides the technician with the options to unlink the Vivantio ticket from the DevOps Work Item and to send ad-hoc comments and attachments to DevOps, which can be useful if you didn’t choose to automatically sync actions.

Clicking on the link to the Work Item in DevOps, we can see that the Work Item was created and the mapped fields were passed from the Vivantio Ticket to the Work Item.

CONFIGURATION IN AZURE DEVOPS

Getting Information Back From Azure DevOps

Configurations can be made in Azure DevOps to automatically send information from DevOps into Vivantio. This is done using the Service Hook that was create in Step 1.

Step 6:

To configure the Service Hook in Azure DevOps, navigate to Service Hooks within Project Settings in Azure DevOps (Microsoft’s documentation on Service Hooks can be found here). On the first page of the Create Service Hook wizard, you’ll choose the Webhooks option and select Next:

On the next page of the wizard, you’ll choose the type of event the Service Hook triggers on. Vivantio currently supports “Work Item Commented On” and “Work Item Updated.” Enter any filters you want for the area or work item type.

Select and configure the action to perform with the service hook. Under “URL,” paste your service hook from Step 1. Scroll to the bottom of the page and select “[Latest]” for Resource Version.

Now when we comment on Work Items in Azure DevOps...

...the comment is automatically added to the linked Ticket’s history in Vivantio:

Additional configurations can be made in Azure DevOps using Webhooks to automatically update fields in Vivantio based on updates in Azure DevOps.

If you’re using Vivantio and Azure DevOps and you don’t have them integrated yet, give it a try and see how it helps improve communications between your service desk and your development team.

INTRODUCTION

In every company, it’s crucial to have effective, efficient communication, such as the ability to alert your team about new urgent issues, or let a customer know you’ve responded to their request. Thanks to API integration and webhooks, Vivantio makes sending messages to applications such as Slack from your department easy.

This tutorial will show you how to configure this in Slack and provides two examples of using notifications in the Vivantio platform. If your company is using Microsoft Teams, you can find the tutorial here.

To connect Vivantio to Slack, you’ll need:

1. Vivantio ITSM
2. Admin access to your Vivantio Instance

CONFIGURATION IN SLACK

Step 1:

Begin by logging into Slack. You will then go to:

api.slack.com/apps » Create New App

• Fill in the App Name. This is the username that notifications from Vivantio will be posted in Slack from.
• Choose a Development Slack Workspace, which is where you will manage your app. If you don’t already have a Development Slack Workspace, you can create one at slack.com/create#email
• Select Create App

Step 2:

Your new app will appear under Your Apps on the api.slack.com/apps page. Select your app. This will bring you to a new page. Navigate to:

Add features and functionality » Incoming Webhooks » Activate Incoming Webhooks: On » Add New Webhook to Workspace

Step 3:

Choose the channel you want to post to in Slack. Select Allow.

Step 4:

Next, copy the webhook URL that is created, circled in red below. This will later be used to set up the webhook in Vivantio.

CONFIGURATION IN VIVANTIO

Step 5:

Log into Vivantio, open the Admin Area. Navigate to:

Integration & API » Webhooks » Add Webhooks

Then select the ticket type you want the webhook to be available for.

Step 6:

Enter a name for your webhook.

Step 7:

Next, navigate to the Basic Details tab and enter the following information:

• Request URL: Paste here the URL produced when you configured the incoming webhook in Slack.
• HTTP Method: POST
• Response Content Type: application/json

Step 8:

This next step, filling out the parameters tab, is optional. Set up parameters for the webhook by selecting Add. These are either values the technician will be prompted to complete, or populated automatically from the ticket. In this example, we have created a multi-line text field for a technician to enter the message that they wish to send into Slack.

Step 9:

Now, fill out the Request Body tab.

For the Request Content Type field, select application/json. The Body Template will contain the information you wish to send in Slack notification, such as specific text, details from the ticket or a webhook parameter. Screenshots from the Request Body tab of two example webhooks are given below.

Example 1:

A notification message sent into Slack that utilizes the webhook parameter we created in the previous step.

{"text": ""}

Example 2:

A notification sent into Slack that includes details from the ticket. In this case, we use fields from the ticket. The “\n\n” signifies a line break. Note that Steps 2 through 8 were followed to create another Webhook “Slack – High Priority Ticket.” Once the Request Body is filled in, click save.

{"text": "High Priority Ticket Logged – Ticket Details: \n\n ID: {{ticket.displayid}} \n\n Subject: {{ticket.title}} \n\n Caller Name: {{ticket.callername}}"}

Step 10:

The last step before we can use our new webhook is to configure its roles. By default, there will be no roles assigned to the webhook. To update the roles, select the webhook and click Roles. Drag the roles you want the webhook available for into Current Roles.

Now let’s put the webhooks we set up into action!

You can use your webhook to send ad hoc notifications into Slack directly from a ticket window or you can execute your webhook through Trigger Rules. Two examples are given below:

Example 3:

An ad hoc message sent into Slack from a Vivantio ticket window

Actions » Slack Notification

The technician is prompted to fill in the Notification to Slack parameter we set up in the Webhook. Recall that this webhook was configured so that the text entered here will be sent into Slack.

Press OK and voila! This message is sent into Slack.

Example 4:

Sending a notification to an IT team’s channel in Slack any time a high priority ticket is logged.

In this case, you can set up a trigger rule to automatically execute the Webhook when a high priority ticket is logged. Go to:

Admin area » System Areas » Select the ticket type you created the Webhook for » Business Rules » Trigger Rules

To add a Trigger Rule, click “Add,” then:

• • Enter a Rule Name and select when the condition is to be executed, either when the ticket first meets the condition (for example, if you just want people to know the ticket has been created) or when the matching ticket is updated (if you want everyone to see all updates to the ticket)
  • Enter the condition(s) for the trigger. In this example, the trigger rule condition is for tickets with the priority name equal to “high.”

For the trigger rule “actions,” select Webhooks » Webhook you want to fire; in this case, we chose

Slack – High Priority Ticket » Save

Once the trigger rule is set up, the “Slack – High Priority Ticket” Webhook will automatically send a notification with ticket details into Slack any time a “High Priority” ticket is logged.

CONCLUSION

There you have it! Now you can easily communicate to any team in Slack directly from Vivantio.

IT Service Requires More Than One Integration Tool

JIRA, Active Directory, and Beyond Trust (formally Bomgar) are a few examples of many third-party services and technology that can help your team by providing outsourced IT service. Using these tools in concert with each other is vital to getting the service data your team needs. So, when considering an ITSM platform, it is critical to understand the availability of integrations.

But what are the differences between the types of software integration tools out there? Here are the 4 major types of third-party integration methods available for service management software along with the pros and cons of each for your service team.

1. API Integration

Application Programming Interface (API) is the most common tool for connecting different applications for service management software. There are many different types of API that are either public, partner, or private. What they all have in common is how they enable interaction between applications. An API uses a common code language to specify functionality and set protocols. This gives your applications the ability to transfer data.

Pros:

• Highly Flexible: Even though you are dependent on the developer resources, specific data becomes highly flexible because the integration uses product code.
• App Changes Aren’t Disruptive: Service providers offer better functionality that goes uninterrupted since APIs are often limited in scope.
• Widely Available: As stated earlier, API is the most common tool for third-party integration. So, it will be unlikely that you run into a service that won’t offer API integration options.

Cons:

• Dependent on Vendor: Vendors are responsible for creating APIs. So, you are reliant on the vendor to create APIs for the specific type of information you are trying to pull.
• Code-Intensive: Because they are code-based, APIs need an understanding of programming languages to install.

2. Webhooks

Webhooks or HTTP callbacks are an alternative to API integration. They are both tools that link to a web application but have two key differences. For webhooks, implementation is often not code-based. They often have modules that are programmable within a web application. Instead of being request-based, webhooks are event-based. They only trigger when specific events occur within a third-party service.

Pros:

• Real-Time Data: Webhooks don’t use a request-based system. They allow your team to view data on a real-time scale.
• Supports Automation Efforts: Because data requests are event-based, you don’t have to set up poll timings to your data center. This can help streamline data flow and automation.

Cons:

• Limits Data Manipulation: A webhook requires the service to trigger a data transfer based on an update. In contrast to webhooks, APIs can list, create, edit, or delete an item without triggering a transfer.

3. ISC

Integration Services Component (ISC) lives on a local server unlike code-based integrations.  The ISC creates a bridge with on-premise tools such as directories, asset management tools, and BI tools without the need for file imports.

Pros:

• (Near) Out-of-the-Box Solution: The ISC immediately offers many data synchronization options you would likely use.
• Wider Range of Functionality: With an ISC, you have complete data access that you can do anything with.  Any data that you can access on the backend with your cloud service will be available.

Cons:

• Knowledge of Database Architecture Necessary: If you are unfamiliar with how your local database is set up, implementing an ISC will be challenging.
• Requires Access to the Backend of Your Applications: There will be many cases where backend access isn’t there for your team, so you won’t be able to use an ISC in those situations.

4. ORCHESTRATION

The most automated integration option is orchestrations. If you are not familiar with orchestrations, they refer to the process of automating multiple systems and services together. Teams will often use software configuration management tools such as PowerShell to build orchestrations. Software configuration management tools offer various methods such as snap-ins or hosting APIs to connect with applications to manage the automation workflow.

Pros:

• Full Automation: Automation across all processes.
• Manages Multiple Systems: Ability to manage the integrations of multiple systems collectively.

Cons:

• Code-Intensive: You need to have coding skills to manage your software configuration management tool.
• Labor-Intensive: Because the workflows are quite complex, the setup can be a drawn-out process. Also, any asset or process changes force you to check how it will affect your orchestrations.

Make sure you check what integration options your ITSM provider offers before you commit.  With Vivantio, you have several options including our rapid integration platform, FLEXBridge. 

Discover for yourself how Vivantio offers codeless integrations, customize ticket views, built-in CRM and much more. Schedule a free personalized demo to learn more.  

WHEN SHOULD I USE THE VIVANTIO API?

We’d encourage the use of Webhooks and Web Methods wherever possible for a number of reasons such as:

• You don’t need to write any code.
• They’re hosted within Vivantio so don’t need to be deployed separately.

But there are a number of situations where the API is the better or only choice. Let’s explain with two most common instances: Integrating with Legacy Systems and Developing Custom Applications.

CREATING THE WEB METHOD

To create a Web Method in Vivantio, log into the platform, open the Admin Area, and go to:

Integration & API » Web Methods

(If you don’t see Web Methods in this menu, please contact our support team.)

When you reach this screen, select the “Add” button. You’ll then get a dialog with a box for you to enter a name and a few sub tabs below to fill in. Submit a name and then move onto the first tab.

BASIC DETAILS

In this example, because we’re going for a simple form POST, we won’t be authenticating.

So, select Access Key Auth, and enter the IP range of the web server(s) that will host the form.

(Note: We’ve gone for 0.0.0.0 and 255.255.255.255 in our example. Don’t do that in practice!)

The other options on this tab are:

• HTTP Method
• Request Content Type

As this is a web form we’re dealing with, you will want to select ‘POST’ and ‘application/x-www-form-urlencoded’ respectively.

PARAMETERS

You can add as many parameters as you like, depending on how complicated you want your form to be.

In this example, we’ve kept it simple with:

• First Name
• Last Name
• Email Address
• Subject
• Description

They are all configured in the same way.

ACTIONS

In this example, we want to create a Ticket when the Web Method is called. So, on the Action tab, choose

Add » Create Incident

(Note: You can use whichever of your Ticket Types is more appropriate for the situation.)

After you’ve selected your Action, you will get a popup with two tabs: Conditions and New Record Details.

In this example, we want a Ticket to be created every time the Web Method is called. So, we will leave the Conditions tab empty and move onto New Record Details.

In this example, you can see we’re using to pass our parameter values into the Ticket Details.

You’ll also want to note though that we’ve put some literal values in for the Priority and Category. In our example, we want these set for every contact form submission, but we don’t want the user to choose them, so we’re specifying fixed values.

RESPONSE

When you’re setting up the Response, you can configure up to three options:

• Response Type – For this field, you have the choice between Content or Redirect. Content allows you to specify content to be returned to the user as part of the Response Body. Redirect let’s you send them to a specific website with a 302 redirect.
• Response Content Type – For this field, you have the choice between JSON, XML, or Text/HTML. This field is only available when you select the Content option for the Response Type field. It will inform the user of the Web Method which data type to expect in return.
• Response Template – This field allows you to enter the actual response you would like to send: either the content or the redirect URL. If your Web Method contains a “Create Ticket” action, you can use to refer to properties from the created ticket within the response template such as {{ticket.displayid}} to get the ID of the inserted ticket.

For our example, we’re going to set up a Content Response using the Content Type “Text/HTML” that shows a basic “Thank You” message and refers to the Ticket ID.

After you hit the “Save” button, you’ll be shown the unique URL for your Web Method.

CREATING THE CONTACT FORM

When creating the form, the things you need to know are:

• The form method should be “POST”.
• The form action should be the Web Method URL you noted earlier.
• When you’re setting the names of your form inputs, they should match the names of the parameters you added earlier.

Here’s a sample form below that is ready to use apart from the action URL on the form:

<!DOCTYPE html>

<html lang=”en”>

<head>

<meta charset=”utf-8″>

<meta http-equiv=”X-UA-Compatible” content=”IE=edge”>

<meta name=”viewport” content=”width=device-width, initial-scale=1″>

<title>HTML Form &raquo; Web Method Example</title>

<link href=”https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css” rel=”stylesheet”>

<!–[if lt IE 9]>

<script src=”https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js”></script>

<script src=”https://oss.maxcdn.com/respond/1.4.2/respond.min.js”></script>

<![endif]–>

</head>

<body>

<div class=”container”>

<div class=”row”>

<div class=”col-lg-6 col-offset-lg-3″>

<form method=”POST” action=”YOUR WEB METHOD URL HERE”>

<div class=”form-group”>

<label for=”firstname”>First Name</label>

<input type=”text” class=”form-control” id=”firstname” name=”firstname” />

</div>

<div class=”form-group”>

<label for=”lastname”>Last Name</label>

<input type=”text” class=”form-control” id=”lastname” name=”lastname” />

</div>

<div class=”form-group”>

<label for=”email”>Your Email Address</label>

<input type=”email” class=”form-control” id=”email” name=”email” />

</div>

<div class=”form-group”>

<label for=”subject”>What can we help with?</label>

<input type=”text” class=”form-control” id=”subject” name=”subject” />

</div>

<div class=”form-group”>

<label for=”description”>Any additional details?</label>

<textarea class=”form-control” id=”description” name=”description” rows=”10″>

(Note: You’ll note that we’ve referenced Bootstrap in this sample. You do not have to do that and can use whatever UI framework you like.)

Here’s what the sample form would look like in practice:

Using the code, you can publish the form to your website. After a user fills in and submits the form, a Ticket will be created via the Web Method. The user will then see the content configured on the Web Method Response.

Editorial Note: In September 2018, privileged access management (PAM) provider Bomgar acquired BeyondTrust and now operates under this name. We’ve since updated this article text to reflect that change.

BEYONDTRUST API

You can access the BeyondTrust API documentation here.

BASIC CONFIGURATION

There are three main steps required to configure everything in Vivantio:

1. Create a Custom Form to hold the BeyondTrust Session Details
2. Create an Email Template to send the session details to customer
3. Create the Webhook to allows the technician to create the session

CUSTOM FORM

Why do you need a Custom Form?

The “Generate Session” method in the BeyondTrust API gives us back a number of different values and we will need these to be available in Vivantio.

The main value we need is the “key_url” field, but you can also set up fields for:

• Expiry Date
• Queue
• Short Key
• Key URL

Begin by logging into Vivantio and going to the Admin Area. You will then go to:

System Areas » Incidents » Custom Forms

From there, you can start adding fields:

(Note: All of the field can be created as “Read only” fields as they will be populated by the Webhook and not end users.)

Having created the fields: create a Custom Form with those fields on the following screen:

EMAIL TEMPLATE

In order to create the Email Template, navigate to:

Admin » System Areas » Incidents » Templates » External Emails

From there, you can click the “Add” button and enter the email you would like to be sent to your end user. You can see our example below:

After saving the email, make sure that the template is available for the “Add Note” process by using the “Action Types” button on the email template list.

WEBHOOK

In order to create the Webook, navigate to:

Admin » Integration & API » Webhooks

From there, you can click the “Add Webhook” button. You will then choose “Incident” and see the Add Webhook screen. You can name this what you like, but, for our example, we will name it “Start BeyondTrust Session”. From there, you will need to fill out a number of tabbed parameters. You can see an example of what that will look like below:

Notes on Specific Fields:

Basic Details » Request URL:

This is the format it should be in:

https://instance.beyondtrust.com/api/command?username=username&password=password&action=generate_session_key&type=support&queue_id=general

The bolded and italicized values should be specific to your BeyondTrust account. You might also want to change the “type” and “queue_id” values to match your instance.

Response Fields:

This tab allows us to extract information from the BeyondTrust response and put it in a Custom Form. We recommend using XPath to get the values out. Here’s an example of what that would look like in practice:

USING THE WEBHOOK

Having completed all of these steps, you should be able to see the “Start BeyondTrust Session” link on the Ticket Details page such as in the example below:

When selecting that option, an email should be sent to your customer, complete with a link to join the BeyondTrust session.

LEVERAGING WEBHOOKS IN SERVICE MANAGEMENT

In this post:

• Webhooks: what they are and why they exist.
• Worked example: How to leverage Webhooks to send SMS messages from The Vivantio Platform using Twilio (Highly technical)

In our last Customer Center post we looked at the what and why of Web Methods and how they can be used to create lightweight endpoints to receive messages from external services such as CopperEgg. In this post, we’re going to look at what you might call the opposite of Web Methods: Webhooks.

What is a Webhook?

Webhooks are nothing new in the tech sphere. Jeff Lindsay came up with the term Webhook in 2007, and if you’re interested, you can read more about the general principle here. If you’ve been following the series, you’ll know that in the last blog post we looked at using Webhooks coming from Copper Egg to send information to Vivantio. The basic goal of a Webhook is to allow one system to connect to another via a HTTP request to carry out an action of some description – telling us an alert condition was detected in the CopperEgg example. So in this post we’re going to look at how you can use Webhooks coming from Vivantio to send information to other systems.

Why use Webhooks?

If you’re looking at integrating Vivantio’s ITSM software with another business tool – CRM, Bug Tracking, Billing, etc. – there’s a good chance the system you’re integrating with is going to need to know when something has happened in Vivantio, such as a new Ticket has been logged or a Ticket has been closed. Without Webhooks, you’d probably end up with a solution that polls the Vivantio API looking for new events you’re interested in and then doing something with them. There are a few downsides to that approach:

• You’ve got a lot of code to write and maintain
• You have to find somewhere to deploy it
• Your IT solution is either a. very chatty or b. slow to respond to events (or both!)

Webhooks solve some or all of those problems:

• You don’t need to write code*
• They’re contained within the Vivantio ITSM Platform
• Event notifications are sent in near real-time

*At least not in Vivantio’s service management tool. Depending on the system you’re integrating with, you might have to write some code to handle the request coming out of Vivantio – we can’t always help you out there! But feel free to email support@vivantio.com and we might be able to give you some pointers, examples or best practices.

Worked Example – SMS via Twilio

Vivantio Webhooks allow you to easily get up and running with with SMS messaging. There are a number of SMS providers out there with HTTP APIs. Our favorite of these providers is Twilio. In this example we’re going to walk you through setting up a Webhook in Vivantio that lets you easily send an SMS message via Twilio.

To follow this example, you’ll need to sign up for a Twilio account. Once you’ve done that, make a note of your Account SID and Auth Token from the “My Account” page:

You’ll also need to set up a “From” phone number. You can do this in the “Numbers” section of your account:

Finally, take a look at Twilio’s API documentation here. That describes the format of the HTTP request that should be sent to Twilio:

The next step is to set Vivantio up to send a message to Twilio similar to the one shown above. So log in to Vivantio and head to Admin → Integration → API → Webhooks:

If you don’t see that option there, contact us via email or our support portal and we’ll enable it for you.

Once you’re there, click “Add Webhook” and you’ll see a list of your available Ticket Types.

Choose one, and you’ll see the Add Webhook dialog, starting off with the Basic Details tab.

Basic Details

First up we’re going to give it a name – here, we’ll be using “Send SMS via Twilio.” Then you have a few other simple fields to fill out:

Request URL

This is the URL at Twilio we want to make the HTTP request to when the Webhook is run. You can get this from your Twilio account. It’ll look something like:

https://api.twilio.com/2010-04-01/Accounts/YourAccountSID/Messages.json

Add that into Vivantio:

HTTP Method

This is the method the request will use. At the moment we only support GET and POST; for Twilio, we’re going to use POST:

Username / Password

Your username is your Twilio Account SID; your password is your Auth Token. If you’re following this walk-through, you’ll have noted these down earlier:

Response Content Type

In this example, we’re not going to do anything with the response we get from the request to Twilio, so this isn’t crucial. The response will be in JSON format though, so let’s pick that:

Action Description

The final box lets you enter some text to appear in the Ticket History after the Webhook has been executed. You can enter whatever you want here:

Advanced users can use the to reference parameters so that parts of the Webhook can appear in the Ticket History. That can be left as an exercise for the reader to experiment with!

With the Basic Details complete, we move on to the next tab, Parameters.

Parameters

When the Webhook executes, Vivantio is going to send some data to another system. Sometimes, that data is going to come from within the Ticket that started off the Webhook like the Ticket ID or Description, for example. Sometimes though, you might want to allow the person running the Webhook to enter a value to use in the Webhook. In our example, we want to let the user enter a) the text to be sent in the SMS, and b) the number to send it to, so we’re going to add two parameters – Recipient and Text.

Recipient

As you might have guessed, this represents who is going to receive the SMS.

Name

The label that will appear on screen next to the input field when the user runs the Webhook – we’ve gone with “Recipient”. This is also used to reference the value within the Webhook body as we’ll see a bit later.

Read Only

Whether or not the end user can edit the field when they run the Webhook. In our example we’ll allow the user to adjust the number if needed but in the real world you might want to restrict this.

Data Type

The type of data that the field will allow. At the moment we only support alpha-numeric fields but we’ll be adding more as we continue to develop the Webhooks module. As always, if you need something that isn’t there, let us know!

Display Type

How the field will appear on screen. We only need a single line text box for the recipient phone number so we’ll choose “Freetext”.

Default Source

The “Default Source” for the parameter value, i.e. what the field will be populated with when the user runs the Webhook. You can either enter a fixed value or use the here to reference properties from the ticket. In this example we’ll use {{ticket.callerphone}} to get the phone number of the caller from the Ticket.

Text

For the second parameter, Text, we’ll use the values shown below. Although similar to the above, here we want a multi-line text box and we don’t need a Default Source specified.

Now that the parameters are set up we can move on to the next tab, Request Body.

Request Body

This is where we set up the actual HTTP request that will be sent to Twilio. To start, we’re going to set the Request Content Type to application/x-www-form-urlencoded – that’s the format Twilio accepts:

Next, we’re going to give it a name – here, we’ll be using “Send SMS via Twilio.” Then you have a few other simple fields to fill out:

For the Request Body, we need to go back to the Twilio API docs we saw earlier. The Twilio example given is:

Body=Jenny%20please%3F%21%20I%20love%20you%20<3&
To=%2B15558675309&
From=%2B14158141829&
MediaUrl=http://www.example.com/hearts.png

We don’t need the Media URL parameter and we’re going to take the Body and To fields from the parameters we created. Our Request Body is going to look like this:

From=YourTwilioFromNumber&To=&Body=

(Replace the italicized bit with your Twilio From Number – you did set one up earlier, right?)

That leaves us with:

That’s all we need to send a basic SMS out. The next tabs along are “Response Fields” and “Response Actions.” We mentioned earlier that we won’t be using the response from Twilio so we’ll skip these two for now. An upcoming blog post will show you how to use Response Fields effectively. So we’ll go straight on to the final tab we’re interested in, Select Tickets.

Select Tickets

This tab lets you configure which Tickets the Webhook is available. In our example, it’s a simple restriction – where the “Caller Phone” field isn’t empty. If we haven’t got a phone number for the end user we can’t send them an SMS! Although, since we left the “Recipient” field editable by the technician, we could leave this blank so it appears for all tickets and you’d be able to enter the number when you run the Webhook.

In a more complicated scenario, you might want to restrict it so that SMS messages are only available on tickets logged by end users who have signed up to receive SMS updates. Or any of a variety of other scenarios.

Once you’ve done that, hit “Save” and you’ll see the Webhook in the list. We’re almost ready to use it:

There’s one more step in the admin area: configuring Roles. You can restrict which Roles can execute each Webhook. By default no permissions are granted, so you’ll want to select the Webhook, hit “Roles” and drag over one of the roles you’re a member of:

All the configuration is done! Now, when you view a Ticket that meets the conditions set in the “Select Tickets” tab, you’ll see the Webhook appear in the “More” menu on the Ticket Details page:

Clicking that option will bring up a dialog prompting you for any parameters (with defaults set, if configured):

Shortly after hitting “Save” your SMS will be sent.

Job done! Vivantio’s service management platform can now send SMS messages via Twilio without writing a single line of code (well…sort of…you had to write the body of a HTTP post, which is almost code – although our development team might take offense if we start calling that coding).

That wraps up this brief introduction to Webhooks. In our next blog post, we’ll be looking at using Business Rules to tie Web Methods and Webhooks together, to give you a more complete end-to-end view of the power of Web Method and Webhooks. You can get started with Webhooks now though – and if you find an interesting use case for them, let us know. We can help you set them up if required, and if what you’re doing is really cool, you might find yourself the subject of an upcoming post!

HOW TO APPROACH INTEGRATION METHODS

When looking to integrate Vivantio with other platforms, it’s important to understand the different methods available to you. We have many avenues of approach and they each offer different pros and cons.

We’ve divided your integration methods into five distinct areas:

VIVANTIO INTEGRATION SERVICES

The Vivantio Integration Services Component (ISC) provides a growing number of modules to allow your team to connect with other systems via a built-in GUI.

As of this posting, those systems include:

• Active Directory
• SQL

You can also schedule data exports such as reporting via the ISC.

DIRECT FIRST CLASS INTEGRATIONS

Over time, due to their popularity with our customers, we have developed a number of direct integrations. These will work out-of-the-box.

As of the time of this post, these include:

• JIRA
• TFS

WEBHOOKS AND WEB METHODS

In order to offer our customers a method to configure interactions without code, we’ve set up Webhooks and Web Methods in Vivantio. With this method, you can set up outgoing HTTP notifications or allow systems to make simple HTTP requests within Vivantio. This offers great flexibility for use with systems that utilize this functionality.

THE VIVANTIO API

Vivantio is built “API first”. What this means is that we have an extensive API that your development team can use to query, update, and create data. This method offers the most possible flexibility. You can find our (work-in-progress) API documentation here.

BESPOKE DEVELOPMENT

It should be noted that, if none of the above options fit with your needs, we are always welcome to explore bespoke development of integrations for our customers. If you contact our support team, we are happy to arrange for a member of our professional services or product team to discuss your requirements in more detail and work out a solution that works for you.

CONSIDERING YOUR INTEGRATION OPTIONS

When considering an ITSM platform, it’s always important to understand how it will work with your other tools. The Vivantio Platform comes with a number of different integration options to help you get data in and out of Vivantio. Let’s look at the four most common types of software that can be integrated with Vivantio.

CUSTOMER RELATIONSHIP MANAGEMENT / ACTIVE DIRECTORY

If you are using or considering to use Vivantio, there is a good chance you have end users who are logging support tickets with you. So, it makes sense to have key information such as what asset each ticket is associated with or how to contact your end user stored in Vivantio. We offer a number of integration options to connect to your CRM or Asset Management tools.

ASSET DISCOVERY

Asset management isn’t the only kind of software we work with. You might also have tools that capture and record information on your assets or network such as:

• SCCM
• Spiceworks

If you want it on hand for your ITSM toolset in order to track repeat issues, the impact of upcoming changes, or tracking scheduled maintenance, we can connect with those tools as well.

MONITORING TOOLS

You might have tools that proactively monitor your IT assets. This can help you track when servers go down or assets are failing. Vivantio can connect with your monitoring tools in order to help automate support for when these events occur.

APPLICATION LIFECYCLE MANAGEMENT

If you house an internal development team, there is a good chance they use application lifecycle tools such as:

• Microsoft Team Foundation Server (TFS)
• JIRA

Vivantio allows your support team to connect with these tools in order to connect your teams and share key data.

These are only a few examples of the types of software Vivantio can integrate with. Please contact our support team if you have any questions about specific integrations.