AGNX

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
[[:start|Home]] > [[:dev|Developer]] > [[dev:sapi|Lookafter Storage System API]] > **GetItemInfo**


====== GetItemInfo ======

**Script path:** <ff:'Courier New'>/storage/bin/api/get_item_info.cgi</ff>

**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) =====

Mandatory parameters are: **sid, path**\\ 
Optional parameters are: **fields, ofmt**


==== sid ====
Session id of the login user. [mandatory]


==== path ====
Path to a folder. [mandatory]\\ 
Please refer to [[dev:sapi:path_spec|How to specify a path]].

Path must point to an existing folder. E.g.:
  * <ff:'Courier New'>path=/Private/MyFile.avi</ff> - get information about the file MyFile.avi in "Private" area
  * <ff:'Courier New'>path=/Company Share/Minutes/</ff> - get information about the folder Minutes in "Company Share"


==== fields ====
= name,date,dategmt,mtime,size,type,owner,company,lock,description,checksum,lock_owner,ucar\\ 
= name,date,size,type (this is default if no fields are provided)

The field names may be any order and the returned field values will follow that order. Separate the field names with commas but do not include any spaces. Fields obmitted will not be returned. Returned value for a field can be empty strings. If a field does not exist in the item's information record, an empty field is returned. WARNING: a misspelled field name will be quietly ignored, i.e. returned empty value!

  * **name** is the name of the item
  * **date** is in 14-digit form, corrected to user's localtime using the user's timezone info from his profile. e.g. 20010130052533
  * **dategmt** is in 14-digit form, GMT time. e.g. 20010129212533 is the GMT equivalent to the date example.
  * **mtime** is the number of non-leap seconds since 1 Jan 1970 GMT. mtime is in GMT.
  * **size** is the file size. Integer, no commas. For folders, it is the total size of all files and subfolder under it, BUT it can be -1 or "blank" if the folder size is not available yet.
  * **type** is a string 'file' or 'folder'.  NOTE: This property can be used to test the existence of a file or folder. If the returned type is empty, then the item does not exist.
  * **owner** is the owner of the item, taking the form of <name>[.<group>] e.g. userone.abc or dotcomguy  ( Update 2013: the [.<group>] part is deprecated.)
  * **company** is the organization of owner, taking the form of [<group>.]<host> e.g. abc.afteroffice.net or dotcom.com  ( Update 2013: the [<group>.] part is deprecated.)
  * **lock** is the lock status of the item. Value is 'yes' if locked and 'no' otherwise. (Actually derived from lock_owner not= empty)
  * **description** is a string entered by owner to describe the item.
  * **checksum** is the 128-bit MD5 checksum of the file represented as lowercased 32 hex digits. This only applies to files. WARNING: For folders, the value returned will be empty/null, without any errors being flagged.
  * **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 ====
Output format\\ 
= json  means to return output in JSON format (with minimum or no redundant white spaces)\\ 
= jsonp  means to return ouput in JSON format, pretty-printed for easy human readability.
otherwise (default, or not specified), means the legacy "flat" formatting output is assumed.

In the legacy "flat" output format,  the returned value for ucar is in a "flat" not pretty-printed JSON object string. It cannot be pretty-printed because it will break the flat format.
In a JSON output formt, the returned value for ucar is also a JSON object nested in overall JSON object, and can be pretty-printed as requested.

----

===== Legacy "flat" OUTPUT (content-type: text/plain) =====

Successful return:
  true <newline>
  <tab separated field values for the item> <newline>

e.g.

  true
  newfolder <TAB> 20010206180115 <TAB> 0 <TAB> folder

Unsuccessful return:
  false <tab> <error message> <newline>

e.g.

  false <TAB> Item does not exist.

----

===== 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

Page Tools
