Search and retrieve folder information

The following script will search for project tree folders and retrieve detailed information for the found elements.

In this example, the script will look for the folder element in the path <GUI Specifications/Login Page/Icons>. A recursive method will then print the information of the folder elements returned by the POST request.

Function to search tree element
def search_tree_element(host_url, username, password, project_key, element_path):
    """
    This method is used to search for tree elements
    Template parameters:
    [project_key] the project key
    Query parameters:
    [element_path] the path to search in
    """

    # The REST API path to search for tree elements
    path_uri = '/rest/com.easesolutions.jira.plugins.requirements/1.0/search/' + project_key + '?'

    # The field-value pair/s that will be added to the query string
    element_path_field_value = 'path=' + element_path

    # The query string to be added to the URI
    query_string = element_path_field_value

    # Send a GET request to search for tree elements
    # Return result of the GET request
    try:
        return requests.get(host_url + path_uri + query_string, auth=HTTPBasicAuth(username, password))
    except requests.exceptions.RequestException as e:
        print e
Function to print folder structure
def print_folder_structure(folders):
    # If folder has values then print the information of the folder
    if folders:
        for folder in folders:
            print '\n%s %s' % ('Display name: ', folder['name_display'])
            print '%s %s' % ('Folder ID: ', folder['id'])
            print '%s %s' % ('Parent folder ID: ', folder['parent'])

            # Perform recursion if there is a folder under this folder
            sub_folders = folder['folders']
            print_folder_structure(sub_folders)
Main
# ['SC'] project key parameter for the project to search the element
# ['GUI Specifications/Login Page/Icons'] the path parameter of the element to search
# Store the result of the POST request to [response]
response = search_tree_element(HOST_URL, USERNAME, PASSWORD, 'SC', 'GUI Specifications/Login Page/Icons')

# Check response if element info is returned
if response.status_code == 200:

    # Get the value of the JSON response
    # Pass the result to print_folder_structure method to print the folder structure of the found element
    json_object = json.loads(response.text)
    folders = json_object['folders']
    print_folder_structure(folders)

else:
    print 'Error code: ', response.status_code
    print response.text

Refer to Constant variable for information of the following constant variable: [HOST_URL, USERNAME, PASSWORD]

Output
Display name:  GUI Specifications
Folder ID:  242
Parent folder ID:  -1

Display name:  Login Page
Folder ID:  260
Parent folder ID:  242

Display name:  Icons
Folder ID:  262
Parent folder ID:  26


{
  "folders": [
    {
      "name": "GUI Specifications",
      "description": "",
      "id": 242,
      "name_display": "GUI Specifications",
      "parent": -1,
      "folders": [
        {
          "name": "Panel UI",
          "description": "",
          "id": 245,
          "name_display": "Panel UI",
          "parent": 242,
          "folders": [
            {
              "name": "FAX",
              "description": "",
              "id": 244,
              "name_display": "FAX",
              "parent": 245,
              "folders": [],
              "issues": [],
              "position": 1
            }
          ],
          "issues": [],
          "position": 1
        }
      ],
      "issues": [],
      "position": 1
    }
  ],
  "issues": []
}





Create folder structure

The following script will create a folder structure by using several project tree web services.

In this example, the script will create  the following folder structure on the root of the project:

  • GUI Requirements
    • Login Page
    • About Us
    • Home Page

It will then get the tree structure of the project using another web service and print the information of the current tree structure.

Function to create a folder under project root
def create_folder_on_project_root(host_url, username, password, project_key, folder_name, folder_description):
    """
    This method is used to create a new folder on project root
    Template parameters:
    [project_key] the project key
    Query parameters:
    [folder_name] the name of the new folder
    [folder_description] optional description of the new folder
    """

    # The REST API path to create a folder on project root
    path_uri = '/rest/com.easesolutions.jira.plugins.requirements/1.0/tree/' + project_key + '/folder?'

    # The field-value pair/s that will be added to the query string
    project_name_field_value = 'name=' + folder_name
    project_description_field_value = '&description=' + folder_description

    # The query string to be added to the URI
    query_string = project_name_field_value + project_description_field_value

    # Send a POST request to create a folder in root in the Requirements
    # Return result of the POST request
    try:
        return requests.post(host_url + path_uri + query_string, auth=HTTPBasicAuth(username, password))
    except requests.exceptions.RequestException as e:
        print e
