tl;dr – This is a quick post to demonstrate the power of Device42’s webhooks. Here we show you how you can utilize events in Device42 to drive creation of JIRA tickets via Device42 webhooks, combined with rules & actions in StackStorm.
So you have Jira and you have Device42, and you’ve been learning the ropes around StackStorm for a bit now. You’ve done the tutorials, and deployed the example workflows. Maybe you’ve even created a rule or two of your own, and customized a few example actions to boot.
Now it’s time to automate your first real task. Where do you begin? It’s often a good idea to look at the simpler tasks that you are doing repetitively as a starting point, and work up from there. In this post, we’ll focus on automating the creation of a JIRA ticket when Device42 finds a new device, utilizing Device42’s webhook functionality to drive things, and StackStorm’s logic processing ability to handle the legwork. This example is not overly complex, but it’s easy to add complexity as time goes on, refining the rules and increasing the amount of data utilized in the process in the future. The benefit of the automation created in this example would be to save a tech from having to manually create a ticket for racking each new device. Instead, the ticket is created auto-magically, including device details.
As a starting point, we’re going to assume that you have a working StackStorm, Device42, and Jira installation.
The overview of the process is:
- Generate a StackStorm X-Auth-Token for the webhook to utilize
- Set up an Action trigger in Device42 that utilizes the endpoint created in Step 1
- Install the StackStorm JIRA Integration Pack (if not already installed)
- Create a rule(s) within StackStorm that will trigger the creation of a new JIRA ticket
Step 1 Generate StackStorm token for webhook auth
[root@CentOS]# st2 auth -t -p $ST2Password $ST2User
Where $ST2Password and $ST2User is your StackStorm credentials.
Copy the token that is returned (pictured, above). You’ll use this to create the webhook endpoint in Device42.
Step 1a Setup webhook endpoint in Device42
Next, lets create the webhook endpoint in Device42 using the token generated above. To do this, visit the Tools → Webhooks → Endpoints menu in Device42, and select Add Webhook Endpoint +.
You’ll need to create a StackStorm authorization token for the webhook to utilize as noted in step 1a, and you’ll also pick the name for your endpoint now, which you’ll use later when creating the rule as well.
Fill out the information on the create webhook screen as pictured below:
You can use tickettest as your endpoint, if you choose, as well –or you can pick your own endpoint name. The ‘name‘ field is for your reference only; I’ve called mine StackStorm. The Header Name and Header Token are very important. You need to type X-Auth-Token as the Header Name, and then for Header Token, enter the token you generated previously in Step 1. Check ‘Ignore Certificate Errors‘ if you do not have the proper certificates & DNS configured for your StackStorm instance. And lastly, choose any set of credentials –These are not required by StackStorm, as the token handles authenticates for us; However, Device42 requires we choose a set of credentials.
Save the endpoint, and move on to Step2…
Step 2 Create & Configure the “Action” trigger in Device42
Lets create the ‘Action‘ trigger in Device42, which will trigger our webhook to be sent to StackStorm when the event criteria we choose is met. As in the example above, the name for your action should be descriptive but not specific to the context of the action. Lets call it ‘Device Changes‘, since this Action will fire whenever any device is changed. If you wish to limit the triggering to device creation only, choose ‘Process Add Events‘.
As far as categories go, as a filter, I typed ‘device‘ and selected all the categories associated with devices. In the image below, you can see my webhook is set to fire on device addition, deletion, and/or change –and will only send the fields that have changed. If you would like all fields sent, leave ‘Changed Fields Only‘ unchecked.
For ‘Webhook Action Endpoints‘, choose the endpoint you created in Step1. In the example, you can see the StackStorm endpoint that was created above selected:
Step 3 Install the StackStorm JIRA Integration Pack
For step 3, you’ll need to install the JIRA Integration Pack. In case you do not have it installed, here’s a quick screenshot demonstrating the installation of the pack –and to save you the trouble of figuring it out, the JIRA pack has a bunch of dependencies. Use the following commands to install them –for reference, this is a CentOS x64 “basic server” install. It required one linux package (gcc compiler), and four python packages:
[root@CentOS]# yum install gcc [root@CentOS]# easy_install libyaml [root@CentOS]# easy_install pyyaml [root@CentOS]# easy_install pyjwt [root@CentOS]# easy_install cryptography
Once the above dependencies are installed, you can use ST2’s ‘packs.install’ command, which will install the JIRA Integration Pack from StackStorm’s repository:
st2 run packs.install packs=jira repo_url=https://github.com/StackStorm/st2contrib.git
This is a what a successful installation should look like (This is a screenshot of the execution history of the install, as the JIRA pack was previously installed. Nonetheless, the output of the install command looks identical if all goes well):
Step 3a Generate a Jira Auth Token & Configure the integration
To generate the JIRA authentication token, follow the basic instructions that can be found in the readme.md file that installed with StackStorm in JIRA’s integration folder (/opt/stackstorm/packs/jira ). Also in this folder, you will find a config.yaml file which requires the URL of your JIRA instance, the RSA certificate file you generated (per the Readme), an oauth_token + secret, and a consumer key. You will generate the consumer key, and use a script to get the tokens. The script referenced in the Readme file is broken 2018 Update: the file linked in the README appears to have been updated, and now works. You can use it, or the version on our Github repository (link). Generate your consumer key using python as such:
(Generating a random, example UUID via python [remove the dashes!] as consumer key)
Once you have generated a consumer key & set up the integration via the JIRA UI, grab, customize (the generated consumer key, path to the RSA certificate you generated per the readme, your JIRA server URL), and run the [fixed] generate_access_token.py to get JIRA oauth tokens for the config.yaml to complete the integration.
Step 4 Tying it all together
Creating a rule in StackStorm can be a trial-and-error type task, depending on how familiar you are with the process and all of the parts you are trying to bring together. Programming experience is a big plus here, as the .yaml format used to describe rules in StackStorm uses Jinja syntax, so if you know python, you’ll have a big head start!
Since we know Device42 will be sending a webhook over as we’ve configured, we know we can utilize the core.st2.webhook trigger when our criteria is met. Furthermore, we have configured Device42 to only send the hook when a new device is detected, but could easily send webhooks for any event, and detect a new device via ‘criteria’ –specifically, in the case of a new device being created, where trigger.body.action equals “I”. Since we handled that with Device42, the rule (as shown) checks that the category of the change (via trigger.body.category) is device (as shown below).
---
name: "D42_Create_Jira_Ticket"
pack: "custom"
description: "Rule that creates a ticket in Jira when Device42’s webhook fires upon creation of a new device"
enabled: true
trigger:
type: "core.st2.webhook"
parameters:
url: "tickettest"
criteria:
trigger.body.category:
pattern: "device"
type: "equals"
action:
ref: "jira.create_issue"
parameters:
project: "IN"
summary: "New D42 Device Detected: {{trigger.body.data['name']}}"
type: "Task"
description: "Serial: {{trigger.body.data['serial_no']}} AssetNumber: {{trigger.body.data['asset_no']}} Notes: {{trigger.body.data['notes']}}"
For the action portion of our rule, use ‘jira.create_issue’ from the JIRA Integration Pack (from Step 3). If you were to list out the required parameters (st2 run jira.create_issue –help) you would see that required parameters are project name, summary, issue type, and description.
Once you’ve finished writing your rule (or go ahead and copy and paste the example above into a local .yaml file), create your rule by running:
st2 rule create jira_ticket_create.yaml
…where jira_ticket_create.yaml is the name of the file you saved above. Your rule should then be visible as such if you list out rules (via st2 rule list). As written, the rule will listen on the URL /tickettest, and will create a ticket in the JIRA project called ‘IN‘, with the issue title summary made up of a concatenation of ‘New D42 Device Detected:‘ and the device’s name ( ‘{{trigger.body.data[‘name’]}}‘ ), which will be parsed from the webhook. Lastly, the rule will extract the Serial Number, Asset Number, and Notes (provided by Device42) into the description of the created JIRA issue, as can be seen in the latest JIRA Issue that was automatically created, pictured below:
The original webhook is received as such [pulled from st2api.log], which is useful in case you would like to pull out other variables, or get a better understanding of how the variables above map to the webhook that was received:
result = {
"category": "device",
"from": "UI",
"user": "admin",
"action": "I",
"time_stamp": "2016-10-27 18:55:41.396617+00:00",
"data": {
"asset_profile_id": null,
"bladeno": "",
"type_id": "3",
"serial_no": "08238",
"fiber_switch": "f",
"device_bhost_id": null,
"id": "98",
"custom_fields": "",
"uuid": "",
"hardware_id": null,
"virtual_subtype": "1",
"change_setpoint": null,
"storage_room_id": null,
"building_id": null,
"device_vhost_id": null,
"device_category_id": null,
"where_at": "",
"virtual_host": "f",
"in_service": "t",
"service_level_id": "2",
"blade_chassis": "f",
"autoobj_id": null,
"customer_id": null,
"name": "newdevice42",
"notes": "These are the notes I've entered into Device42.",
"asset_no": "802348582",
"switch": "f",
"sub_type_id": null,
"first_added": "2016-10-27 18:55:41.39296+00",
"live_id": null
}
}
That’s it! Your first automation should be fully-functional. Next time Device42 finds a new device, or you create one, you’ll see a JIRA ticket that corresponds. Hope you enjoyed following along, and congratulations!
