A query option is a set of query-level string parameters that controls the amount and order of the data returned by the resource URL.
When calling a Smart Build Insight API with query options, the service request that transformations be applied to the resource data before returning.
-
Such transformations can include filtering, sorting, or ordering options for the data being fetched from the resource endpoint.
-
These query options, supported by Smart Build Insight services, are governed by the OData and standardized by OASIS.
Now, let us consider the following Smart Build Insight API that fetches data based on the resource identified by the URL endpoint.
Example to fetch calendar details by Tenant ID
Provide the TenantId and CalendarId in the resource URL to get calendar details by WorkExceptions, WorkHours, as well as WorkDays.
You can get the TenantId from the client application credentials.
Step 1: Define the resource URL
For example, enter the Smart Build Hostname, the Tenant Id and the Calendar Id for the following Smart Build Insight API endpoint.
https://sbi.<SEVERNAME>.hxgnsmartbuild.com/hxsb-api/v1/Tenants('{TenantId}')/Calendars('{CalendarId}')
Method : GET
You can also append query parameters to the API endpoint based on which Smart Build Insight returns the resources in the response payload.
Step 2: Add Header parameter as well as query parameters (as applicable)
-
First, add authorization header parameter.
-
By default, all Smart APIs can only be accessed with a valid access token passed as an authorization header parameter.
-
This must be passed as key-value pair.
Key
Value
Authorization
Bearer <accessToken>
-
-
Next, define the query options that the Smart Build Insight service will use when returning resource data in the response. For example, this API supports the following OData query parameters.
Query Parameter
Data Type
Description
$expand
String
Indicates the related entities that must be represented inline. This parameter is a comma-separated list of navigation property names. Optionally, it can be followed by a /$ref or /$count path segment.
A parenthesized set of expand options to filter, sort, order, count, select, or expand the related entities.
For example, you can use this parameter to expand the calendar details by WorkException, as well as WorkHours including filters, if applicable.
$select
String
Requests that the service return only the properties, dynamic properties, actions, and functions explicitly requested by the client. This parameter contains a comma-separated list of:
Properties
Qualified action names
Qualified function names
The asterisk operator (*)
The asterisk operator prefixed with the namespace or alias of the schema in order to specify all operations defined in the schema
Only aliases defined in the Smart Build metadata document of the service can be used in URLs.
For example, you can apply select option on WorkHours as well as WorkDays.
$top
Integer
Specifies a non-negative integer n to limit the number of resource items returned from a resource collection to that number.
For example, use the value of 3 along with additional WorkExceptions filters to fetch the first 3 WorkExceptions defined under the calendar.
$skip
Integer
Specifies a non-negative integer n that excludes that many items from the result. The service returns the resource items starting with position n+1.
For example, use the value 3 to ignore the first three query results in the response.
For a complete description of OData Query parameters, see the OASIS OData System Query Options documentation.
Step 3: Send your request to the service
For example, consider the following Smart Build Insight resource URL with query options defined.
https://sbi.<SERVERNAME>.hxgnsmartbuild.com/hxsb-api/v1/Tenants('{TenantId}')/Calendars('{CalendarId}')?$expand=workdays($expand=workhours),workexceptions
Method: GET
-
You must provide the Smart Build Insight hostname, a valid Tenant ID and a valid Calendar ID.
-
The applied query options will expand by WorkDays and WorkExceptions; where WorkDays will also further expand by WorkHours.
Once the Smart Build Insight URL resources and query options are defined, send the service request.
Step 4 : Review your response
Upon successful execution of the API, the response is returned from the Smart Build Insight server based on the query options defined in the request URL. For instance, this is a sample response returned for our example request (as described under Step 3).
The following JSON is an excerpt and solely represents the response layout.
{
"@odata.context": "https://sbi.test.hxgnsmartbuild.com/hxsb-api/v1/$metadata#Tenants('8284741f-5909-41f5-ace4-6bde6ead5411')/Calendars(WorkDays(WorkHours()),WorkExceptions())/$entity",
"Id": "9fc2d377-76de-4777-a6c6-7c2c47229500",
"ConcurrencyToken": null,
"Name": "Hexagon Demo-305",
"CreatedOn": "2020-07-01T04:45:01.662Z",
"CreatedBy": "User_Bgd",
"EditedOn": "2021-05-04T16:18:13.967Z",
"EditedBy": "User_Bgd",
"Description": "Hexagon Demo-305",
"WorkHoursPerDay": 8,
"WorkweekStartDay": 1,
"WorkweekEndDay": 3,
"IsDefault": false,
"WorkDays": [
{
"Id": "a79bc31e-60f4-445d-8251-3124159b7a9b",
"ConcurrencyToken": null,
"Name": null,
"CreatedOn": "2021-05-04T16:18:13.99Z",
"CreatedBy": "User_Bgd",
"EditedOn": null,
"EditedBy": null,
"Day": 2,
"WorkHours": [
{
"Id": "f7bd0c59-e2f5-4d7f-89e8-c628d12251b5",
"ConcurrencyToken": null,
"Name": null,
"CreatedOn": "2021-05-04T16:18:13.991Z",
"CreatedBy": "User_Bgd",
"EditedOn": null,
"EditedBy": null,
"StartTime": 46800,
"EndTime": 61200
},
{
"Id": "1209dc21-a814-4d22-8f9d-f4f2f60320e5",
"ConcurrencyToken": null,
"Name": null,
"CreatedOn": "2021-05-04T16:18:13.991Z",
"CreatedBy": "User_Bgd",
"EditedOn": null,
"EditedBy": null,
"StartTime": 28800,
"EndTime": 43200
}
]
},
{
"Id": "99dda1e4-9166-4bdd-a229-67d066470332",
"ConcurrencyToken": null,
"Name": null,
"CreatedOn": "2021-05-04T16:18:13.988Z",
"CreatedBy": "User_Bgd",
"EditedOn": null,
"EditedBy": null,
"Day": 1,
"WorkHours": [
{
"Id": "21fe4bbf-4a6f-4b37-8e31-24a35f9b3bd8",
"ConcurrencyToken": null,
"Name": null,
"CreatedOn": "2021-05-04T16:18:13.989Z",
"CreatedBy": "User_Bgd",
"EditedOn": null,
"EditedBy": null,
"StartTime": 28800,
"EndTime": 43200
},
{
"Id": "b11b9f0a-e336-4fd2-8c74-968d764ecaf7",
"ConcurrencyToken": null,
"Name": null,
"CreatedOn": "2021-05-04T16:18:13.989Z",
"CreatedBy": "User_Bgd",
"EditedOn": null,
"EditedBy": null,
"StartTime": 46800,
"EndTime": 61200
}
]
}
],
"WorkExceptions": [
{
"Id": "57dc4474-7992-43a3-bb98-32d1c3c4376f",
"ConcurrencyToken": null,
"Name": "Non Work",
"CreatedOn": "2021-05-04T16:18:13.978Z",
"CreatedBy": "User_Bgd",
"EditedOn": null,
"EditedBy": null,
"StartDate": "2013-01-01T12:00:00Z",
"EndDate": "2013-01-01T12:00:00Z",
"IsDayOff": true,
"IsException": false,
"IsHoliday": false
},
{
"Id": "179499ec-7f15-4d48-8a10-0eee9f3c696d",
"ConcurrencyToken": null,
"Name": "Non Work",
"CreatedOn": "2021-05-04T16:18:13.968Z",
"CreatedBy": "User_Bgd",
"EditedOn": null,
"EditedBy": null,
"StartDate": "2010-05-31T12:00:00Z",
"EndDate": "2010-05-31T12:00:00Z",
"IsDayOff": false,
"IsException": true,
"IsHoliday": false
},
{
"Id": "6fb82a20-c879-4225-937c-a891be6083e4",
"ConcurrencyToken": null,
"Name": "Non Work",
"CreatedOn": "2021-05-04T16:18:13.976Z",
"CreatedBy": "User_Bgd",
"EditedOn": null,
"EditedBy": null,
"StartDate": "2012-09-03T12:00:00Z",
"EndDate": "2012-09-03T12:00:00Z",
"IsDayOff": false,
"IsException": false,
"IsHoliday": true
}
]
}