Interact With the ATLASSIAN Jira Software From Within z/OS
In this tutorial from BMC's Subhasish Sarkar and Sujit Neb, learn how to interact with ATLASSIAN Jira from a JCL Job that executes on z/OS
In this tutorial, we look at how we can interact with the ATLASSIAN Jira software product from a JCL Job that executes on z/OS. We are going to cover two simple scenarios—first, adding a comment to a Jira issue and then, reading the Jira issue and retrieve the comment previously added. We believe that these two scenarios will provide ample guidance and idea to the readers to try and cover other use-cases as deemed fit. The tutorial expects that the reader is familiar with the ATLASSIAN Jira software product concepts and has experience using it.
Step 1: Python Script That Adds a Comment to a Jira Issue
We start with coding a Python script that adds a comment to a Jira issue. Let us name the Python Script “Add_comment.py.” It is assumed here that the reader uses a machine running Microsoft Windows OS. The script can be saved anywhere on the local machine. We have saved our script on the desktop. The script will look something like this (see Figure 1):
Figure 1. Python script code to add a comment to a Jira issue
The script makes use of different requests and json Python module entities. We make use of the Jira Software REST API [[https://jira.your-domain.com/rest/api/2/issue/ZENG-231320/comment ]], to add a specific comment to a particular Jira issue (ZENG-231320 in our case). The strings “UserID” and “Password” should be replaced with the user’s original user ID and a valid password used to access Jira. To learn more about the Jira Software REST APIs, click here.
Step 2: Test the Python Script ‘Add_comment.py’
To ensure that the Python script works as expected, execute the script from your Windows command prompt or any terminal that you are comfortable using. CD to the location where your script has been saved and execute the command python “Add_comment.py.” If the script executes successfully, you should see the message “A comment has been added to the JIRA issue …” on the console window, and the comment “Test Comment 01” should get added to the Jira issue (see Figure 2).
Figure 2. Console Output resulting after the successful execution of the Python Script ‘Add_comment.py’
Note the following line in the console output:
“self”: “https://zsojira.bmc.com/rest/api/2/issue/360612/comment/1389013”,
We are interested in the Comment ID 1389013 because we need it in the next step when we try to extract the comment from the Jira issue (see Figure 3).
Figure 3. The comment gets added to the Jira issue after the successful execution of the Python script ‘Add_comment.py’
Step 3: Python Script That Extracts a Comment From a Jira Issue
Next, we code a Python script that extracts a comment from a Jira issue. We are going to extract the same comment that we had previously added to the Jira issue. Let’s name the second Python script “Get_comment.py.” The script can be saved anywhere on the local machine, preferably in the same location where the first Python script has been stored for convenience. We’ve saved our script on the Desktop. The script will look something like this (see Figure 4):
Figure 4. Python script code to extract a comment from a Jira issue
We specify the Comment ID 1389013 in the Jira Software REST API [[https://jira.your-domain.com/rest/api/2/issue/ZENG-231320/comment/1389013 ]]. The Comment ID 1389013 corresponds to the comment that we had previously added to the Jira issue. We are trying to extract the same comment here. The strings “UserID” and “Password” should be replaced with the user’s original user ID and a valid password.
Step 4: Test the Python Script ‘Get_comment.py’
It’s now time to test our script. If the script executes successfully, you should see the message “The comment previously inserted into the Jira issue has been successfully retrieved !!!” on the console window, followed by the extracted comment text (see Figure 5).
Figure 5. Console output resulting after the successful execution of the Python script “Get_comment.py”
Step 5: Code a JCL Job That Executes the Python Script ‘Add_comment.py’
We’re now going to code our JCL Job that will execute the Python script “Add_comment.py” to add a comment to a Jira issue.
//JIRAADDC JOB (5990),'EXECUTE-PYSCRIPT',CLASS=A,MSGCLASS=X, // REGION=0M,NOTIFY=&SYSUID //***************************************************************** //BPXBTCH1 EXEC PGM=BPXBATCH //STDPARM DD DISP=SHR, // DSN=YOUR.PDS(ADDCMTPY) //STDOUT DD SYSOUT=* //STDERR DD SYSOUT=* //CEEDUMP DD DUMMY //* //
Content of the ‘YOUR.PDS(ADDCMTPY)’ member should be:
sh python3 /home/user/Add_comment.py
NOTE: python3 is the Python installation path; for example, /usr/lpp/IBM/cyp/v3r8/pyz/bin/python3. Check with your system administrator if you’re not sure about the path where Python installation has been done at your shop.
/home/user/ is the USS path in which we are going to create the Python file, Add_comment.py. You can reuse the code in the Python script that you have already created and saved on your local Windows machine.
BPXBATCH is a utility that is used to run shell commands or executable files through the batch facility. You can invoke BPXBATCH from a batch job, as we have chosen to do in our case. To know more about the BPXBATCH utility, you can refer to the IBM documentation at BPXBATCH utility – IBM Documentation.
Step 6: Submit the JCL Job That Executes the Python Script ‘Add_comment.py’
It’s now time to submit the JCL Job that executes the Python script “Add_comment.py” to add a comment to a Jira issue. The Job is expected to complete its execution successfully and once that has been done, check the STDOUT DD output. You should see the “A comment has been added to the JIRA issue …” success indicator message. You should be able to see an output something like the one listed below:
{
"author": {
"active": true,
"avatarUrls": {
"16x16": "https://jira.your-domain.com/secure/useravatar?size=xsmall&ownerId=JIRAUSER35690&avatarId=22018",
"24x24": "https://jira.your-domain.com/secure/useravatar?size=small&ownerId=JIRAUSER35690&avatarId=22018",
"32x32": "https://jira.your-domain.com/secure/useravatar?size=medium&ownerId=JIRAUSER35690&avatarId=22018",
"48x48": "https://jira.your-domain.com/secure/useravatar?ownerId=JIRAUSER35690&avatarId=22018"
},
"displayName": "Sarkar, Subhasish",
"emailAddress": "abc@xyz.com",
"key": "JIRAUSER35690",
"name": "sxxxxxxa",
"self": "https://jira.your-domain.com/rest/api/2/user?username=sxxxxxxa",
"timeZone": "Asia/Kolkata"
},
"body": "Test Comment 01",
"created": "2021-08-06T06:06:00.548-0500",
"id": "1389630",
"self": "https://jira.your-domain.com/rest/api/2/issue/360612/comment/1389630",
"updateAuthor": {
"active": true,
"avatarUrls": {
"16x16": "https://jira.your-domain.com/secure/useravatar?size=xsmall&ownerId=JIRAUSER35690&avatarId=22018",
"24x24": "https://jira.your-domain.com/secure/useravatar?size=small&ownerId=JIRAUSER35690&avatarId=22018",
"32x32": "https://jira.your-domain.com/secure/useravatar?size=medium&ownerId=JIRAUSER35690&avatarId=22018",
"48x48": "https://jira.your-domain.com/secure/useravatar?ownerId=JIRAUSER35690&avatarId=22018"
},
"displayName": "Sarkar, Subhasish",
"emailAddress": "abc@xyz.com",
"key": "JIRAUSER35690",
"name": "sxxxxxxa",
"self": "https://jira.your-domain.com/rest/api/2/user?username=sxxxxxxa",
"timeZone": "Asia/Kolkata"
},
"updated": "2021-08-06T06:06:00.548-0500"
}
A comment has been added to the JIRA issue ZENG-231320 !!!
You will also find that the comment has been added to the Jira issue (see Figure 6).
Figure 6. The comment gets added to the Jira issue after the successful execution of the JCL Job that executes the Python script “Add_comment.py”
Also, don’t forget to note down the Comment ID. We’ll be extracting next the same comment that was just added. You can grab the Comment ID from the STDOUT DD output from either of the following two lines:
"id": "1389630", "self": "https://jira.your-domain.com/rest/api/2/issue/360612/comment/1389630",
The Comment ID in our case is 1389630.
Step 7: Code a JCL Job That Executes the Python Script ‘Get_comment.py’
We’re now going to code our JCL Job that will execute the Python script “Get_comment.py” to extract a comment from a Jira issue.
//JIRAGETC JOB (5990),'EXECUTE-PYSCRIPT',CLASS=A,MSGCLASS=X, // REGION=0M,NOTIFY=&SYSUID //***************************************************************** //BPXBTCH1 EXEC PGM=BPXBATCH //STDPARM DD DISP=SHR, // DSN=YOUR.PDS(GETCMTPY) //STDOUT DD SYSOUT=* //STDERR DD SYSOUT=* //CEEDUMP DD DUMMY //* //
Content of the ‘YOUR.PDS(GETCMTPY)’ member should be:
sh python3 /home/user/Get_comment.py
Create the Python file, Get_comment.py at the USS path /home/user. You can reuse the code in the Python script that you have already created and saved on your local Windows machine. Just remember to plug in the correct Comment ID (1389630 in my case) that you had noted down in the previous step.
url = https://jira.your-domain.com/rest/api/2/issue/ZENG-231320/comment/1389630
Step 8: Submit the JCL Job That Executes the Python Script ‘Get_comment.py’
Submit the JCL Job that executes the Python script “Get_comment.py” to extract a comment from a Jira issue. The Job should complete its execution successfully and once that has been done, check the STDOUT DD output. You should see the “The comment previously inserted into the Jira issue has been successfully retrieved” success indicator message. You should also see the extracted comment text. You should be able to see an output something like the one listed below:
{
"author": {
"active": true,
"avatarUrls": {
"16x16": "https://jira.your-domain.com/secure/useravatar?size=xsmall&ownerId=JIRAUSER35690&avatarId=22018",
"24x24": "https://jira.your-domain.com/secure/useravatar?size=small&ownerId=JIRAUSER35690&avatarId=22018",
"32x32": "https://jira.your-domain.com/secure/useravatar?size=medium&ownerId=JIRAUSER35690&avatarId=22018",
"48x48": "https://jira.your-domain.com/secure/useravatar?ownerId=JIRAUSER35690&avatarId=22018"
},
"displayName": "Sarkar, Subhasish",
"emailAddress": "abc@xyz.com",
"key": "JIRAUSER35690",
"name": "sxxxxxxa",
"self": "https://jira.your-domain.com/rest/api/2/user?username=sxxxxxxa",
"timeZone": "Asia/Kolkata"
},
"body": "Test Comment 01",
"created": "2021-08-06T06:06:00.547-0500",
"id": "1389630",
"self": "https://jira.your-domain.com/rest/api/2/issue/360612/comment/1389630",
"updateAuthor": {
"active": true,
"avatarUrls": {
"16x16": "https://jira.your-domain.com/secure/useravatar?size=xsmall&ownerId=JIRAUSER35690&avatarId=22018",
"24x24": "https://jira.your-domain.com/secure/useravatar?size=small&ownerId=JIRAUSER35690&avatarId=22018",
"32x32": "https://jira.your-domain.com/secure/useravatar?size=medium&ownerId=JIRAUSER35690&avatarId=22018",
"48x48": "https://jira.your-domain.com/secure/useravatar?ownerId=JIRAUSER35690&avatarId=22018"
},
"displayName": "Sarkar, Subhasish",
"emailAddress": "abc@xyz.com",
"key": "JIRAUSER35690",
"name": "sxxxxxxa",
"self": "https://jira.your-domain.com/rest/api/2/user?username=sxxxxxxa",
"timeZone": "Asia/Kolkata"
},
"updated": "2021-08-06T06:06:00.547-0500"
}
The comment previously inserted into the Jira issue ZENG-231320 has been successfully retrieved !!!
Extracted comment:
Test Comment 01
This concludes the tutorial. To summarize, we looked at how to interact with the ATLASSIAN Jira software product from within z/OS. We’ve seen how we can add a comment to a particular Jira issue and then extract the same comment from the Jira issue. You can use these concepts and methods to try out other use-cases as deemed necessary.