Sync ServiceNow to Jira - HTML to Wiki conversion

[Francis Martens]

(I'm Francis - product manager for Exalate at iDalko)

The challenge

An Exalate evaluator asked for an integration between ServiceNow and Jira (On-Premise) for an Agile Board synchronization. The product looked like a fit but was missing one major feature: 

All their story descriptions on ServiceNow are made using an 'HTML description' field, with embedded images.  

When applying these HTML fields to the Jira issue, unmodified - you get unformatted.

Now not very useful, is it? 

Also, there was an additional problem, the image tag refers to a file identified by sys_id. 
<img src="/sys_attachment.do?sys_id=9e185a2ddb8268d0e1d10e85ca961955" />

Enabling the HTML module in the wiki renderer was a no-go given the potential security risks (read XSS) associated to it.

Question from the customer: Would it be possible to deliver a feature which 

• Converts HTML to wiki notation
• Ensures that embedded images remain embedded? 

 

What is Exalate?

A small intro regarding exalate for those who are new to it.

Exalate is a cross-company integration solution allowing to integrate ServiceNow with many different other platforms such as Jira, Zendesk, Azure DevOps, Github and more coming.

The Exalate is deployed as a separate application in front of the ServiceNow instance. As an exalate administrator you can define what information is sent to the other side, and how incoming messages are processed and applied onto your ServiceNow instance.

Any integration solution requires flexibility to take into account the almost endless business cases, and Exalate provides this flexibility through groovy scripts.

How is the challenge resolved?

Jira allows to enable a wiki renderer - which allows to format the content of a description / multi line custom field.
By using markup tags such as h1, h2 ... it is possible to nicely present the content - more on this is available at Text Formatting Notation Help

To solve the challenge, a capability to convert html into wiki markup language was required.  Exalate allows to define 'external scripts' which can contain the required logic to implement such functionality.   To perform the conversion, a new groovy class was created which is using the jsoup.org html parser to break down the html coming from ServiceNow

Note: Highly recommended! It is a clean library, easy to integrate, and the author, Jonathan Hedley, is super responsive. 

The class can be used as follows

HtmlToWiki htw = new HtmlToWiki(replica.attachments)
issue.description = htw.transform(replica.customKeys."html_description")

And the result: 

or in wiki notation:

*Design proposition*
  
!^Pasted image.png!
  
  
*Requirements*
  
|{color:#ff9900} Description{color}|{color:#ff9900}Status {color}|{color:#ff9900} Comment{color}|
| | | |  

And the Embedded Images?

So how are embedded images then being handled?
The HtmlToWiki class can process BasicHubAttachment lists that contain a map between the sys_id (the remoteId) and the filename:

[

   "BasicHubAttachment"{

      id=11200,
      "remoteId=""`419e39c4db4624d0e1d10e85ca961907`",
      "mimetype=""`image/png`",
      "filename=""`Exalate-Thumbnail.png`",
      "created=""`null`",
      "filesize=""`151479`",
      "author=""`null`",
      "thumbnailable=""`null`",
      "zip=""false"

   },

...

   "BasicHubAttachment"{
      id=11202,
      "remoteId=""`9e185a2ddb8268d0e1d10e85ca961955`",
      "mimetype=""`image/png`",
      "filename=""`Pasted image.png`",
      "created=""`null`",
      "filesize=""`141019`",
      "author=""`null`",
      "thumbnailable=""`null`",
      "zip=""false"
   }
]

So - whenever there is an image tag containing in the src, a reference to "sysattachment.do?<sys_id>", that source will be replaced with the corresponding file name as known on the Jira side

More information?

This functionality can be used, by adding HtmlToWiki.groovy to the classpath on your Jira side. This can be for instance <jirahome>/scripts.

Given that there is a dependency on jsoup (version 1.13.1), that jar also needs to be added to the classpath. Again <jirahome>/scripts is a good candidate.

Conclusion

Extending Exalate with new capabilities can be done with the extensibility of external scripts. As external scripts can be versioned (like using git), any script can be validated before deployed into production.