Hello! Alexey Matveev here.

We all know and love SIL® (Simple Issue Language®) because its routines let us automate our actions in Atlassian Jira and Confluence. We write our routines in the SIL® Manager menu option, but most of us don’t use the other menu options that are available for SIL®. Let’s fix that.

Here are all these menu options:

How to use SIL to the maximum

All these options are available for the SIL® Engine, which means it is all free for you.

Custom Field Usage

This menu option provides information on how each custom field is used in your Jira. The vendor’s information is available here.

You can find all custom fields in the cog item -> Issues -> Custom Fields menu.

How to use SIL to the maximum

Here is how the screen looks if you click the Custom Field Usage menu option:

How to use SIL to the maximum

You can see that you have a select field called Custom Field, which contains the list of all custom fields in your Jira. The list shows a limited amount of custom fields, which is why you can start typing the name of the custom field you need, and the list will be filtered by the letters you typed:

How to use SIL to the maximum

After you select the field, you need to click on it:

How to use SIL to the maximum

You can see the SIL aliases for the field, screens, and projects where the field is used and also the lines of code where the custom field is used.

At the moment of writing this article, there is an open bug CADS-6237 which says that the References part is not showing lines of code where the custom field is used. That is true. I had to modify the code of the SIL engine to make the References part work properly for this article, which is why in the screenshot above, the References part contains rows with scripts where the custom field is used.

Redirect Page Configuration

This menu option lets you make a smart redirection to Jira pages. I spent a couple of hours understanding why we need this feature and how to use it. I feel that it is better to explain this feature with an example.

Suppose each employee files invoices each month in Jira.

How to use SIL to the maximum

As you can see, Alexey Matveev filed two invoices for March and April.

But HR works in an external system where the payment is made, and in this external system, HR officer must be able to see the latest invoice, which was filed in Jira, for each employee.

Of course, this HR officer can log in to Jira, open Issue Navigator, and filter all issues in the Invoices project by employee ordered by the Invoice Date custom field in descending order, and the first invoice will be the latest invoice.

How to use SIL to the maximum

But it is a too complicated approach. We would like to be able to access the latest invoice by a link in our HR system.

In our HR system, we can make the link look like this:

How to use SIL to the maximum

As you can see we call the plugins/servlet/kredi servlet which will do smart redirection for us and also we pass Alexey+Matveev as the user name parameter which will tell the servlet for which user we need the latest invoice.

Now we need to make our servlet smart. Open the Redirect Page Configuration menu and enter the following code:

How to use SIL to the maximum

The script does the following:

we take the value of the userName parameter which was passed in the URL.
we check if the userName parameter was really passed. If it was not passed we redirect to the error page with the message “Provide user with userName parameter”.
we check that a user with the user name exists in Jira. If not, we redirect to the error page with the message “User userName not found”.
we select the latest invoice for the user. If no invoices selected, we redirect to the error page with the message “No invoices for userName”.
we show the invoice page.

Well, let’s test it!

First, let’s make a link like this:

How to use SIL to the maximum

If we click on this link we will see the following screen:

How to use SIL to the maximum

Correct! We were redirected to my latest invoice.

Now let’s not pass the userName parameter:

How to use SIL to the maximum

And we were redirected to the error page:

How to use SIL to the maximum

Correct!

Now, let’s provide the user name who does not exist in Jira

How to use SIL to the maximum

We were redirected to the error page:

And now let’s provide a user without filed invoices:

How to use SIL to the maximum

Again we were redirected to the error page:

How to use SIL to the maximum

So, our program works correctly!

In short, we moved all logic for redirecting us to the correct page to Jira. And it is very handy because we can implement our logic with the SIL language which makes manipulation with Jira easy.

Switch User

This menu lets us work in Jira under any registered user in Jira without knowing the password of the user.

How to use SIL to the maximum

The list of users is limited but you can type letters in the User field and users will be filtered for you:

How to use SIL to the maximum

Click on the user you want to work under, push the Switch! button and you will be logged in as this user without providing the password of this user.

To return back to your user, you can use the Switch Back To option:

How to use SIL to the maximum

SIL® Configuration

This menu option lets you set configuration parameters for SIL.

How to use SIL to the maximum

SIL Home Directory lets you change the file folder where all SIL® scripts will be placed. By default, all scripts are placed in your JIRA_HOME/silprograms folder, but you can place the scripts into any folder you want under the JIRA_HOME folder.

