In my previous post, Unleash the real power of JIRA with SIL, the Simple Issue Language, I explained why I loved SIL so much and provided a few examples as well. Today, we'll get you started with SIL by explaining how to install the JJupin and showing you all the functionalities provided by the plugin.
Note: The Simple Issue Language is available in several plugins, all made by Kepler Rominfo. The language itself is packaged in an independent JIRA plugin called katl-commons. To keep things simple in this post, we'll stick to the JJupin plugin.
To install the JJupin plugin, you will need to have "administrator" rights in you JIRA instance, which probably means being in the jira-administrators group. Once that is done, simply go in the "Add-ons" section of JIRA Administration and search for JJupin, then install it. Make sure you activate it with a trial (or a real) license.
Yes, JJupin is a commercial add-on that costs real money, and yes, I know Script Runner is free and allows you to do scripting as well. Here is what JJupin costs:
First of all, it's super cheap. Secondly, I'm convinced by the time this post is over that you'll be convinced JJupin is an absolute steal at that price.
Now that you've installed JJupin, let's look at what has been added to your JIRA instance:
This allows you to use SIL scripts in JIRA workflow conditions. I recommend you create the SIL script and edit it through the SIL Manager (covered later) as opposed to always going into draft mode. Not only will this save you time, but if you go through draft mode, a copy of the SIL script will be created each time you save, thus polluting your file system with useless copies.
You can write your SIL script directly from the workflow, but I recommend you use the SIL Manager instead. Note that the extension .sil will be automatically added to whatever name you give your script, even if you include .sil yourself, so watch out for that.
This allows you to use SIL scripts in JIRA workflow validators. The same best practice I mentioned for conditions applies here.
This allows you to use SIL scripts in JIRA workflow post-functions. The same best practice I mentioned for conditions applies here.
Note that the order where you place your SIL script can have a huge impact on what happens. You will usually want to place after the Re-index an issue to keep indexes in sync with the database JIRA post-function, but you may choose to place it earlier. If you insert a (k) SIL Post-function on the original Create transition, you will absolutely need to move it after the Creates the issue originally post-function.
JJupin also adds a new gadget that allows you to run SIL scripts directly from a JIRA dashboard. This is especially useful to launch one-time migration or update / corrective scripts. I also use it to test my workflows, instead of having to create an issue and then transition it manually.
Once you add the JJupin Gagdet, you will need to Edit it in order to add some scripts. It is important to note that only JIRA Administrators and System Administrators may configure this gadget. Also, its configuration is "Global" meaning there is only one JJupin Gadget per JIRA instance. On the other hand you can and should configure script security to make sure the execution of important scripts are limited to administrators or even certain users.
JIRA Administration -> Add-ons -> Kepler Tools
The Kepler Workflow Viewer allows you to see an entire workflow in one screen. You'll see all the conditions, validators and post-functions of the JIRA workflow, and if you are using SIL, you have the option to show the SIL script directly in that view. I find it's a great way to review a workflow that has been coded by one of my colleagues, and saves a lot of clicks. Here is an example I generated for the default JIRA workflow.
The SIL Program Manager is where you'll spend your time coding SIL scripts. For a browser text-editor, it is fairly decent and allows you check your scripts for basic errors, and has basic text editor functionality such as find and replace. My only real complaint is that it lacks a full-screen view, which can cause problems when editing large scripts or when hitting backspace when you're outside the editor... which causes your browser to go back, and makes you lose all your unsaved changes. Still happens to me every now and then.
Of course, you can use any text editor you like and edit SIL scripts too. In my work, I don't always have access to the file system of the JIRA server so I'll take whatever competent editor I can get !
The SIL Services screen allows you to manage JIRA services that call SIL scripts. Actually, it's a nice layer on top of the existing JIRA Services screen in the JIRA Administration. To add a SIL service, you'll need (1) to give it a name, (2) to specify which user you'll run it as (Pro-tip: Use an administrator! You can always switch to another user during the script execution) (3) specify an interval in minutes (no cron expressions sorry!) (4) and the SIL script. I like how there's always to SIL script explorer to help you find files, rather than specifying the full path yourself.
The SIL Listener Manager allow you to create listeners that execute SIL scripts. This can be very useful if you wish to implement your own notifications messages. To create a SIL Listener, you'll need to (1) select a JIRA event (2) select which user to run the SIL Script as (3) select the SIL script you want to execute when the JIRA event is raised.
Here's a real-word example of a SIL Listener: In JIRA, the Issue Updated event is raised whenever an issue is edited, regardless of the field that was changed. Now, let's say we want to send a notification ONLY if some custom field called Issue Reviewer has changed. In JIRA that's not possible, but with a SIL Listener you can catch the event and check if the Issue Reviewer field has changed and send an email to the new Issue Reviewer. I'll share the example at some point in the future, but if you're interested, leave a comment and I'll do it quicker.
The Custom Field Usage screen allows you to see where your custom fields are used. You select a custom field, and you'll get the list of all the screens where it is used, as well as all the SIL scripts where the custom field is used. This proves to be invaluable if you're looking to measure the impact of renaming a custom field or changing its context. Make sure you use it !
If you're a keen observer, you'll see the screenshot mentions SIL Aliases. I'll address aliases in another upcoming post.
JIRA Administration -> Add-ons -> Kepler Plugins Configuration
This section is not reserved to JJupin, other plugins from Kepler Rominfo use it as well. Regardles, these are the screens that are available when you install the JJupin plugin.
The Katl-commons Configuration screen allows you to configure the Common Asynchronous Runner, which is used for asynchronous tasks submitted by certain features of SIL. It also allows you to output the Raw Parameters Page, which is an additional generic page containing all configuration parameters for all plugins in a raw format. I haven't encountered much use for them yet.
The SIL Configuration page let's you control global properties of the SIL language.
The Charset property is super important if you'll be using international characters in your scripts. As someone who works in English and French, I always use the UTF-8 encoding.
The Email Templates Directory property determines where email templates will be stored on the file system. If you keep the default value, email templates will stored in JIRA_HOME/kepler/emails, which is as good a place as any other as far as I'm concerned, since you cannot organize email templates in subfolders.
The Default Email language property determines which language is used when using kepler email templates, because YES these babies support i18n internationalization, a topic I hold dear as you can see. You can select either Sender Language or Receiver Language.
The Email Sender property allows you to select the email channel that SIL will use when sending emails. Either use the Direct Sender or the JIRA Mail Queue.
SIL Tree Caching
I won't go into too much details about SIL Tree Caching. It essentially caches scripts to get a performance boost of around 50 percent. Good to use on your production JIRA instance, but obviously can be counter-productive in development / staging.
SIL Programming Warnings
If you turn on Enable Warning Report, a report will be printed in the logs showing any warnings found during execution of a SIL script. Useful for debugging.
The Configuration for the Redirect SIL Script page allows you to configure the Kepler Redirect module, also known as KRedi. The KRedi service is called by using the URL <base_url>/secure/KRedi.jspa and passing it request parameters. This can be super useful when you want to send some information from another system to JIRA. There's a lot to be said about KRedi, enough to warrant its own blogpost... later !
The Remote Systems Configuration allows you to setup access to remote JIRA systems that also have JJupin installed. Then you'll be able to use their local SIL REST service provided by katl-commons by using call routine and passing the system's name as a parameter.
Same thing as the REST Cofniguration page, but for SOAP Services.
This very important screen will allow you to setup your LDAP configuration and be able to use the ldapUserRecord routine to interface directly with your LDAP or Active Directory. If your AD is well kept, you'll be able to find someone's manager or phone number directly from a SIL script. This allows for some seriously powerful workflow automation.
The JJupin screen, also known as Kepler parameters for the JJUPIN plugin allows you to manage other files besides your SIL script. This includes email templates, sil.aliases for alias definition and sil.properties for global properties you can use in SIL scripts. It works like the SIL Manager we saw earlier, it just shows you different files.
Another big chunk of JJupin, Live Fields allows you to hide, disable or set the values for JIRA fields through scripts. Again, this is big enough to warrant its own series of blog posts, but the general idea is to intercept certain events and make some changes to the UI. It's pretty powerful stuff.
This page lets you set up custom field descriptors, which are used to translate the custom field value into a valid SIL value. You will need to have a look at this page if you're using Custom Fields that have special types, like custom fields added from other plugins.
The Advanced configuration for JJupin screen allows you to control the asynchronous runner, in others word to set (1) the number of threads to be initialized by the thread pool for asynchronous operations, (2) the maximum running time for a SIL script (Time to live), where a script that takes more than the maximum allowed time to run will be killed and end with no result and (3) the time interval between cleanup actions on the threads that exceeded the Time to live.
The Kepler Licenses screen allows you to see and manage Kepler licenses installed in your kepler home directory. If you bought JJupin through the Universal Plugin Manager, you will have no use for this screen.
I believe this is a legacy screen that was used before the Atlassian Universal Plugin Manager came to be. You can probably ignore it.
Phew ! That's it ! To be honest when I started writing this post I didn't think there'd be so much to say about JJupin for an introduction post. I took a while to write but I feel it gives a great overview on all the JJupin offers. It really is an amazing JIRA plugin and I hope you enjoy it as much as I do.
This blog post is based off of JJupin version 2.6.8 installed on JIRA 6.2.2