Merge pull request #61 from blackducksoftware/gsnyder/custom-fields

adding support for creating and deleting custom fields

Author: Glenn Snyder

blackduck/HubRestApi.py

@@ -1457,6 +1457,126 @@ def update_component_by_url(self, component_url, update_json):
         return self.execute_put(component_url, update_json)
 
 
+    ##
+    #
+    # Custom fields
+    #
+    ##
+    def _get_cf_url(self):
+        return self.get_apibase() + "/custom-fields/objects"
+
+    def supported_cf_object_types(self):
+        '''Get the types and cache them since they are static (on a per-release basis)'''
+        if not hasattr(self, "_cf_object_types"):
+            logging.debug("retrieving object types")
+            self._cf_object_types = [cfo['name'] for cfo in self.get_cf_objects().get('items', [])]
+        return self._cf_object_types
+
+    def get_cf_objects(self):
+        '''Get CF objects and cache them since these are static (on a per-release basis)'''
+        url = self._get_cf_url()
+        if not hasattr(self, "_cf_objects"):
+            logging.debug("retrieving objects")
+            custom_headers = {'Accept': 'application/vnd.blackducksoftware.admin-4+json'}
+            response = self.execute_get(url, custom_headers=custom_headers)
+            self._cf_objects = response.json()
+        return self._cf_objects
+
+    def _get_cf_object_url(self, object_name):
+        for cf_object in self.get_cf_objects().get('items', []):
+            if cf_object['name'].lower() == object_name.lower():
+                return cf_object['_meta']['href']
+
+    def get_cf_object(self, object_name):
+        assert object_name in self.supported_cf_object_types(), "Object name {} not one of the supported types ({})".format(object_name, self.supported_cf_object_types())
+
+        object_url = self._get_cf_object_url(object_name)
+        custom_headers = {'Accept': 'application/vnd.blackducksoftware.admin-4+json'}
+        response = self.execute_get(object_url, custom_headers=custom_headers)
+        return response.json()
+
+    def _get_cf_obj_rel_path(self, object_name):
+        return object_name.lower().replace(" ", "-")
+
+    def create_cf(self, object_name, field_type, description, label, position, active=True, initial_options=[]):
+        '''
+            Create a custom field for the given object type (e.g. "Project", "Project Version") using the field_type and other parameters.
+
+            Initial options are needed for field types like multi-select where the multiple values to choose from must also be provided.
+
+            initial_options = [{"label":"val1", "position":0}, {"label":"val2", "position":1}]
+        '''
+        assert isinstance(position, int) and position >= 0, "position must be an integer that is greater than or equal to 0"
+        assert field_type in ["BOOLEAN", "DATE", "DROPDOWN", "MULTISELECT", "RADIO", "TEXT", "TEXTAREA"]
+
+        types_using_initial_options = ["DROPDOWN", "MULTISELECT", "RADIO"]
+
+        post_url = self._get_cf_object_url(object_name) + "/fields"
+        cf_object = self._get_cf_obj_rel_path(object_name)
+        cf_request = {
+            "active": active,
+            "description": description,
+            "label": label,
+            "position": position,
+            "type": field_type,
+        }
+        if field_type in types_using_initial_options and initial_options:
+            cf_request.update({"initialOptions": initial_options})
+        custom_headers = {
+            'Content-Type': 'application/vnd.blackducksoftware.admin-4+json',
+            'Accept': 'application/json'
+        }
+        response = self.execute_post(post_url, data=cf_request, custom_headers=custom_headers)
+        return response
+
+    def delete_cf(self, object_name, field_id):
+        '''Delete a custom field from a given object type, e.g. Project, Project Version, Component, etc
+
+        WARNING: Deleting a custom field is irreversiable. Any data in the custom fields could be lost so use with caution.
+        '''
+        assert object_name in self.supported_cf_object_types(), "You must supply a supported object name that is in {}".format(self.supported_cf_object_types())
+
+        delete_url = self._get_cf_object_url(object_name) + "/fields/{}".format(field_id)
+        return self.execute_delete(delete_url)
+
+    def get_custom_fields(self, object_name):
+        '''Get the custom field (definition) for a given object type, e.g. Project, Project Version, Component, etc
+        '''
+        assert object_name in self.supported_cf_object_types(), "You must supply a supported object name that is in {}".format(self.supported_cf_object_types())
+
+        url = self._get_cf_object_url(object_name) + "/fields"
+
+        custom_headers = {'Accept': 'application/vnd.blackducksoftware.admin-4+json'}
+        response = self.execute_get(url, custom_headers=custom_headers)        
+        return response.json()
+
+    def get_cf_values(self, obj):
+        '''Get all of the custom fields from an object such as a Project, Project Version, Component, etc
+
+        The obj is expected to be the JSON document for a project, project-version, component, etc
+        '''
+        url = self.get_link(obj, "custom-fields")
+        custom_headers = {'Accept': 'application/vnd.blackducksoftware.component-detail-5+json'}
+        response = self.execute_get(url, custom_headers=custom_headers)
+        return response.json()
+
+    def get_cf_value(self, obj, field_id):
+        '''Get a custom field value from an object such as a Project, Project Version, Component, etc
+
+        The obj is expected to be the JSON document for a project, project-version, component, etc
+        '''
+        url = self.get_link(obj, "custom-fields") + "/{}".format(field_id)
+        custom_headers = {'Accept': 'application/vnd.blackducksoftware.component-detail-5+json'}
+        response = self.execute_get(url, custom_headers=custom_headers)
+        return response.json()
+
+    def put_cf_value(self, cf_url, new_cf_obj):
+        '''new_cf_obj is expected to be a modified custom field value object with the values updated accordingly, e.g.
+        call get_cf_value, modify the object, and then call put_cf_value
+        '''
+        custom_headers = {'Accept': 'application/vnd.blackducksoftware.component-detail-5+json'}
+        return self.execute_put(cf_url, new_cf_obj, custom_headers=custom_headers)
+
     ##
     #
     # General stuff

