URL Query Options - HxGN Smart Build - 4.0 U10 (4.0.10) - Help - Hexagon

HxGN Smart Build Insight API Help

Language
English (United States)
Product
HxGN Smart Build
Search by Category
Help

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 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 services, are governed by the OData and standardized by OASIS.

Now, let us consider the following Smart Build 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.

Please contact Smart Build support for TenantId.

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 API endpoint.

https://apigwy.intergraphsmartcloud.com/hxsb-<SERVERNAME>-api/v1/Tenants('{TenantId}')/Calendars('{CalendarId}')

Method : GET

You can also append query parameters to the API endpoint based on which Smart Build returns the resources in the response payload.

Step 2: Add Header parameter as well as query parameters (as applicable)

  1. 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>

  2. Next, define the query options that the Smart Build 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.

SHARED Tip 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 resource URL with query options defined.

https:https://apigwy.intergraphsmartcloud.com/hxsb-<SERVERNAME>-api/v1/Tenants('{TenantId}')/Calendars('{CalendarId}')?$expand=workdays($expand=workhours),workexceptions

Method: GET

  • You must provide the Smart Build 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 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 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://apigwy.intergraphsmartcloud.com/hxsb-test-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

}

]

}