Entity Properties
Entity-properties are key-value pairs stored against the task / issue / project entities. They can be used for storing details that are needed for API integrations but don’t have to be visible in the UI. Key has to be a String & the Value could be a simple string or a json object. Extension developers can store multiple key-value pair for a single entity. These entity properties can be stored / retrieved / updated / deleted using the below mentioned APIs as well as the JS SDK available for the extension.
Scope: ZohoProjects.entity_properties.{operations}
Operations: READ, CREATE, UPDATE, DELETE
Supported entities
- Projects
- Tasks
- Issues
Entity Properties API
| Retrieve Entity Properties GET /restapi/portal/[PORTALID]/entity/properties/retrieve |
| Store Entity Properties POST /restapi/portal/[PORTALID]/entity/properties/store |
| Update Entity Properties POST /restapi/portal/[PORTALID]/entity/properties/update |
| Remove Entity Properties DELETE /restapi/portal/[PORTALID]/entity/properties/remove |
Retrieve Entity Properties
Retrieves the data stored against an entity. The argument of this method should be the key that was used when the same data was stored.
Scope: ZohoProjects.entity_properties.READ
Request Parameters
| project_id* | Long | ID of the project |
| property_key | String | Unique key for the app |
| entity_id* | Long | Entity ID (project/task/issue) |
| entity_type* | String | Type of the entity. Accepted values = 1,2 and 3 (1 =task, 2 = issue, 3 = project). |
* - Mandatory parameters
Sample Response
Status: 200 Success Content Type: application/json;charset=utf-8
{properties:[{ id: "27092************”,
key: "sample_extension",
value: “{“userId” : “12****” , “userName” : “Helen”}“
}]
Store Entity Properties
Users can store data against an entity.
POST /restapi/portal/[PORTALID]/entity/properties/store
Scope: ZohoProjects.entity_properties.CREATE
Request Parameters
| app_id | Long | ID of the extension |
| project_id* | Long | ID of the project |
| property* | String |
Extension data to be stored. The data has to be passed with the extension key in below format. |
| entity_id* | Long | Entity ID (project/task/issue) |
entity_type* | String | Type of the entity. Accepted values = 1, 2 and 3 (1 =task, 2 = issue, 3 = project). |
* - Mandatory parameters. Parameters should be passed as form data in the body.
Sample Response
Status: 200 Success Content Type: application/json;charset=utf-8
{properties:[{ id: "27092************”,
key: "sample_extension",
value: “{“userId” : “12****” , “userName” : “Helen”}“
}],
status : "success" }
Update Entity Properties
Updates the data that is stored against an entity.
POST /restapi/portal/[PORTALID]/entity/properties/update
Scope: ZohoProjects.entity_properties.UPDATE
Request Parameters
| project_id* | Long | ID of the project |
| property* | String |
Extension data that needs to be updated. The data has to be passed with property id and unique extension key in below format. |
| entity_id* | Long | Entity ID (project/task/issue) |
| entity_type* | String | Type of the entity. Accepted values = 1, 2 and 3 (1 =task, 2 = issue, 3 = project). |
* - Mandatory parameters. Parameters should be passed as form data in the body.
Sample Response
Status: 200 Success Content Type: application/json;charset=utf-8
{properties:[{ id: "27092************”,
key: "sample_extension",
value: “{“userId” : “12****” , “userName” : “Helen”}“
}],
status:"success" }
Remove Entity Properties
Deletes the data that is stored against a specific entity. The argument of this method is the ID that was generated as the output when the same data was stored using the 'entity.store()' method.
Delete /restapi/portal/[PORTALID]/entity/properties/remove
Scope: ZohoProjects.entity_properties.Delete
Request Parameters
| project_id* | Long | ID of the project |
| property_id* | Long | Property ID from the RETRIEVE response |
| entity_id* | Long | Entity ID (project/task/issue) |
| entity_type* | String | Type of the entity. Accepted values = 1, 2 and 3 (1 =task, 2 = issue, 3 = project). |
* - Mandatory parameters
Sample Response
Status: 200 Success Content Type: application/json;charset=utf-8
{{message: "Property removed successfully", status: "success"}
Limitations of entity properties
- A maximum of 100 properties can only be stored against an entity.
- The key should not exceed 200 characters.
- The size of the value should not exceed 50 KB.
- This method cannot be invoked for the 'app_settings', 'attachment_picker' and 'top_band' locations.