Star Fork Watch

Using Titanoboa as an open source alternative to Zapier

Among other things, Titanoboa can be used to replace your cloud-based integration (iPaaS) provider - if you prefer to run your iPaaS on premises or in your private cloud or you simply need to customize it a bit (as enterprises usually do). Or if you just love Titanoboa and want it to handle everything!

But you know what they say: the proof is in the money - and that you should put your pudding where your mouth is. So lets use Titanoboa to integrate stuff:

Sample Integration: Connecting Github with Slack

Very common "hello world" of cloud integration is to integrate a github repository with a Slack channel.
In this particular example I will want to get a Slack message when somebody opens (or changes) an issue in a github repository.
It is certainly easy using Zapier for this use case. But how hard is it with Titanoboa? Especially if I have not pre-built any of the integration steps yep - how hard could it be? I attempted it and here is the result: it just takes a minute, maybe less.

You actually do not need any pre-built steps or to develop anything. You can use Github's webhooks to trigger a job in Titanoboa. That job will have only one step: to make an Http call to post a message to some Slack's channel.

Triggering the workflow job

Github offers an ability to configure webhooks. When configuring a webhook, you can choose which events you would like to receive payloads for. In this example it will be for github issues only.

On titanoboa's end, every workflow can be automatically invoked via a webhook (see wiki). Each workflow can be invoked by a call to URI

/systems/{system id}/jobs/{jobdef-name}

or

/systems/{system id}/jobs/{jobdef-name}/{revision}

Also - and this makes any integration very easy - there is no predefined schema or even a content type. Any (json or transit) properties sent in the request will get automatically transformed into a map of job's properties.

Github webhook configuration could then look something like this to invoke a workflow called "github2slack":

Now you can just create a new workflow called "github2slack" in Titanoboa:

And watch it getting triggered from github (say by creating a new issue):
All request's json properties sent from Github will get automatically translated into wokflow's properties. E.g following request

X-GitHub-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
X-Hub-Signature: sha1=1661da7bf2bfc4a605523af82dbfb851b5906f02
User-Agent: GitHub-Hookshot/044aadd
Content-Type: application/json
Content-Length: 6615
X-GitHub-Event: issues
{
  "action": "opened",
  "issue": {
    "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347",
    "number": 1347
  },
  "repository" : {
    "id": 1296269,
    "full_name": "octocat/Hello-World",
    "owner": {
      "login": "octocat",
      "id": 1
    }
  },
  "sender": {
    "login": "octocat",
    "id": 1
  }
}

will result in these job's properties:

A note on security

Each workflow definition has its own webhook URI that can be used to start a job. Naturally not all consumers of webhooks will support same type of authentication (e.g.JWT) - and so titanoboa makes it possible to define custom authentication function for any URI.

You can find an example of how to secure your "github2slack" workflow's webhook so as it works seamlessly with github's HMAC hex digest signature here.

Sending a message to Slack

This part is also super easy. Just follow Slack documentation here - create a new Slack app and add it to the channel you wish. It will be assigned a webhook URL that will look something like this:

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

Now to make an HTTP call to that URL you can use a predefined workflow step: Http Client. Since all information received from Github are readily available in job's properties, we can freely use them in our message that will be sent to Slack. Lets tweak the only workflow step we have so far and make it do what we want. We can include some fancy message formatting:

Now if we open a new issue in our Github repo we will get a message like this in Slack:

Congratulations! We have done it!

The whole workflow can be found in this github repository.

Read more about titanoboa in our github wiki.