RESTful API “A new hope”
Over the years I have done a fair number of IBM Netcool Impact to Service Desk integrations. Using a variety of methods such as:
- Perl script called via an Impact policy (JRExecAction)
- Impact policy leveraging the much used Web Services DSA (SOAP)
The majority of these integrations used SOAP as REST API’s were less common. However, in the last few years Simple Object Access Protocol (SOAP) with its sometimes overwhelming complexity has become increasingly redundant when compared with the faster, more agile and less complex Representational State Transfer (REST). As with all new things there are pros and cons to using either SOAP or REST which we won’t discuss here but is covered in-depth on many technical web sites scattered throughout the world wide web.
With the release of IBM Netcool Impact 7.1 fix pack 6 (released 30th June 2016) Impact now provides a dedicated RESTful API, at last I hear you cry. Now you can move away from grinding your teeth in frustration at having to retrieve a WSDL file, compiling said WSDL into a .jar and then realise that you are missing some of the fields you required in the first place and need to update the web service itself before retrieving the WSDL.
This blog will now outline how to quickly integrate Impact with the JIRA service desk to create ‘Incidents’ using the new RESTful API.
Eagle eyed technicians will have spied a new ‘Data Model’ that can be created (since 22.214.171.124) to create RESTful API data sources named ‘RESTful API’.
To use RESTful functions in an Impact policy a RESTful data source needs to be created. by entering the details of the desired data source. The fields that need to be populated are:
- Data Source Name
- Host Name
And on selecting “Basic Authentication”
- User Name
Below is a screenshot of the Data Model screen and note that I have obscured some of the details.
I have given my data source a name of ‘JIRA_ORBDATA’ and entered the hostname of the JIRA server which is usually in the format of ‘<ORGANISATION>.atlassian.net’. The cloud service that my JIRA service desk listens on uses the default port of 443.
The following check boxes were all ticked by default and left as is.
- Use HTTPS
- Reuse Connection
- Cache Response
One thing to note is that as I was using HTTPS (really, who uses HTTP for over the web integration in this day and age) I had previously imported the Atlassian certificates into the required trust store.
Basic authentication was selected with a valid username and password and the default “Request headers” were used.
At the bottom of the page after populating and saving my data I clicked on the useful ‘Test Connection’ button. This displays “Connection OK” hopefully you will experience the same sensation as I at this point which is one of undiluted euphoria.
There is also a “Preview Request” button which shows a request and the passed headers, this innocuous but useful message led me down a dark path.
Please note that the Information text clearly has a line that states “Authorization:Basic ***********”. So I assumed that this was authenticating preemptively by default, I should know better by now not to trust my own eyes.
With the data model created I quickly knocked together a policy which makes use of the new function ‘RESTfulAPIPOST’ . This new function takes three parameters:
Path could be configured in the data model and left as a blank “” parameter in the policy but for the purposes of this example I have elected to populate it in policy with the value ‘/rest/api/2/issue/’.
Here is the policy in full:
On executing the policy an Incident will be created in the JIRA service desk with the following fields populated:
- Summary – “Test ticket raised via REST API Impact”
- Description – “Test ticket please ignore, Neil will delete in due course”
On executing the policy I got this:
However, I was not notified that a ticket was created and on logging into the JIRA service desk there has been no incident created. On checking the policy logs I see the following message:
This message captured by the policy is saying that the fields I have tried to set are not appropriate (paraphrasing). This has occurred as the policy has logged in anonymously which can be seen by the value X-AUSERNAME=anonymous in the above log message.
A quick read of the JIRA website here informed me that:
“Because JIRA permits a default level of access to anonymous users, it does not supply a typical authentication challenge. Some HTTP client software expect to receive an authentication challenge before they will send an authorization header. This means that it may not behave as expected. In this case, you may need to configure it to supply the authorization header, as described above, rather than relying on its default mechanism.”
Therefore my assumption that the policy was preemptively authenticating as based on the evidence of the information presented by the “Preview Request” button in the Data Model was wrong.
I assumed wrongly that the line “Authorization:Basic ***********”.” meant that it was preemptively authenticating, what a mistake to make.
I fixed this by going back into the Data Model scrolling down to “Request Headers” clicking on “New” and entering the following values and the clicking OK.
- Header Name = Authorization
- Header Value = Basic base64 encoded combination of username and password
Remember to save the change.
Now on running the policy I get notified straight away that an Incident has been created.
On clicking the link above it takes me directly into the newly raised Incident.
With the incident raised this brings this blog to a close. Hopefully, this blog outlined how quick and clean using the new RESTful API is to integrate with the Atlassian JIRA Service Desk. With a RESTful Data Model and it’s associated methods now supplied as standard from IBM Netcool Impact 126.96.36.199 onward. These new features open up many exciting prospects to integrate the Netcool suite with a myriad of service desks that have RESTful API’s. Please note that as with all things IBM please check that you have the required licenses in place before integrating Impact with an external service desk. If you have any questions on this subject please feel free to contact me at neil.richards@orb-data.