page-structural-entities

Specification Version

Version: "1"

Context and rules

Required for the SubjectRead capability.

Returns paged structural entities based on various criteria received by the endpoint.

Endpoint specification

• Name: endpoint-prefix-aireframe-page-structural-entities
• Verb: POST
• Authentication: Client credentials

Input

• Format: JSON
• Schema:

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"title": "page-structural-entities-request",
	"type": "object",
	"properties": {
		"Filter": {
			"type": "object",
			"properties": {
				"RootKey": {
					"type": [
						"null",
						"string"
					],
          			"description": "The key of the structural entity to filter the sub-tree from."
				},
				"Depth": {
					"type": [
						"integer",
						"null"
					],
					"description": "The depth of the tree to traverse. If null, the entire tree is traversed.",
					"format": "int32"
				},
				"SearchTerm": {
					"type": [
						"null",
						"string"
					]
				},
				"SubjectAssignable": {
					"type": [
						"boolean",
						"null"
					],
					"description": "Only return structural entities whose structure type is subject assignable."
				},
				"StructureTypeKeys": {
					"type": [
						"array",
						"null"
					],
					"items": {
						"type": "string"
					}
				}
			},
			"required": [
				"RootKey",
				"Depth",
				"SearchTerm",
				"SubjectAssignable",
				"StructureTypeKeys"
			]
		},
		"PagingRequest": {
			"type": "object",
			"properties": {
				"After": {
					"type": [
						"null",
						"string"
					],
					"description": "Request items after the node with provided cursor"
				},
				"Before": {
					"type": [
						"null",
						"string"
					],
					"description": "Request items before the node with provided cursor"
				},
				"First": {
					"type": [
						"integer",
						"null"
					],
					"description": "Request the first x items",
					"format": "int32"
				},
				"Last": {
					"type": [
						"integer",
						"null"
					],
					"description": "Request the last x items.",
					"format": "int32"
				},
				"OrderBy": {
					"type": [
						"null",
						"string"
					],
					"description": "Gets the key of the field to order by."
				},
				"OrderDirection": {
					"description": "Gets the direction to order by.",
					"oneOf": [
						{
							"type": "null"
						},
						{             
							"type": "string",
							"enum": [
								"Ascending",
								"Descending"
							]
						}
					]
				}
			},
			"required": [
					"After",
					"Before",
					"First",
					"Last",
					"OrderBy",
					"OrderDirection"
			]
		}
	},
	"required": [
		"Filter",
		"PagingRequest"
	]
}

• Example:

{
	"Filter": {
	    "RootKey": null,
	    "Depth": null,
	    "SearchTerm": null,
	    "SubjectAssignable": true,
	    "StructureTypeKeys": ["dept"]
	},
	"PagingRequest": {
	    "After": null,
	    "Before": null,
	    "First": null,
	    "Last": null,
	    "OrderBy": null,
	    "OrderDirection": null
	}
}

Response

• Format: JSON
• Schema:

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"title": "page-structural-entities-response",
	"type": "object",
	"properties": {
		"PageInfo": {
			"type": "object",
			"properties": {
				"HasNextPage": {
					"type": "boolean"
				},
				"HasPreviousPage": {
					"type": "boolean"
				},
				"StartCursor": {
					"type": [
						"null",
						"string"
					]
				},
				"EndCursor": {
					"type": [
						"null",
						"string"
					]
				},
				"TotalCount": {
					"type": "integer",
					"format": "int32"
				}
			},
			"required": [
				"HasNextPage",
				"HasPreviousPage",
				"TotalCount"
			]
		},
		"Edges": {
			"type": "array",
			"items": {
				"required": [
					"Cursor",
					"Node"
				],
				"properties": {
					"Node": {
						"type": "object",
						"properties": {
							"Key": {
								"type": "string"
							},
							"DisplayName": {
								"type": "string",
							},
							"StructureType": {
								"type": "object",
								"properties": {
									"Key": {
										"type": "string"
									},
									"DisplayName": {
										"type": "string"
									},
									"IsSubjectAssignable": {
										"type": "boolean"
									}
								},
								"required": [
									"Key",
									"DisplayName",
									"IsSubjectAssignable"
								]
							},
							"Depth": {
								"type": "integer",
								"format": "int32"
							},
							"ParentKey": {
								"type": [
									"null",
									"string"
								]
							},
							"CustomFieldValues": {
								"type": "array",
								"items": {
									"type": "object",
									"properties": {
										"Key": {
											"type": "string"
										},
										"Name": {
											"type": "string"
										},
										"IsRequired": {
											"type": "boolean"
										},
										"FieldType": {
											"type": "string",
											"enum": [
												"Text",
												"Email",
												"Number",
												"PhoneNumber",
												"DateTime",
												"Date",
												"Time",
												"UserIdentifier"
											]
										},
										"Value": {
											"type": "object",
											"properties": {
												"DataType": {
													"type": "string",
													"enum": [
														"String",
														"Decimal",
														"Integer",
														"DateTime",
														"Date",
														"Time",
														"Boolean"
													]
												},
												"Value": {
													"type": [
														"string",
														"integer",
														"number",
														"boolean",
														"null"
													]
												}
											},
											"required": [
												"DataType"
											]
										}
									},
									"required": [
										"Key",
										"DisplayName",
										"IsRequired",
										"FieldType",
										"Value"
									]
								}
							}
						},
						"required": [
							"Key",
							"DisplayName",
							"StructureType",
							"Depth"
						]
					},
					"Cursor": {
						"type": "string",
					}
				}
			}
		}
	},
	"required": [
		"PageInfo",
		"Edges"
	]
}

• Example

{
	"PageInfo": {
		"HasNextPage": false,
		"HasPreviousPage": false,
		"StartCursor": "AAB",
		"EndCursor": "AAB",
		"TotalCount": 1
	},
	"Edges": [
		{
			"Node": {
				"Key": "AAB",
				"DisplayName": "AAB Department",
				"StructureType": {
					"Key": "dept",
					"DisplayName": "Department",
					"IsSubjectAssignable": true
				},
				"Depth": 1,
				"ParentKey": null
			},
			"Cursor": "AAB"
		}
	]
}

Previous versions

None