Update apis

Author: XingY

docs/storage.md

@@ -110,10 +110,17 @@ else:
 box_id = result["data"]["rowId"]
 
 ###############
-# Update the location of a box in the freezer
+# Update the location of a box in the freezer. An optional "auditUserComment"
+# property may be included in the props dict; it is recorded as the "Reason"
+# on the resulting audit event.
 ###############
 result = api.storage.update_storage_item(
-    "Terminal Storage Location", {"rowId": box_id, "locationId": shelf2_row_id}
+    "Terminal Storage Location",
+    {
+        "rowId": box_id,
+        "locationId": shelf2_row_id,
+        "auditUserComment": "Relocated to make room for incoming samples from Lab B.",
+    },
 )
 if result is not None:
     print(result)
@@ -122,9 +129,14 @@ else:
     exit()
 
 ###############
-# Delete the freezer, which will delete the full hierarchy of non-terminal and terminal storage locations
+# Delete the freezer, which will delete the full hierarchy of non-terminal and terminal
+# storage locations. An optional audit_user_comment is supplied here for the audit log.
 ###############
-result = api.storage.delete_storage_item("Freezer", freezer_row_id)
+result = api.storage.delete_storage_item(
+    "Freezer",
+    freezer_row_id,
+    audit_user_comment="Decommissioning Freezer #1 per facilities request.",
+)
 if result is not None:
     print(result)
 else:

labkey/storage.py

@@ -58,42 +58,38 @@
 
 
 def create_storage_item(
-    server_context: ServerContext, type: str, props: dict, container_path: str = None, audit_user_comment: str = None
+    server_context: ServerContext, type: str, props: dict, container_path: str = None
 ):
     """
     Create a new LabKey Freezer Manager storage item that can be used in the creation of a storage hierarchy.
     :param server_context: A LabKey server context. See utils.create_server_context.
     :param type:
-    :param props:
+    :param props: a dict of property values for the storage item. Any storage item type also accepts an optional
+        "auditUserComment" (string) entry, which is recorded as the "Reason" on the resulting audit event.
     :param container_path:
-    :param audit_user_comment: optional comment that will be attached to the audit log record for this storage change.
     :return:
     """
     url = server_context.build_url(STORAGE_CONTROLLER, "create.api", container_path)
     payload = {"type": type, "props": props}
-    if audit_user_comment is not None:
-        payload["auditUserComment"] = audit_user_comment
 
     return server_context.make_request(url, json=payload)
 
 
 def update_storage_item(
-    server_context: ServerContext, type: str, props: dict, container_path: str = None, audit_user_comment: str = None
+    server_context: ServerContext, type: str, props: dict, container_path: str = None
 ):
     """
     Update an existing LabKey Freezer Manager storage item to change its properties or location within the storage hierarchy.
     For update_storage_item, the "rowId" primary key value is required to be set within the props.
     :param server_context: A LabKey server context. See utils.create_server_context.
     :param type:
-    :param props:
+    :param props: a dict of property values for the storage item. Any storage item type also accepts an optional
+        "auditUserComment" (string) entry, which is recorded as the "Reason" on the resulting audit event.
     :param container_path:
-    :param audit_user_comment: optional comment that will be attached to the audit log record for this storage change.
     :return:
     """
     url = server_context.build_url(STORAGE_CONTROLLER, "update.api", container_path)
     payload = {"type": type, "props": props}
-    if audit_user_comment is not None:
-        payload["auditUserComment"] = audit_user_comment
 
     return server_context.make_request(url, json=payload)
 
@@ -109,13 +105,14 @@ def delete_storage_item(
     :param type:
     :param row_id:
     :param container_path:
-    :param audit_user_comment: optional comment that will be attached to the audit log record for this storage change.
+    :param audit_user_comment: optional reason text recorded as the "Reason" on the resulting audit event.
     :return:
     """
     url = server_context.build_url(STORAGE_CONTROLLER, "delete.api", container_path)
-    payload = {"type": type, "props": {"rowId": row_id}}
+    props = {"rowId": row_id}
     if audit_user_comment is not None:
-        payload["auditUserComment"] = audit_user_comment
+        props["auditUserComment"] = audit_user_comment
+    payload = {"type": type, "props": props}
 
     return server_context.make_request(url, json=payload)
 
@@ -129,12 +126,12 @@ def __init__(self, server_context: ServerContext):
         self.server_context = server_context
 
     @functools.wraps(create_storage_item)
-    def create_storage_item(self, type: str, props: dict, container_path: str = None, audit_user_comment: str = None):
-        return create_storage_item(self.server_context, type, props, container_path, audit_user_comment)
+    def create_storage_item(self, type: str, props: dict, container_path: str = None):
+        return create_storage_item(self.server_context, type, props, container_path)
 
     @functools.wraps(update_storage_item)
-    def update_storage_item(self, type: str, props: dict, container_path: str = None, audit_user_comment: str = None):
-        return update_storage_item(self.server_context, type, props, container_path, audit_user_comment)
+    def update_storage_item(self, type: str, props: dict, container_path: str = None):
+        return update_storage_item(self.server_context, type, props, container_path)
 
     @functools.wraps(delete_storage_item)
     def delete_storage_item(self, type: str, row_id: int, container_path: str = None, audit_user_comment: str = None):