How Live Fields work

Contents

Live Fields

Live Fields is a Power Scripts for Jira extension that contains several routines for Simple Issue Language (SIL) used to do the following operations: hide, disable or set the values for Jira fields automatically, while editing or viewing the issue.

Live Fields can help you:

• restrict visibility on certain fields for certain users
• disable editing for certain fields
• change values in the other fields automatically when a field value changes

You can also call Live Fields routines from post functions, and not only from the main configuration script or hooks.

What's the idea? 

To understand how Live Fields work, we have to define some notions first:

• An action is the action executed on the screen. It can be hide, show, disable, and so on.
  Each action can be called from SIL using its corresponding routine (lfHide, lfShow, lfDisable, and so on).
• A hook script (or the callback script) represents a SIL script file that is executed when an event is triggered.
  You can create a hook using the  lfWatch routine.
• The main script (or configuration script) is the initial script executed when the view issue / edit issue is called. This is actually your entry point in the Live Fields.

Take a look at the following sequence diagram: 

As you can see, the sequence of operations is the following:

1. When the Jira issue page is loaded, the Live Fields Configuration for the issue project is retrieved and the Main Script is executed.

Note: the Main Script represents the SIL Script file from the Live Fields Configuration of the issue project. The Main Script contains the actions and the hooks that will be executed every time an issue page is loaded. The main script can be associated with many projects, to ease the configuration for projects having similar screens. Not all pages in Jira trigger Live Fields main script (explained below).

     2.  After the Main Script is executed, the hooks will be registered and the results will be sent to the browser where the actions will apply. 

Note: An action is represented by the live fields routines that changes the fields state, like lfHide/lfShow, lfDisable/lfEnable. A hook represents a SIL Script file that is executed when an event is triggered; hooks are created using the lfWatch routine.

     3. When a user interacts with an element (Jira field) that has a hook registered for it, the event is triggered and the Hook Script is executed.

Note: The Hook Script can also contain actions and hooks. The difference is that the actions from the Hook Script are executed only in the current screen (the screen where the event was triggered).

Screens where we can use Live Fields

Note that Live Fields can only be used in certain screens. You cannot use Live fields for the administration pages of Jira, for instance.

The following table summarizes the screens loading the Live Fields main script (configuration):

As a general note, you should not worry if you are requesting an action for a field that is not on the screen. Live Fields is smart enough to skip over the non-existent fields.

If necessary, arbitrary javascript, residing in the silprograms folder on the server, can be executed on any above screen. However, try to minimize the amount of javascript, since it makes your Jira install non-portable across versions of Jira.

Example

Let’s say you want to set the priority of the issue to "Major" when the summary contains the word "important".

Writing the code

Create the Main Script.

1. Go to Administration > Add-ons > SIL Manager.
2. Click the silprograms folder and the New > New file button. 
3. Create a new SIL file and name it MainScript.sil like in the image below. This is the Main Script and we will configure it later.
   
   
   

4. In the MainScript.sil file that you create write the following code:

   MainScript.sil

    lfWatch("summary", {"summary"}, "HookScript.sil" , {"keyup"}); 

5. When entering on the issue page, the MainScript.sil will run and attach a listener for the keyup event, for the summary field. When the event is triggered the script from the HookScript.sil is run.

Next, let's create the HookScript.sil file in the way you created the MainScript.sil. Write the following code in the HookScript.sil file:

 if (contains(argv["summary"], "important")) {
   lfSet("priority", "Major");
   lfShowFieldMessage("priority", "Priority changed", "INFO");
 }

You can find more information about managing your SIL Scripts on the SIL Manager page.

Creating a Live Field Configuration

So, we have created two scripts, but before testing them we have to create a Live Field Configuration and associate it to a project.

To do this, follow the next steps:

1. Go to Administration > Add-ons > Live Fields.
   
    
2. 
   
   
3. Click the Add Live Fields button.
4. In the displayed dialog box:
   1. Enter the configuration name and description
   2. Select a SIL File for the Live Fields Configuration
   3. Select the project(s) to associate the configuration with. The Main Script represents the SIL Script file from the Live Fields Configuration, so let's choose it for our configuration:
      
      
      
   4. 
      
      
5. Click the Add button and the Live Field Configuration will be created.
   

Summary

You have created two scripts, the MainScript.sil and the HookScript.sil.

You have created a Live Fields Configuration that contains the MainScript.sil and associated it with a project (with TEST, in our case).

Result

Every time we enter an issue page of the TEST project, the MainScript.sil is executed and the hook is registered. When we edit the issue summary, the keyup event is triggered and the HookScript.sil is executed.

You can find more information about Live Fields Configuration here.

Let's test it!

On the edit screen of the issue, start typing the summary for the issue. Every time the event keyup is triggered a call to the server is made and the HookScript.sil is executed. The server receives the values of the related fields (the second parameter from the lfWatch routine), in our case the value of the summary field.

For example, we have the following issue:

We start editing the summary field:

We typed " imp", so the event was triggered three times. That means the HookScript.sil was executed three times, and it received the following values for summary field: "test ",  "test i", "test im". This are the values passed from argv["summary"].

When the Summary field contains the word "important", the priority will be set as "Major" and a message will be displayed.

A Note on Performance

Because of the nature of the Live Fields, please abstain of doing lengthy operations, especially in hooks. Over the years, we have seen users doing database lookups, calling external systems and other such digital endeavors. In the above example, you need to imagine that the hook is called N times, and if you executed an SQL inside of that hook, that SQL will be called N times.

Keeping your footprint low means happy users!

See also

• Live Fields Routines
• More information about SIL programs – Simple Issue Language documentation