Function to create a folder below a specified folder
def create_folder_on_specified_folder(host_url, username, password, project_key, folder_id,
                                      folder_name, folder_description):
    """
    This method is used to create a new folder under a specified folder
    Template parameters:
    [project_key] the project key
    [folder_id] the ID of the parent folder
    Query parameters:
    [folder_name] the name of the new folder
    [folder_description] optional description of the new folder
    """

    # The REST API path to create a folder on a specified folder
    path_uri = '/rest/com.easesolutions.jira.plugins.requirements/1.0/tree/' + \
               project_key + '/folder/' + str(folder_id) + '?'

    # The field-value pair/s that will be added to the query string
    project_name_field_value = 'name=' + folder_name
    project_description_field_value = '&description=' + folder_description

    # The query string to be added to the URI
    query_string = project_name_field_value + project_description_field_value

    # Send a POST request to create a folder under a specified folder
    # Return the result of the POST request
    try:
        return requests.post(host_url + path_uri + query_string, auth=HTTPBasicAuth(username, password))
    except requests.exceptions.RequestException as e:
        print e
Function to get the complete project tree structure for a given project
def get_tree_structure(host_url, username, password, project_key):
    """
    This method is used to get complete tree structure for an existing project
    Template parameters:
    [project_key] the project key
    """

    # The REST API path to get complete tree structure for an existing project
    path_uri = '/rest/com.easesolutions.jira.plugins.requirements/1.0/tree/' + project_key

    # Send a GET request to get complete tree structure for an existing project
    # Return the result of the GET request is saved in response variable
    try:
        return requests.get(host_url + path_uri, auth=HTTPBasicAuth(username, password))
    except requests.exceptions.RequestException as e:
        print e
Recursive function to print the information of the folder elements
def print_folder_structure(folders):
    # If folder has values then print the information of the folder
    if folders:
        for folder in folders:
            print '\n%s %s' % ('Display name: ', folder['name_display'])
            print '%s %s' % ('Folder ID: ', folder['id'])
            print '%s %s' % ('Parent folder ID: ', folder['parent'])

            # Perform recursion if there is a folder under this folder
            sub_folders = folder['folders']
            print_folder_structure(sub_folders)
Function that handle the creation of sub folders and checking if the folder is created or not
def handle_sub_folder_creation(project_key, root_folder_id, folder_name, folder_description):
    """
    This method is used to handle the creation of multiple sub folders
    parameters:
    [root_folder_id] the project key
    [folder_name] the ID of the parent folder
    [folder_description] the ID of the parent folder
    """
    # [project_key] project key parameter of the project to create a folder
    # [root_folder_id] the id parameter of the folder where the folder will be created
    # [folder_name] the name parameter of the folder
    # [folder_description] the description parameter of the folder
    # Store the result of the POST request to [response]
    login_folder_response = create_folder_on_specified_folder(HOST_URL, USERNAME, PASSWORD, project_key,
                                                              root_folder_id, folder_name, folder_description)

    if login_folder_response.status_code != 200:
        print 'Error code: ', login_folder_response.status_code
        print login_folder_response.text
Main
project_key = 'SC'
# ['SC'] project key parameter of the project to create a folder
# ['GUI Requirements'] the name parameter of the folder
# ['This folder contain all GUI requirements'] the description parameter of the folder
# Store the result of the POST request to [response]
gui_folder_response = create_folder_on_project_root(HOST_URL, USERNAME, PASSWORD, project_key, 'GUI Requirements',
                                                    'Contains all GUI Requirements for project Sand Castle')

