How to connect OTRS with GitHub

Robert Ullrich19. Sep 2017 | Best PracticesConsultingUse cases

Last time I had a requirement of a customer, who wanted to connect OTRS with the GitHub account of his company. I think this might also be an interesting use case for you. In this small blog article you can learn, how to create an issue in GitHub via OTRS, to receive the latest information on a GitHub issue and to create comments for an issue in GitHub.

To complete this Howto, you need a running OTRS & a valid GitHub repository. Furthermore, you need a valid user login and the “access_token” of the user which should be used for the integration. The REST/JSON API of GitHub can be used by everyone, who has a GitHub account.

Use case for this connector

The GitHubConnector can be used in software developing companies, where the customer service team is using OTRS for the requests of customers and the development department is using GitHub for maintaining the source code, work on open issues a.s.o. To improve the communication (and to prevent agents to work on two different systems) you can use the GitHubConnector of this article.

OTRS Requirements for this HowTo

OTRS Framework

  • at least OTRS 5.0.x

OTRS Packages

You need the following Freely selectable Features of the OTRS Business Solution5s :

  • OTRSGenericInterfaceInvokerTicket
(Adds new invoker for TicketCreate and TicketUpdate in the GenericInterface.)
  • OTRSGenericInterfaceInvokerEventFilter
(Contains additional functionalities to add conditions to events of invokers.)

Third Party Software

You need this third party software:

  • XML::Simple
  • XML::LibXML
  • XML::LibXSLT

DynamicFields

  • “GitHubIssueID” of type „TEXT“ to store the GitHub issue id (e.g.: 1)
  • “GitHubCreateTime” of type “TEXT” to store the timestamp, when the issue was created
  • “GitHubUpdateTime” of type “TEXT” to store the last update time of the issue in GitHub
  • “GitHubIssueState” of type “TEXT” to store the latest state of the issue from GitHub

 

Configuring the GitHubConnector in OTRS

After you satisfied the pre-requirements, you’re ready to create a new web service within OTRS. The name of the new web service is “GitHubConnector”. Afterwards, you have to set up the needed invokers.

GitHubConnector General config

Configuring the Invoker “IssueCreate”

Now you’re ready to start the configuration of our Invokers. To be able to create issues in Github, you have to set up an Invoker called “IssueCreate”.  Select all the needed data for your outgoing requests and use “XSLT” as mapping for your outgoing and incoming response data.

GitHubConnector IssueCreate Config 1

For the incoming response data, you have to select the dynamic fields (GitHubIssueID, GitHubCreateTime, GitHubLastUpdate and GitHubIssueState), which you created before.

GitHubConnector IssueCreate Config 2

For our XSLT mapping we need at least the following elements:

Name Type Description
title string Required. The title of the issue.
body string The contents of the issue.

Now you can configure your outgoing XSLT-mapping. If you need a working XSLT-mapping, you can use the following example:

GitHubConnector IssueCreate OutgoingXSLT

You also need a XSLT-mapping for the incoming response data, because you have to store the GitHub Issue ID,  the Create Time the Last Update Time and the GitHub Issue State:

GitHubConnector IssueCreate IncomingXSLT

OTRS stores the GitHub Issue ID in the dynamic field “GitHubIssueID”. Afterward, it’s shown in the OTRS TicketZoom.

Furthermore, we want to know the latest State of the GitHub Issue, that’s the reason why it’s also stored in a dynamic field

The used “Event trigger” is the last point for this invoker. Just select one and you’re done with the first Invoker.

Configuring the Invoker “IssueGet”

The next invoker is “IssueGet”.  Select all the needed data for your outgoing requests (please don’t forget the dynamic field “GitHubIssueID” in the “Ticket dynamic fields” drop-down) and use “XSLT” as a mapping for your outgoing data.

GitHubConnector IssueGet Config 1 GitHubConnector IssueGet Config 2

As outgoing XSLT-mapping, you can use my example. I will transmit the Issue ID to GitHub because I want to get the latest Issue state.

GitHubConnector IssueGet OutgoingXSLT

A mapping for the incoming response data is necessary because we want to store the “LastUpdate” timestamp and the latest Issue state.

GitHubConnector IssueGet IncomingXSLT

The used “Event Trigger” is the last point for this Invoker. Just select one and you’re done with the second Invoker. In my example, I’m using a dynamic field update, which is automatically set by a GenericAgent.

 

Configuring the Invoker “NoteCreate”

The next invoker is “NoteCreate”.  Select all the needed data for your outgoing requests (please don’t forget the dynamic field “GitHubIssueID” in the “Ticket dynamic fields” drop-down) and use “XSLT” as a mapping for your outgoing data.

GitHubConnector NoteCreate Config 1 GitHubConnector NoteCreate Config 2

Use my example as outgoing XSLT-mapping:

GitHubConnector NoteCreate OutgoingXSLT

You don’t need a mapping for the incoming response data.

The used “Event trigger” is the last point. Select one and you’re done with the last Invoker of my tutorial. In my example I’m using an ArticleCreate event in OTRS, to trigger the Invoker.

 

Configuring the GitHubConnector “Network Transport”

 

Requester configuration

It’s necessary to configure the network transport for the Invokers because we’ve to use the right requests commands towards GitHub.Otherwise we’ll receive errors. It’s quite easy as you can see:

GitHubConnector Transport Config

We don’t have to use an authentication module because we’re using the access token of a specific user in our mapping.

Afterward just click on “Save and finish”.

Testing the GitHubConnector

Testing the Requester

Create or take an already existing ticket and trigger the “IssueCreate” Invoker.

As result you should see something similar in the OTRS Debugger:

GitHubConnector IssueCreate Debugger 1 GitHubConnector IssueCreate Debugger 2 GitHubConnector IssueCreate Debugger 3

In GitHub a new issue was created:

GitHubConnector IssueCreate Github

If we now trigger the Invoker “IssueGet” we’ll see the following in the Debugger:

GitHubConnector IssueGet Debugger 1 GitHubConnector IssueGet Debugger 2

OTRS is now requesting everything from GitHub for a specific issue and is mapping the data into our dynamic fields:

GitHubConnector IssueGet Debugger 3

You’ll now see the following information in the TicketZoom:

GitHubConnector IssueGet TicketZoom

And the last the Invoker is “NoteCreate”:

GitHubConnector NoteCreate Debugger 1 GitHubConnector NoteCreate Debugger 2 GitHubConnector NoteCreate Debugger 3

You can now see that the Note was created in GitHub:

GitHubConnector NoteCreate Github

More information about the GitHub API

You can also use other resources which are provided by the GitHub API.

If you need more information, please go to the following website: https://developer.github.com/v3/

Your email address will not be published. Required fields are marked *

This site uses cookies. By continuing to use the site, you agree to the use of cookies. More information

The cookie settings on this website are set to "allow cookies" to give you the best browsing experience possible. If you continue to use this website without changing your cookie settings or you click "Accept" below then you are consenting to this.

Close