Differences

This shows you the differences between two versions of the page.

--- dev:sapi:get_item_info [2022/04/20 17:57] – vikki
+++ dev:sapi:get_item_info [2022/04/20 18:08] (current) – vikki
@@ Line 8: / Line 8: @@
 **Description:** Returns information about an item (file or folder). Information you want to retrieve is specified using the fields parameter, which is a string consisting of comma separated field names.
-**INPUT (via GET or POST)**
+----
+===== INPUT (via GET or POST) =====
 Mandatory parameters are: **sid, path**\\
 Optional parameters are: **fields, ofmt**
-----
 ==== sid ====
 Session id of the login user. [mandatory]
-----
 ==== path ====
@@ Line 29: / Line 28: @@
   * <ff:'Courier New'>path=/Company Share/Minutes/</ff> - get information about the folder Minutes in "Company Share"
-----
 ==== fields ====
@@ Line 50: / Line 48: @@
   * **lock_owner** is the lock owner for a lock placed on the item. Value is in the form of and "email" e.g. name@host that identifies a user account, but does not necessarily mean a valid email address. Only applicable to files and NOT folders. For folders, this value is always empty. The (legacy) lock value above is "yes" if this value is not empty.
   * **ucar** is the JSON object the represents the UCAR settings associated with this item. Currently only applicable to folders in Company Share and Company HomePage. For folders elsewhere and regular files, the value returned is empty. An example of such a JSON object is documented in an example below, as the value of the property "ucar". Subject to user privilege, only ucar groups of which the user is member of will be shown.
-----
 ==== ofmt ====
@@ Line 64: / Line 60: @@
 ----
-==== Legacy "flat" OUTPUT (content-type: text/plain) ====
+===== Legacy "flat" OUTPUT (content-type: text/plain) =====
 Successful return:
@@ Line 83: / Line 79: @@
 ----
+===== JSON OUTPUT (content-type: text/plain) =====
+Successful return:
+    JSON output object:
+    {
+      "status" : true,
+      "item_info" : {
+			"property1" : "value1",
+			"property2" : "value2",
+			"property3" : "value3",  ...
+		     }
+    }
+    Most of field values will be represented simply as "fieldname":"simple-value" pair, in the root "item_info" property.
+    For field value of "ucar", a sub-JSON object will represent it. (A sample is shown below.)
+    "ucar" : {
+               <taskKeyword>: { "level":<integer>, "groups":{ <groupname>:<0/1>,... }, "taskdescription":<desc-of-task> },
+               <taskKeyword>: { "level":<integer>, "groups":{ <groupname>:<0/1>,... }, "taskdescription":<desc-of-task> },
+               <taskKeyword>: { "level":<integer>, "groups":{ <groupname>:<0/1>,... }, "taskdescription":<desc-of-task> },
+		:
+             }
+Unsuccessful return:
+    JSON output object:
+    {
+      "status" : false,
+      "errmsg" : "error message, if status is false"
+    }
+In both legacy "flat" output and also JSON output, appropriate HTTP header status codes are also returned.
+e.g. 200 OK, 401 Invalid user profile, etc.
+A full sample of a JSON object returned:
+  {
+   "item_info" : {
+      "owner" : "sschan",
+      "ucar" : {
+         "listFolderContent" : {
+            "level" : "10",
+            "groups" : {
+               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 1, "guest" : 0, "management" : 0
+            },
+            "taskdescription" : "List Folder Content"
+         },
+         "createFiles" : {
+            "level" : "10",
+            "groups" : {
+               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 1, "guest" : 0, "management" : 0
+            },
+            "taskdescription" : "Create Files in Folder"
+         },
+         "deleteFilesInFolder" : {
+            "level" : "1",
+            "groups" : {
+               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 0
+            },
+            "taskdescription" : "Delete Files in Folder"
+         },
+         "deleteFolder" : {
+            "level" : "1",
+            "groups" : {
+               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 0
+            },
+            "taskdescription" : "Delete Folder"
+         },
+         "createSubfolder" : {
+            "level" : "1",
+            "groups" : {
+               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 1, "guest" : 0, "management" : 0
+            },
+            "taskdescription" : "Create Subfolder"
+         },
+         "writeFilesInFolder" : {
+            "level" : "1",
+            "groups" : {
+               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 0
+            },
+            "taskdescription" : "Write to Files in Folder"
+         },
+         "readFilesInFolder" : {
+            "level" : "2",
+            "groups" : {
+               "admin" : 1, "account" : 0, "sales" : 0, "order" : 1, "user" : 0, "guest" : 0, "management" : 1
+            },
+            "taskdescription" : "Read Files in Folder"
+         },
+         "seeThisFolder" : {
+            "level" : "10",
+            "groups" : {
+               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 1, "guest" : 0, "management" : 0
+            },
+            "taskdescription" : "See Folder (Visible)"
+         },
+         "editUcarSetting" : {
+            "level" : "1",
+            "groups" : {
+               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 0
+            },
+            "taskdescription" : "Update UCAR Setting"
+         },
+         "renameFilesInFolder" : {
+            "level" : "1",
+            "groups" : {
+               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 0
+            },
+            "taskdescription" : "Rename Files in Folder"
+         },
+         "renameFolder" : {
+            "level" : "6",
+            "groups" : {
+               "admin" : 1, "account" : 1, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 1
+            },
+            "taskdescription" : "Rename Folder"
+         }
+      },
+      "lock" : "no",
+      "mtime" : 1359626401,
+      "date" : "20130131180001",
+      "name" : "myfolder",
+      "description" : "Description of the item",
+      "size" : 0,
+      "checksum" : "",
+      "lock_owner" : "",
+      "dategmt" : "20130131100001",
+      "type" : "folder",
+      "company" : "noc.afteroffice.com"
+   },
+   "status" : true
+  }
+For a brief explanation of what the ucar settings mean, first note that ucar only applys to a folder item (and in a shared folder like Company Share or Company HomePage). The JSON object has as first level of name/value pairs keyed on ucar tasks names like "renameFolder", "listFolderContent", etc. The value of each of these tasks is another JSON object with three name/value pairs, namely "level", "groups", and "taskdescription". Level is the numeric level assigned to the associated task. A user must have a user level lower that this to have the permission to do the task on the folder. Groups has yet another JSON object defining which user group has permission to do the task on the folder. It is a yes/no permission for users in that group to do the task. Either level privilege or group privilege is sufficient to grant permission when both rules are taken together.

AGNX

User Tools

Site Tools

Differences

Page Tools