# Check response if folder is created on root
# If folder is created get the ID then create sub folders under the specified folder
if gui_folder_response.status_code == 200:

    # Load the json response
    root_folder_object = json.loads(gui_folder_response.text)

    # Store the ID of the newly created folder on the root
    root_folder_id = root_folder_object['id']
    handle_sub_folder_creation(project_key, root_folder_id, 'Login Page',
                               'Contains all the UI requirements for login page')
    handle_sub_folder_creation(project_key, root_folder_id, 'About Us',
                               'Contains all the UI requirements for About Us page')
    handle_sub_folder_creation(project_key, root_folder_id, 'Home Page',
                               'Contains all the UI requirements for Home page')

else:
    print 'Error code: ', gui_folder_response.status_code
    print gui_folder_response.text

# Get the tree structure for project SC
tree_response = get_tree_structure(HOST_URL, USERNAME, PASSWORD, project_key)
if tree_response.status_code == 200:
    tree_response_object = json.loads(tree_response.text)
    print_folder_structure(tree_response_object['folders'])

Refer to Constant variable for information of the following constant variable: [HOST_URL, USERNAME, PASSWORD]

Output
Display name:  GUI Requirements
Folder ID:  301
Parent folder ID:  -1

Display name:  Login Page
Folder ID:  302
Parent folder ID:  301

Display name:  About Us
Folder ID:  303
Parent folder ID:  301

Display name:  Home Page
Folder ID:  304
Parent folder ID:  301





Update an existing folder's name

The following script will update the name of an existing folder from the project tree. Returns ok in case of success

Function
def update_folder_name(host_url, username, password, project_key, folder_id, folder_name):
    """
    This method allows to update folder name
    """

    # The REST API path to allow update the folder name

    path_uri = '/rest/com.easesolutions.jira.plugins.requirements/1.0/tree/{}/folder/{}'.\
        format(project_key, folder_id)

    # The request body
    json_data = {'name': folder_name}
    # Send and return the PUT request
    try:
        return requests.put(host_url + path_uri, json=json_data, auth=HTTPBasicAuth(username, password))
    except requests.exceptions.RequestException as e:
        print e
Main
# ['SC'] the project key parameter where the folder name will be updated
# [69] The folder id to be updated
# ['SI_Folder_Update'] New name for the folder

response = update_folder_name(HOST_URL, USERNAME, PASSWORD, 'SI', 69, 'SI_Folder_Update', )

if response.status_code == 200:
    print response.text
else:
    print 'Error code: ', response.status_code
    print response.text

Refer to Constant variable for information of the following constant variable: [HOST_URL, USERNAME, PASSWORD]

Output
Folder rename successful.






Remove an existing folder and all it's child folders

The following script will remove an existing folder and all it's child folders and associated issues from the project tree. Returns ok in case of success

Function
def delete_folder(host_url, username, password, project_key, folder_id):
    """
    This method is used to delete specified folder in Requirements
    Template parameters:
    [project_key] the project key
    [folder_id] the ID of the parent folder
    """

    # The REST API path to delete a folder on project root
    path_uri = '/rest/com.easesolutions.jira.plugins.requirements/1.0/tree/' + project_key + '/folder/' + folder_id

    # Send a DELETE request to delete a folder in the Requirements
    # Return the result of the DELETE request
    try:
        return requests.delete(host_url + path_uri, auth=HTTPBasicAuth(username, password))
    except requests.exceptions.RequestException as e:
        print e
Main
# The id of the folder to be deleted
folder_id = '300'

# ['SC'] project key parameter where a folder will be deleted
# [folder_id] folder id parameter for the folder to be deleted
# Store the result of the POST request to [response]
response = delete_folder(HOST_URL, USERNAME, PASSWORD, 'SC', folder_id)

# Check response if folder is deleted
if response.status_code == 200:
    print 'Folder successfully deleted'
else:
    print 'Error code: ', response.status_code
    print response.text

Refer to Constant variable for information of the following constant variable: [HOST_URL, USERNAME, PASSWORD]

Output
Folder successfully deleted