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.

PREREQUISITES

In order to connect Vivantio to TFS, you’re going to need:

• Admin access to your Vivantio instance
• Admin access to your TFS instance
• A user account in TFS for Vivantio
• The IP address(es) for your TFS servers

BASIC CONFIGURATION

Step 1:

Log in to Vivantio, open the Admin Area, and select TFS under the Integration & API heading on the left menu:

The first screen you’ll see will prompt you for the version of TFS you’re using, and the credentials to use.

• If you’re using TFS 2012/13, or 2015, enter a username and password.
• If you’re using TFS 2017 or VSTS, enter a username and a Personal Access Token. For details on creating a PAT, see the MSDN documentation here.

Having entered those and hit the ‘Save’ button.

Step 2:

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’ll use one of these URLs when you set TFS up to send information back into Vivantio. We’ll get more into that later. But, while you’re here, you should configure the IP Range for Vivantio to accept requests from, using the ‘IP Range’ button in the menu bar:

Having configured those, you can move on to the next tab, Ticket to Work Item Mapping.

TICKET TO WORK ITEM MAPPING

You can control which types of Vivantio Ticket can be mapped to which types of TFS Work Item by setting up Ticket to Work Item Mappings. This prevents the wrong type of information being transferred or the wrong type of records being created.

When creating a Ticket to Work Item Mapping, you’ll be prompted for a number of different things:

• Project Collection – The Project Collection in TFS
• Project – The Project in TFS
• Work Item Type – The Work Item Type in TFS
• Ticket Type – The type of Ticket within Vivantio

These control the basics of the mapping. On the next tab, Sync Options, there are settings relating to the sync of data between:

You can configure Vivantio to automatically send updates to TFS when the Vivantio Ticket is updated. (Note: This option does not force TFS to update Vivantio. That has to be configured within TFS itself.)

Finally, you can add 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.

After choosing the appropriate options, hit ‘Save’, and you’re ready to start creating TFS Work Items.

CREATING A NEW WORK ITEM

When viewing a Ticket in Vivantio, under the “More…” menu item, you’ll see the option to “Create New TFS Work Item”:

Clicking that button will bring up the “Create New TFS Work Item” dialog:

You can optionally enter Notes for the Vivantio Ticket History, then hit ‘Save’ to create the TFS Work Item. After a short period of time, you’ll see a TFS tab appear on the Ticket Details:

That includes a link to view the Work Item in TFS, along with options to unlink the ticket from TFS, or to add a direct comment to the TFS Work Item, which can be useful if you didn’t choose to automatically sync actions.

GETTING INFORMATION BACK FROM TFS

The next step in the process is getting information added to TFS sent into Vivantio. This is done using one of two mechanisms, depending on what version of TFS you’re using:

• Work Item Alerts (TFS 2015 or earlier)
• Service Hooks (TFS 2017 / VSTS)

The configuration is pretty similar either way.

Creating a Work Item Alert

(The Microsoft documentation on Work Item Alerts can be found here.)

Work Item Alerts are the ‘older’ of the two mechanisms that can be used for TFS to update Vivantio. If you’re using a version of TFS that supports Service Hooks, we suggest you use those instead. However, if you do want to use Work Item Alerts, you can do so easily.

You can follow the instructions in the MS documentation to configure the basics of the Work Item Alert – which work items the alert is for, and when. The main difference is that rather than having the alert delivered to an email address, you’ll select the ‘SOAP’ option, and enter in your Work Item URL:

TFS will then send a HTTP request to Vivantio when the alert fires, and Vivantio will add the details of the update as a Note on the ticket.

Creating a Service Hook

(The Microsoft documentation on Service Hooks can be found here.)

Service Hooks are a newer feature within TFS–introduced in TFS 2015. We don’t currently have Vivantio listed within TFS as a dedicated option, so on the first page of the Create Service Hook wizard, you’ll choose the “Webhooks” option:

On the next page of the wizard, you’ll choose the type of event the Service Hook triggers on:

Right now, we only support Work Item Commented On and Work Item Updated, but we’re working on introducing support for other events soon. Enter any filters you want for the area or work item type, then move on to the last step:

All you need to do here is add your Service Hook URL, then click Finish. TFS will then start sending updates on Work Items back in to Vivantio.

If you’re using Vivantio and TFS, and you don’t yet have them integrated, give it a try, and see how it can help you improve communications between your Service Desk and your development team!

ASSET SYNCHRONIZATION IN VIVANTIO

If you’re running an IT service desk or managed service provider using Vivantio, you’ve probably got some IT assets out there. When your end users log a ticket with you, there’s a good chance that it will relate to one of those assets.

If you’re using an Asset Discovery tool, then you’ve also got a database of those assets somewhere. Asset Synchronization allows your technicians to get all the information they need from that database within Vivantio.

WHAT YOU NEED FOR ASSET SYNCHRONIZATION

