SetItemInfo

Script path: /storage/bin/api/set_item_info.cgi

Description: Set item info for a file or folder, subject to access control. The optional parameters and their value determine which item info you want to set.

INPUT (via GET or POST)

Mandatory parameters are: sid, path
Optional parameters are: description, lock, date, dategmt, mtime, ofmt

sid	session id of the login user. [mandatory]
path	path to an item [mandatory] Please refer to [How to specify a path]. path must point to an existing file or folder. e.g. path=/Private/MyFile.avi - setting information for the file MyFile.avi in "Private" area path=/Company Share/Archive/Data/ - setting information for the folder Data.
description	= <a_descriptive_string> This is optional, the existing item description will be unchanged if this parameter is unspecified. To assign an empty string (clear the description) use "description=", that is specify description with an empty string. Currently the length of the description is limited to 80 characters. (Another limitation is that it cannot contain "::" <back-to-back-colon> in the string. Such patterns will be removed.
lock	= yes \| no Set the lock status of the item to either lock (yes) or unlock (no). This parameter is optional, existing lock status will be unchanged if unspecified. Lock status will also be unchanged if it is not "yes" or "no". ( This parameter is now deprecated. An alternative API to effect a Lock will be provided later.)
date	= <14-digit string for user's localtime> e.g. 20040324115809 for 24-Mar-2004 11:58:09am (+0800) Sets the last-modification time of the item -- subject to access control.
dategmt	= <14-digit string for GMT time> e.g. 20040324035809 for 24-Mar-2004 03:58:09am (+0000) Sets the last-modification time of the item -- subject to access control.
mtime	= epoch (the number of non-leap seconds since 1 Jan 1970 GMT) mtime is in GMT. Sets the last-modification time of the item -- subject to access control.
ucar	A valid JSON object representing the new UCAR settings for the item (which is applicable only to folders in Company Share and Company HomePage.) Please refer to the documentation for GetItemInfo for the format of the JSON object for this parameter. The value for "ucar" represents the same UCAR JSON object required here. If the JSON object has syntax error, it will flagged as an error. This parameter will be ignored if the item is NOT a folder in Company Share or Company HomePage.
ofmt	= null \| json \| jsonp null is the default, and the legacy "flat" output format is returned. json means the output format is in JSON format jsonp is like json, but in "pretty" form for easier human readability.

Warning: For each call, use one of date, dategmt, mtime in exclusion of the other two. Result of using more than one of them together in one go is not predictable.

OUTPUT (content-type: text/plain)

Successful return:

	true <newline>

Equivalent JSON output would look like the following:

	{
	   "status" : true
	}

Unsuccessful return:

	false <tab> <error message> <newline>

e.g.

	false <TAB> Item does not exist.

Equivalent JSON output would look like the following:

	{
	   "http_status" : "404 Item does not exist",
	   "status" : false,
	   "errmsg" : "Item does not exist."
	}

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.

This is the general JSON object structure for the for the "ucar" parameter:
Note: This is the same structure as that from the GetItemInfo API except that the taskdescription name-value pairs are not present. (The taskdescription given by GetItemInfo can be retain here, but it will be ignore as it is redundant.)

    "ucar" : { 
               <taskKeyword>: { "level":<integer>, "groups":{ <groupname>:<0/1>,... } },
               <taskKeyword>: { "level":<integer>, "groups":{ <groupname>:<0/1>,... } },
               <taskKeyword>: { "level":<integer>, "groups":{ <groupname>:<0/1>,... } },
		:
             }

Submitting this JSON object means that the new values, for levels and groups, will be overwrite the corresponding ones on the server. Subject to user privilege, user can only make changes to group permission for groups that he/she belongs to only. (Note: The ucar info returned by GetItemInfo API shows only groups that the user is part of.) The value for level should be intergers only ..,-3,-2,-1,0,1,2,3,.. otherwise the new value will be ignored, server value unchanged. Group values are boolean 1 or 0 to indicate permision given for the respective group or not. A particular groupname:value can be not present which will implicitly mean the same as <groupname>:0.

The part or whole set of ucar received from GetItemInfo can be changed and resubmitted back to SetItemInfo to affect a change of values on the server. Part of the whole set should have whole taskKeyword name/value pair, i.e. <taskKeyword>:{ level and groups pairs }, occuring one or more times within a "ucar":{...} object. Changes to any present taskKeyword name/value pair will take effect, while taskKeyword name/value pair will not take effect.

A sample of a WHOLE ucar set for the submitted "ucar" parameter:

WHOLE ucar set, in the sense that all the ucar tasks sub-objects are submitted.

      {
         "listFolderContent" : {
            "level" : "10",
            "groups" : {
               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 1, "guest" : 0, "management" : 0
            }
         },
         "createFiles" : {
            "level" : "10",
            "groups" : {
               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 1, "guest" : 0, "management" : 0
            }
         },
         "deleteFilesInFolder" : {
            "level" : "1",
            "groups" : {
               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 0
            }
         },
         "deleteFolder" : {
            "level" : "1",
            "groups" : {
               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 0
            }
         },
         "createSubfolder" : {
            "level" : "1",
            "groups" : {
               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 1, "guest" : 0, "management" : 0
            }
         },
         "writeFilesInFolder" : {
            "level" : "1",
            "groups" : {
               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 0
            }
         },
         "readFilesInFolder" : {
            "level" : "2",
            "groups" : {
               "admin" : 1, "account" : 0, "sales" : 0, "order" : 1, "user" : 0, "guest" : 0, "management" : 1
            }
         },
         "seeThisFolder" : {
            "level" : "10",
            "groups" : {
               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 1, "guest" : 0, "management" : 0
            }
         },
         "editUcarSetting" : {
            "level" : "1",
            "groups" : {
               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 0
            }
         },
         "renameFilesInFolder" : {
            "level" : "1",
            "groups" : {
               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 0
            }
         },
         "renameFolder" : {
            "level" : "6",
            "groups" : {
               "admin" : 1, "account" : 1, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 1
            }
         }
      }

Samples of PART ucar sets for the submitted "ucar" parameter:

PART ucar sets, in the sense that not all the ucar tasks sub-objects are submitted.

SAMPLE 1
      {
         "writeFilesInFolder" : {
            "level" : "1",
            "groups" : {
               "admin" : 1, "account" : 0, "sales" : 0, "order" : 0, "user" : 0, "guest" : 0, "management" : 1
            }
         },
         "readFilesInFolder" : {
            "level" : "10",
            "groups" : {
               "admin" : 1, "account" : 1, "sales" : 0, "order" : 0, "user" : 1, "guest" : 0, "management" : 1
            }
         },
      }

SAMPLE 2
      {
         "writeFilesInFolder" : {
            "level" : "1",
            "groups" : {
               "admin" : 1, "management" : 1
            }
         },
         "readFilesInFolder" : {
            "level" : "10",
            "groups" : {
               "admin" : 1, "account" : 1, "user" : 1, "management" : 1
            }
         },
      }

NOTE: It happens that Sample 1 and Sample 2 will effect the same result, if submitted by the same user.