Charset lets you define the character encoding for your scripts. I think it is better to leave it as it is UTF-8. Maybe you would need to change it if you save your SIL® scripts in the Jira database and somehow your database character set is not UTF-8. But I would say it is a very rare case. You should use UTF-8 in all your Jira settings.

SIL® Cache size lets you define the number of the parsed SIL scripts in the SIL cache.

Why would we need a SIL® cache at all?

Here is a simple script in SIL®:

How to use SIL to the maximum

In order to execute this script SIL® must convert this script to Java byte code. There are many different constructions in SIL® like structures, functions, inclusions, loops, conditions, assignments, variable type conversions and so on. All of it must be converted from SIL® code to Java byte code. And it all takes time. That is why once SIL® code is parsed the Java byte code is saved in the SIL® Cache to save your time on parsing this SIL® code again.

That is why if you have thousands of scripts it makes sense to try to increase this parameter and have a look if you have performance gain.

Datasources

This menu option lets you add database source which can be used later in your scripts. It is very handy because you do not need to hardcode database connection and user password in the code.

How to use SIL to the maximum

Let’s configure a database source and use it later in SIL® scripts.

Push the Add Datasource button and connect to an external database:

How to use SIL to the maximum

I put up a second Jira instance in my notebook and connected it to the database of the second Jira instance.

It is important to mention that SIL® does not contain JDBC drivers in its distribution that is why you need to make sure that you have an appropriate driver in your Jira instance. You can read here about adding JDBC drivers to Jira.

Now let’s push the Save button and we will have a new data source called external_database configured:

How to use SIL to the maximum

Now let’s use it in our SIL® script:

How to use SIL to the maximum

I executed an SQL query on my external database and received a result:

How to use SIL to the maximum

Mail Sender Configuration

It is a tricky one.

You can send an email with the sendEmail SIL® routine and this menu option lets you provide parameters for this routine.

How to use SIL to the maximum

Container Sender – sends a message by adding your email into the Jira mail queue.

How to use SIL to the maximum

And you can see the error and debug messages in the atlassian-jira-outgoing-mail.log if you have properly configured your logs. You can read more on how to configure email logging here. I prefer to use this option.

Direct sender, custom – you can define your own SMTP mail server:

How to use SIL to the maximum

You will not see the email message in the Jira mail queue or logs in the atlassian-jira-outgoing-mail.log file, but you will be able to see log messages in the atlassian-jira.log file.

Direct sender, default – you can use the SMTP server defined in Jira. The email message will be sent by SIL®. You will not see the email message in the Jira mail queue or logs in the atlassian-jira-outgoing-mail.log file, but you will be able to see log messages in the atlassian-jira.log file.
Null sender (log only) – the message will be written in the logs (it will not be sent to the receiver). But surprise, surprise! The level of the log is INFO, but the default log level for the com.keplerinfo package is ERROR. And as a result, no logs in the log file, no emails in the email box and this option is the default one. I spent an hour figuring out how to make everything work. Just add the INFO log level for the com.keplerinfo (more info here) or choose another option. Here is an example of a log message:

How to use SIL to the maximum

Asynchronous Runner

If you click on this menu option you will see the following screen.

How to use SIL to the maximum

Threads set the number of threads for the SIL® engine. By default, it is set to 10 which means that you can not execute more than 10 SIL® scripts concurrently. If you have many scripts running at the same time consider increasing this value.

Time To Live (TTL) sets the time for a thread to live. The default value is 1 hour. It means that if a script runs more than 1 hour it will be killed. If you have long-running scripts consider increasing this value.

Checkpoint Interval sets the time how often SIL® engine will check running threads and kill the threads if the threads have been running for more than TTL time.

Also, you can see all running tasks in the part of the Running task of the screen.

Remote Systems

The Remote Systems menu option lets you

Add connections to remote systems and call sil scripts from these remote systems.
Set permissions to call SIL scripts by SIL REST API.

How to use SIL to the maximum

Let’s first create a connection to a remote system and call a SIL® script from this remote system.

I have two Jira instances running on localhost:2990/jira and localhost:8080.

I have this SIL® script on localhost:8080 called test.sil:

How to use SIL to the maximum

This scripts accepts a parameter and logs an error message into the atlassian-jira.log file with a message which includes this parameter.

Now on localhost:2990/jira I go to cog item -> Manage Apps -> Remote Systems, push the Add Remote button, and provide data for my localhost:8080 Jira instance:

