DATA CENTER AND SERVER | CLOUD
Get/Create/Update/Remove Folder
Franklin Gabito
Support Advocate (ease solutions)
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