Scripts setup

Adding SIL aliases

The following SIL aliases need to be added for each of the custom fields used by this integration. In order to do that, follow the steps below.

1. Go to Jira administration > Manage apps > SIL Manager.
2. Select 'SIL Aliases' tab on the right hand side of the SIL Manager window and click the '+' icon to add a new entry. 
   

3. Add the following aliases: 

   Alias	Custom Field
   absenceType	Absence Type
   reason	Reason/Comment
   manager	Manager/Approver
   startDate	Start date
   endDate	End date

   It may happen for your Jira instance to have more than one field named Start date or End date. In this case, identifying the right ids of BigPicture Start and End date fields from the 'SIL Aliases' tab will rather be tedious. Instead, you may use the following method.

   • Go to Jira administration > Issues > Custom fields.
   • Search for the date field (look for description field used by SoftwarePlant plugins). 
   • Click on the cog wheel icon and hover over 'Configure'. The custom field id should show up in the address at the very bottom of the page. 

   
   Once done with adding aliases, the mapping will be displayed as pairs of aliases and respective custom field ids. 
   

Creating file tree

1. Navigate to Jira administration > Manage apps > SIL Manager.
   
2. Right click on the 'silprograms' folder, click on 'New' and select 'File'. 
   
3. Name it "createFiles.sil" and click the tick to apply changes. 
   
   

4. Copy the below code and paste it over to the script field. 
   
   

   createDirectory("BigPicture");
   createDirectory("BigPicture/Absences");
    
   string [] files = "functions.incl|structs.incl|types.csv";
   for(string f in files) {
       createFile("BigPicture/Absences/" + f);
   }
    
   createDirectory("BigPicture/Absences/Workflow");
    
   files = "assignManager.sil|recordAbsence.sil|validator.sil";
   for(string f in files) {
       createFile("BigPicture/Absences/Workflow/" + f);
   }

   
   

5. Click on a green button to run the code.  
   
   You should see the following confirmation afterwards.
   
6. Right click on the 'silprograms' folder again and hit 'Refresh'. 
   
   The following folder tree along with some empty script files should be created.
   
7. Use the right click and the 'Delete' option to remove the 'createFiles.sil' script as it is no longer needed. Click 'OK' when prompted to confirm the action.   
   

Configuring Workflow and Absences scripts

Each script can be opened e.g. in TextEdit (for Mac) or any other text editor.

assignManager.sil (download file)

1. Once opened in a text editor, copy the script text and paste it into the corresponding file from under the 'Workflow' folder in the SIL Manager. 
   
   
2. Make sure to save the changes.
   You should be presented with a green 'Save done' text afterwards.
   

recordAbsence.sil (download file (BigPicture 8.0.X - 8.2.X) | download file (BigPicture 8.3.X and later))

1. Once opened in a text editor, copy the script text and paste it into the corresponding file from under the 'Workflow' folder in the SIL Manager. 
   
   
2. Hit '⌘ + f' (for Mac) to use the search and type customfield_XXXXX. There should be 5 items found.  
   
   

3. Click on the 'SIL Aliases' tab on the right. Then, for each of the custom fields from the code lines below, find their ids and swap with XXXXX in the script code.
   

   Code line	SIL alias
   date start = toTimeZone(customfield_XXXXX, "GMT+1")	startDate
   a.typeId = types[customfield_XXXXX].id	absenceType
   a.startDate = formatDate(toTimeZone(customfield_XXXXX, "GMT+1"), dateFormat)	startDate
   a.endDate = formatDate(toTimeZone(customfield_XXXXX, "GMT+1"), dateFormat)	endDate
   a.comment = customfield_XXXXX	reason

   
   For example, for Start date, this should look like below. 
   
   

4. Once you have these XXXXXs all swapped with custom field ids, save the script.
   
   
   You should be presented with a green 'Save done' text afterwards.
   

validator.sil (download file)

1. Once opened in a text editor, copy the script text and paste it into the corresponding file from under the 'Workflow' folder in the SIL Manager.
   
   
2. Make sure to save the changes.
   
   You should be presented with a green 'Save done' text afterwards.
   

types.csv (download file)

1. Once opened in a text editor, copy the text and paste it into the corresponding file from under the 'Absences' folder in the SIL Manager.
   
   
2. Make sure to save the changes.
   
   You should be presented with a green 'Save done' text afterwards.
   

structs.incl (download file)

1. Once opened in a text editor, copy the script text and paste it into the corresponding file from under the 'Absences' folder in the SIL Manager.
   
   
2. Click on a green button to run the code.  
   
   You should see the following confirmation afterwards.
   
3. Make sure to save the changes.
   
   You should be presented with a green 'Save done' text afterwards.
   

functions.incl (download file (BigPicture 8.0.X - 8.2.X) | download file (BigPicture 8.3.X and later))

1. Once opened in a text editor, copy the script text and paste it into the corresponding file from under the 'Absences' folder in the SIL Manager.
   

2. In the highlighted two lines, swap the default credentials (dastin/Pas$$word) with the username and password of a Jira user that will be used to make the REST calls to BigPicture. 
   

   It is recommended that a new Jira user with Jira System Administrators or Jira Administrators global permission be created as a service account so that password changes do not impact the functionality of this script.

   
   

   For the purpose of this user manual, we used Jira admin account. 
   
3. Click on a green button to run the code.  
   
   You should see the following confirmation afterwards.
   
   Once this script has been run successfully for the first time the username and password used will be stored permanently as a persistent variable. This can be seen in the 'Persistent vars' tab on the right hand side of the SIL Manager.
   
   As soon as you confirm that these are stored there, you can modify the script to not have the credentials visible in the code itself. For this we used getPersistentVar routine.
   
   
4. Make sure to save the changes. 
   
   
5. You should be presented with a green 'Save done' text afterwards.