You can use the Vivantio API to build your own Asset Synchronization, but there is another way. Depending on where your data is stored, there are a couple of out-of-the-box options available via the Vivantio Integration Services Component.

WHAT IS THE INTEGRATION SERVICES COMPONENT?

The Integration Services Component (ISC) is an application you install on your local network. It is designed to run one of several different types of task that require access to local resources, such as your Asset Discovery database. In terms of tasks available from your ISC, there are quite a few including:

• Asset Sync (what you will use for Asset Synchronization)
• Active Directory Sync
• Scheduled Export

The ISC can be downloaded via the Admin Area in Vivantio. Basic setup can be performed via the installer.

WHAT ASSET DISCOVERY TOOLS CAN I CONNECT TO?

The Asset Sync connects directly to the database used by your chosen Asset Discovery tool. At the time of this post, we have support for:

• SQL Server
• SQLite databases

It should be noted that connecting directly to the database has pros and cons, but this allows us to connect with the widest range of tools.

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.

The primary method for integrating CopperEgg with Vivantio is through Web Methods.

WHAT ARE WEB METHODS?

Web Methods are lightweight HTTP endpoints that are configurable in Vivantio to receive HTTP requests. After receiving a request, Vivantio will then perform a series of actions using data from the request.

From the developer’s point-of-view, it’s similar to a web service, but you don’t write code for it. Web Methods are configured using a GUI.

WHY USE WEB METHODS?

Web Methods were originally developed to address when customers want to create tickets in Vivantio using an HTTP request made by other systems. We wanted to give our customers a way to create integrations without depending on the Vivantio API and development team resources or time.

BASIC CONFIGURATION

When creating a Notification Profile in CopperEgg, you can specify the “Destination” as a “Webhook”. This means the details of the CopperEgg alert will be sent as an HTTP post to the URL you specify. You can see an example of this below:

To give you an idea of the target process flow for the integration, it will look something like this:

After setting this up, you will need to find out what CopperEgg is going to send Vivantio as part of the notification. You can find this in the CopperEgg documentation. As an example, we will use the sample below:

{

“alertid” : 15688482,

“create_time” : “2015-03-11T16:30:52Z”,

“clear_time” : null,

“alert_text” : “V-SPICEWORKS: Lost Connectivity (Server Not Seen)”,

“tags” : [],

“kind” : “active”,

“alert_source” : “system”,

“details” :[

“description”,

“Additional Information”,

{

“inet” : “10.2.150.37”,

“Operating_System” : “Microsoft Windows Server 2012”,

“inet6” : “fe80::14da:773e:b5bf:ee20u0012”,

“hostname” : “V-SPICEWORKS”

}

] }

With this example in mind, let’s walk through how to create a Web Method in Vivantio that can respond to this type of alert.

WEB METHOD CONFIGURATION

(Note: In the future, we hope to have this down to a single button click for CopperEgg.)

Using the previous example, the first step for configuring your Web Method is to create a Category for CopperEgg alerts. You can find this in:

Admin » System Areas » Incidents » Configuration » Categories

From there, select “Add Root” and enter a name. For this example, we will use “Copper Egg Alert”.

For the next step, we will create a Custom Form to store the details of the CopperEgg alert. You can find this in:

Admin » System Areas » Incident » Custom Forms & Fields

Using the example, we are looking to store the “Alert ID”, “Alert Text”, and “Hostname”. As these will all be filled in by the Web Method, they can all be created as “Read only” for the Field Type.

Once you create the three fields, we can create a Custom Form with those field and set it to appear for the “Copper Egg Alert” Category we created earlier:

The next step is creating the Web Method itself. You can do this under:

Admin » Integration & API » Web Methods

In this screen, select Add and it will bring up a dialog similar to this example:

Let’s explain what you need for each tab:

Basic Details

• Name – This is where you can name your Web Method.
• Access Key Auth – If you have this enabled, enter an IP address range from which requests will be accepted.
• HTTP Method – CopperEgg uses an HTTP POST when sending webhooks, so select that option from the dropdown.
• Request Content Type: CopperEgg data is sent in JSON, so select “application/json”.

Parameters

This is where you can set up the values you expect to receive as part of the Web Method. Using our example, we can refer to the “Alert ID” value.

After hitting “Add”:

• Name – This is where you can specify a name for the parameter for reference.
• Source Type – This tells the Web Method where to pull the value from. With our example, we are taking from the “Request Body”.
• Source Path – This is where you specify where to pull the value. You can use XPath or “dot notiation” to note the path. Using our example, we would specifiy “alertid”.
• Default Value – This is where you would specify a default value for the parameter. In this example, we would not need any default values.

Actions

This is where you can set up what the Web Method will do when invoked. You can add multiple actions for each Web Method. You can also note conditions for the action.

(Note: As of this post, we only allow two choices: Create a New Ticket or Update an Existing Ticket.)

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.