Read Hierarchical Records of an Object
|
Method
|
GET
|
|
URL
|
/v2/<object_full_identifier>/<record_UUID>/hierarchy
|
|
Parameters
|
fields, incomingRelationships, filter, sort, limit, offset, exclude_total_count, data_format, hie_field, direction
|
|
Response Content Type
|
application/json
|
Response
The response is a JSON representation of a list of all retrieved records. Following is an example Status Code 200 response for the Showcase object.
[
{
"__object_identifier": "io_showcase",
"io_showcase_phone_number": "+1 (650) 123456",
"io_search_filter_file_object": null,
"io_owner": "bbbf0872-b9dc-11e0-adfd-00ff8314382b",
"io_showcase_document": null,
"io_private": false,
"io_platform_changes_permitted": null,
.
.
},
{...}, {...}, ..., {...}
]
{
"__object_identifier": "io_showcase",
"io_showcase_phone_number": "+1 (650) 123456",
"io_search_filter_file_object": null,
"io_owner": "bbbf0872-b9dc-11e0-adfd-00ff8314382b",
"io_showcase_document": null,
"io_private": false,
"io_platform_changes_permitted": null,
.
.
},
{...}, {...}, ..., {...}
]
 |
Each returned record includes the __object_identifier pseudo-field, which contains the full identifier of the object to which the record belongs.
|
|
Parameter
|
Description
|
Data Type
|
Example
|
|---|---|---|---|
|
fields
|
Object fields to be retrieved. Eager loading is supported in depth, and related record fields can be eager-loaded if relationships between records exist.
If not specified, all object fields are retrieved by default.
|
String
|
Retrieve only the uuid, owner, private, active, and deleted fields for each record:
/v2/<object_full_identifier>/<record_UUID>/hierarchy?fields=io_uuid,io_owner,io_private,io_active,io_deleted
|
|
incomingRelationships
|
Incoming relationships of the object to use to retrieve related records.
|
String
|
Retrieve the related records for the application_log_related_to incoming relationship for each record:
/v2/<object_full_identifier>/<record_UUID>/hierarchy?incomingRelationships=io_application_log_related_to
|
|
filter
|
Filtering condition on records to retrieve. The SMQL WHERE clause is supported for filtering eager-loaded fields.
If not specified, all undeleted records are retrieved by default.
|
String
|
Retrieve only the records updated by the system user:
/v2/<object_full_identifier>?filter=io_updated_by.io_username='system'
|
|
sort
|
Sorting criteria for retrieved records. The SMQL ORDER BY clause is supported for sorting eager-loaded fields. Ascending (ASC) and descending (DESC) criteria are supported. ASC is the default.
If not specified, records are retrieved in no specific order.
|
String
|
Retrieve all records sorted by creation date in descending order:
/v2/<object_full_identifier>/<record_UUID>/hierarchy?sort=io_created_on+DESC
Retrieve all records sorted by the full name of the user who created the record (default ascending) and by the creation date in descending order:
/v2/<object_full_identifier>/<record_UUID>/hierarchy?sort=io_created_by.io_full_name,io_created_on+DESC
|
|
limit
|
The number of records to retrieve. SMQL LIMIT clause syntax is supported. If specified, the response includes the X-Total-Count header with the total count of records that can be retrieved without the limit. Consider using exclude_total_count if calculation of this value is not performant.
If not specified, and no filtering is specified, all undeleted records are retrieved.
|
Integer
|
Retrieve 100 records for an object:
/v2/<object_full_identifier>/<record_UUID>/hierarchy?limit=100
|
|
offset
|
Offset to use to retrieve records. It is recommended to combine this parameter with the sort parameter. SQML OFFSET clause syntax is supported
If not specified, records are retrieved with no offset.
|
Integer
|
Retrieve the next 100 records after the first 500, ordered by Name:
/v2/<object_full_identifier>/<record_UUID>/hierarchy?sort=io_name&limit=100&offset=500
|
|
exclude_total_count
|
Set this flag to exclude the X-Total-Count header, which is provided by default when you use limit to specify the number of records returned.
If limit is not set and the total number of selected records is large, performance may be impacted depending on permissions configuration. In these cases, use this parameter to reduce the number of calculation iterations of the total count.
|
Boolean
|
Retrieve only 100 records for an object:
/v2/<object_full_identifier>/<record_UUID>/hierarchy?limit=100&exclude_total_count=true
|
|
data_format
|
The output data format. Supported values are basic and extended.
The basic format, which is the default, corresponds to the example response shown above. The extended format includes additional information for specific data types, such as:
• Option List
• Currency Amount
• Quantity
• Document
• Image
• Status
• Relationship
For more information, see Extended Output Data Format.
|
String
|
Retrieve a list of records with extended output data:
/v2/<object_full_identifier>/<record_UUID>/hierarchy?data_format=extended
|
|
hie_field
|
The Relationship fields to be used as links to ancestor records when hierarchical record trees are traversed. Direct and indirect traversal are supported based on hierarchical tree locations.
For direct traversal, the list of records of the object specified by the object_full_identifier parameter is retrieved through a hierarchical tree in that object. The hie_field parameter is used to specify a Relationship field for which the target object is the object itself. The record_uuid parameter is used to specify the record of the object at which to begin traversal. As an example, if there is an object named Role that has a Relationship field named io_parent which points to that same object, you can use hie_field=io_parent to load a list of descendant Role records to the ancestor record specified in the record_uuid parameter.
For indirect traversal, the list of records of the object specified by the object_full_identifier parameter is retrieved through a hierarchical tree in a related object that is linked to the main object with a Relationship field. The related object also has a Relationship field that is used for a hierarchical tree. The hie_field parameter must be used to specify the two fields separated with a dot. The record_uuid parameter is used to specify the record of the related object at which to begin traversal. As an example, if there is an object named Role that has a Relationship field named io_parent which pointsto that same object, and an io_user_role field in a User record is linked to the same Role object, you can use hie_field=io_user_role.io_parent to load a list of User records that are under descendant Role records of an ancestor record specified in the record_uuid parameter.
|
String
|
Retrieve a list of hierarchical records with parent record fields:
/v2/<object_full_identifier>/<record_UUID>/hierarchy?hie_field=io_parent
|
|
direction
|
The direction in which to load records in hierarchical trees. Supported values:
• ancestor: Ancestor records of the record specified in the record_UUID parameter.
• descendant: Descendant records of the record specified in the record_UUID parameter.
• descendant_by_anc: Descendant records of the root ancestor record of the record specified in the record_UUID parameter.
|
String
|
Retrieve a list of hierarchical records of ancestors of the specified record:
/v2/<object_full_identifier>/<record_UUID>/hierarchy?direction=ancestor
|
Error Response Messages
|
HTTP Status Code
|
Error Type
|
Error Message
|
|---|---|---|
|
400
|
missing_parameter_error
|
Missing or invalid required parameter
|
|
400
|
smql_query_error
|
SMQL query error
|
|
400
|
serialization_error
|
Serialization error
|
|
500
|
server_error
|
Server error
|
Access Control
This REST API endpoint respects access control and permissions for each record. Data that users lack permissions to read is not returned. All authenticated users (for example, with the Standard User role) can execute this REST endpoint.
Examples
• Retrieve a list of descendant Role records of a specified Role record, including the root record:
http://server/v2/io_role/2bc3e036-deb3-46d8-b666-e09e04250774/hierarchy?hie_field=io_parent&sort=io_name&limit=100
• Retrieve a list of ancestor Role records of a specified Role record, including the root record:
http://server/v2/io_role/2bc3e036-deb3-46d8-b666-e09e04250774/hierarchy?hie_field=io_parent&direction=ancestor&sort=io_name&limit=100
• Retrieve a list of descendant Role records of a root ancestor record of a specified Role record:
http://server/v2/io_role/2bc3e036-deb3-46d8-b666-e09e04250774/hierarchy?hie_field=io_parent&direction=descendant_by_anc&sort=io_name&limit=100
• Retrieve a list of User records under a tree of descendant Role records of a specified Role record, including the root record:
http://server/v2/io_user/7c8218a1-8801-4a85-b4b0-9270bb427b80/hierarchy?hie_field=io_user_role.io_parent&sort=io_name&limit=100
|
|
The io_user_role field is used in this example only for demonstration purposes, and is not available in the Max User object. If needed for testing, you can add this field to the User object and set related values in User records, so that the parameter example is valid.
|