I recently decided to try my hand at building a Jive App with some simple integration to one of our infrastructure provisioning tools called Foreman and I found that after following the Jive Developer training (which is an excellent way to get started, by the way) I still wasn't sure how to hook my app up to a third party API and use basic authentication.

Foreman itself is a fantastic open source tool which allows you to orchestrate the creation and configuration (via puppet or chef) of your VM's and physical infrastructure. In my organisation we use it to enable us to rapidly deploy development environments (host groups in foreman lingo, I use environments as a classification like production, pre-prod, dev etc).

The problem I am trying to solve, is to have a way for developers and managers to quickly see a list of environments that exist, the virtual machines which exist inside of those host groups and any IP addresses allocated to the server from within the Jive interface. I know that some of you might be uncomfortable with merging infrastructure tools with a social platform - but it's an experiment, it could work well or it could be awful - and there is only one way to find out!

Prerequisites

Before you begin this tutorial you will need to have the jive node sdk installed, have access to the jive developer sandbox or an on-prem development instance and have access to a foreman instance. My intention is that this could be used to access any tool with a REST API inside your organisation so feel free to swap and change as appropriate.

Where to begin?

Ok, so we know that our problem is to display a list of host groups and the hosts that they contain from within a Jive App so that our developers and managers can easily access the information from a unified interface that they are familiar with. Jive provides a great API in the form of the Jive Connects which we will leverage to send connections to the third party API.

The third party API I need to work with is documented here: The Foreman :: API and the main functions I am interested in using are:

/api/hostgroups - inside foreman all of my hosts belong to their own hostgroup, so a single Jive instance belongs to a hostgroup like jive-dev1, jive-dev2 etc

/api/hosts - gets a list of hosts, or an individual host if an ID is specified.

So lets get started.

First, we need to use the Jive SDK to deploy a skeleton app that we can use as the base for what we are trying to do.

Once you have done this, you will need to upload the extension.zip file to your server have a basic app, configured and deployed. Make sure that you can see the App in your apps drop down menu to ensure it loaded correctly.

Now for the fun part. Lets modify our App to change the name and also to add support for the Jive Connects API. At this point I should tell you that there is already some great documentation for using Jive Connects with Authentication at Jive Apps Developer Community: Jive Connects API - Client Application Configuration and API Usage, but don't know if it was just a lack of coffee when I tried this but I struggled to find how to use basic auth in the documentation, hence this blog post.

The fun stuff....

Update app.xml

First, lets update apps/myforemanapp/public/app.xml and change some of the metadata and add support for the Jive Connects API. I have commented the bits I modified or added. I also removed anything that wasn't used in the file that comes out of the box.

Setting up a service tag

The code we have created looks good, but even if you upload it, you still won't get any joy from it. Thats because we now need to create the service tag definition - which tells your jive instance exactly how it needs to connect to your third party API.

In your Jive Admin panel (/admin/apps-services.jspa) browse to the Add-On tab, then "App Services" from the menu on the left. Click 'Add Service' and then set up your service so that it matches my screenshots below, changing the service url to match the API you want to connect to. Note that the jive service tag field is the most important - this MUST be identical else your app won't work!

We are adding HTTP Header definitions version=2 because we need to tell Foreman that we want to use version2 of their API. After you have created your service tag you should be ready to go. Because we have modified the app.xml, I find it good practice to uninstall the app, re-run node app.js to generate a new extension.zip and then to redeploy the extension.zip file to your instance.

Once your app has been re-deployed visit your app, go ahead and launch it through the apps menu:

You should then see a screen asking for your Foreman credentials:

Enter your credentials provided by Foreman, and then click submit. This will be the last time that you are asked for your credentials unless you change the authentication type for the service tag, or your credentials change on the third party system. Once you have done that, you should see a screen like the (ugly) one below containing a list of your host groups, hosts and their IP addresses. With a bit of polish this will be ready for our users.

Thanks for reading. I hope this helps some novices like me to quickly put together a remote authenticated API call.