How to Integrate CopperEgg with Vivantio
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.
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”,
“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:
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”.
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.
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.)