blackduck/__version__.py

@@ -1,3 +1,3 @@
-VERSION = (0, 0, 34)
+VERSION = (0, 0, 35)
 
 __version__ = '.'.join(map(str, VERSION))

examples/create_custom_field.py

@@ -0,0 +1,48 @@
+
+#!/usr/bin/env python
+
+import argparse
+import json
+import logging
+import sys
+
+from blackduck.HubRestApi import HubInstance
+
+parser = argparse.ArgumentParser("Create a custom field")
+parser.add_argument("object", choices=["BOM Component", "Component", "Component Version", "Project", "Project Version"], help="The object that the custom field should be attached to")
+parser.add_argument("field_type", choices=["BOOLEAN", "DATE", "DROPDOWN", "MULTISELECT", "RADIO", "TEXT", "TEXTAREA"])
+parser.add_argument("description")
+parser.add_argument("label")
+parser.add_argument("-i", "--initial_options", action='append', nargs=2, metavar=('label', 'position'), help="Set the initial options by repeatedly using the -i option, supply a label and position for each possible selection. Used for DROPDOWN, MULTISELECT, and RADIO field types.")
+parser.add_argument("-a", "--active", action='store_true', default=False, help="Use the --active option to make the created field active (dafault: Inactive")
+parser.add_argument("-p", "--position", default=0, type=int, help="Use the --position option to specify what numeric position the custom field should be displayed in")
+args = parser.parse_args()
+
+
+logging.basicConfig(format='%(asctime)s:%(levelname)s:%(message)s', stream=sys.stderr, level=logging.DEBUG)
+logging.getLogger("requests").setLevel(logging.DEBUG)
+logging.getLogger("urllib3").setLevel(logging.WARNING)
+
+
+hub = HubInstance()
+
+logging.debug("Creating custom field using arguments: {}".format(args))
+
+initial_options = [{"label": io[0], "position": io[1]} for io in args.initial_options]
+
+import pdb; pdb.set_trace()
+
+response = hub.create_cf(
+    args.object, 
+    args.field_type, 
+    args.description, 
+    args.label, 
+    position=args.position,
+    active=args.active,
+    initial_options=initial_options)
+
+logging.debug("status code: {}".format(response.status_code))
+
+
+
+

examples/delete_custom_field.py

@@ -0,0 +1,34 @@
+
+#!/usr/bin/env python
+
+import argparse
+import json
+import logging
+import sys
+
+from blackduck.HubRestApi import HubInstance
+
+parser = argparse.ArgumentParser("Delete a custom field or all of them")
+parser.add_argument("object", choices=["BOM Component", "Component", "Component Version", "Project", "Project Version"], help="The object that the custom field should be attached to")
+parser.add_argument("field_id", help="Use a value of 'all' to delete all the custom fields for the given object")
+args = parser.parse_args()
+
+
+logging.basicConfig(format='%(asctime)s:%(levelname)s:%(message)s', stream=sys.stderr, level=logging.DEBUG)
+logging.getLogger("requests").setLevel(logging.DEBUG)
+logging.getLogger("urllib3").setLevel(logging.WARNING)
+
+
+hub = HubInstance()
+
+if args.field_id == "all":
+    # delete all custom fields for the specified object type
+    custom_fields = hub.get_custom_fields(args.object).get('items', [])
+    for custom_field in custom_fields:
+        logging.debug("Deleting custom field")
+        custom_field_url = custom_field['_meta']['href']
+        response = hub.execute_delete(custom_field_url)
+        logging.debug("status code for deleting {} is {}".format(custom_field_url, response.status_code))
+else:
+    response = hub.delete_cf(args.object, args.field_id)
+    logging.debug("status code: {}".format(response.status_code))