How to use SIL to the maximum

Now push the Save button and create a script on localhost:2990/jira which will call the test.sil from localhost:8080:

How to use SIL to the maximum

The first parameter is the name of our connection (my_ext_jira).

The second parameter is the name of the script which will be executed on the remote system.

The third parameter is the additional parameter which will be passed to our test.sil and we will take the value of this parameter as argv[0].

Now let’s run the script and have a look at the logs on localhost:8080. We will see the following line:

How to use SIL to the maximum

It means that we successfully called a SIL script on localhost:8080 from localhost:2990/jira.

Next, let’s have a look at the Security section of the Remote Systems menu option.

Suppose we have two scripts on our localhost:2990/jira.

test.sil

How to use SIL to the maximum

test1.sil

How to use SIL to the maximum

And also I have a user called user1 who does not have the Jira Administrator permission and I want this user to be able to execute inline scripts and SIL® scripts on the file system by SIL REST API.

Let’s go to Remote Systems:

How to use SIL to the maximum

We will be working with the Grant execute inline, Grand read and Grant execute buttons from the Security section.

First, let’s try to execute an inline script by user1.

How to use SIL to the maximum

With this JSON:

How to use SIL to the maximum

And we have the 403 Forbidden error.

Now let’s push the Grant execute inline button and add this grant to user1:

How to use SIL to the maximum

And now we got the 200 response which means that the script was executed successfully.

Now let’s try to execute the test1.sil file under user1. This time the JSON will look like this:

How to use SIL to the maximum

And we get the 403 Forbidden error. Now let’s permit user1 to execute the test1.sil file, push the Grant execute button:

How to use SIL to the maximum

Let’s execute the script and this time the response code is 200.

LDAP Configuration

You can provide a connection to your LDAP.

How to use SIL to the maximum

I ran a docker with a LDAP server from here.

How to use SIL to the maximum

Let’s push the Add LDAP button and configure our connection:

How to use SIL to the maximum

The only available option for the Directory field in Active Directory. But it does not mean that you can make a connection only to Microsoft Active Directory. You can use any LDAP server. In my case, I used open LDAP.

Now we can select data from this LDAP.

Let’s try to select data with the ldapUserList routine:

How to use SIL to the maximum

And I successfully chose the admin user from my LDAP.

How to use SIL to the maximum

Script Storage

This menu option lets you define where to store your SIL® scripts.

By default all SIL® scripts are stored in the file system (the disk option):

How to use SIL to the maximum

If you choose the database option all scripts will be stored in the AO_1B54DA_TSTEXT database table.

I believe that it is better to save your SIL scripts on the filesystem because in this case, you can store all your scripts in a version control system. For example, Bitbucket.

Custom Fields Mapping

You can map the values of custom fields in your Jira to SIL® values. You can find the Vendor’s information here.

How to use SIL to the maximum

For example, let’s have a look at the Checkboxes custom field. The value is mapped to the string[] SIL value which means that you can get a value from a checkbox field like this:

How to use SIL to the maximum

And you can set a value to a checkbox field like this:

How to use SIL to the maximum

You cannot change the mapping for the field because it is a standard Jira field and SIL® already provided the correct mapping for you.

Now please, pay attention to the Grid custom field (the second row in the red rectangle). This grid custom field goes from the Table Grid Next Generation add-on. SIL® does not provide a mapping for this field by default. That’s why it is mapped to the string value by default but you can change the mapping:

How to use SIL to the maximum

In some cases, any available out of the box mapping will not work correctly. In this case, you can develop a custom plugin for SIL® with your own mapping.

Integration Configuration

You can create connections to Slack and Stride here and then use these connections in your SIL® scripts.

SIL® Webhooks Configuration

You can create your own REST API in this menu option.

SIL® Diagnostic

This menu provides you with the overall information about your SIL® engine:

How to use SIL to the maximum

I believe that most of this information is needed for developers of the SIL® engine, but I would like to mention a very cool feature here.

You can see all SIL® threads and kill them.

Suppose, you wrote and ran a SIL® script that keeps executing and takes lots of CPU or memory resources. You can kill this thread from here.

How to use SIL to the maximum

You can see that I have a thread with TID 393 and I know that this script just takes resources, I do not need this thread. All I need to do is to push the kill button. And the thread will be killed.

Test this out and let us know if you have any questions!

How to maximize SIL® (Simple Issue Language)

Subscribe for updates