The following describes MTAPI-SRQL language: the MTOA Service Request Query Language used to perform filtering of Service Requests
via the “POST /api/v1/servicerequests/query” endpoint.
The MTAPI-SRQL language allows Service Request to be filtered using a set of filter type. The current supported types are:
Status
PlaceOfSupply
ServiceAttributes
RegulatedEntity-{REGULATED_ENTITY_ID}
Note the following use-cases are currently using the dataset available in MTOA-PLATFORM-TEST.
MITRACK USECASES
Query Service Requests but also include the Service Request Status History associated with each Service Request
This can be done by setting the "IncludeStatusHistory" property to true.
{
"UserId": 10005,
"IncludeStatusHistory": true,
"Page": 1,
"PageSize": 25,
}
The returned Service Request List payload will include the Service Request Status history within each Service Request in as follow:
{
"ServiceRequests": [
...
{
"StatusHistory": [
{
"ServiceHistoryEntryId": 12054,
"Status": "Submitted",
"EnglishDisplayName": "Submitted",
"FrenchDisplayName": "Soumise",
"Date": "2021-08-18T18:34:41",
"ServiceCategoryCode": "ON",
"ServiceStandardId": 0
},
{
"ServiceHistoryEntryId": 12051,
"Status": "InProgress",
"EnglishDisplayName": "In-Progress",
"FrenchDisplayName": "En cours",
"Date": "2021-08-19T18:34:33",
"ServiceCategoryCode": "OFF",
"ServiceStandardId": 0
}
],
"DateUpdatedUtc": "2021-08-18T22:34:41",
}
Query a list of Services by specifying the Service Ids in a comma delimited list
Because different services might not support the same Metadata fields, ExcludeMetadata must be set to true.
{
"Services":"230,231,232",
"ExcludeMetadata": true,
"IncludeRegulatedEntities": true,
"Page": 1,
"PageSize": 25
}
Query a list of ServiceRequests by specifying the Service Request Ids in a comma delimited list
Because different ServicesRquests might not support the same Metadata fields, ExcludeMetadata must be set to true.
{
"ServiceRequests": "15215,15216,15217,15218",
"ExcludeMetadata": true,
"IncludeRegulatedEntities": true,
"Page": 1,
"PageSize": 25
}
Include the Regulated Entities data inside the dataset that contains a list of Service Requests
Query a single regulated entity such using an IMO number
The query needs to support full matches for the IMO number
{
"Services":"230,231,232",
"ExcludeMetadata": true,
"IncludeRegulatedEntities": true,
"Page": 1,
"PageSize": 25,
"Filter": "RegulatedEntity-IMO='Value_2'"
}
IMO could be replaced by any of the Regulated Entity Identifiers: {VESSEL_NM, CDN_SHIP_IND, IMO, OFFICIAL_NO}
That query needs to support partial matches for Vessel Names
{
"ServiceId": 230,
"ExcludeMetadata": false,
"IncludeRegulatedEntities": true,
"Page": 1,
"PageSize": 25,
"Filter": "RegulatedEntity-VESSEL_NM.Contains('Value')"
}
The .Contains('text') indicates partial matches.
Query a list of ServiceAttributes (by specifying the ServiceAttribute Ids in a comma delimited list)
{
"ServiceId": 2,
"ExcludeMetadata": false,
"IncludeRegulatedEntities": true,
"Page": 1,
"PageSize": 25,
"Filter": "ServiceAttributes='98,99,100'"
}
Query a list of ServiceRequest Statuses (by specifying the ServiceRequest Statuses in a comma delimited list)
{
"ServiceId": 2,
"ExcludeMetadata": false,
"IncludeRegulatedEntities": true,
"Page": 1,
"PageSize": 25,
"Filter": "Status='Draft,InProgress,Submitted'"
}
We should be able to use the filters in multiple permutations
ex1:
{
"ServiceId": 2,
"ExcludeMetadata": false,
"IncludeRegulatedEntities": true,
"Page": 1,
"PageSize": 25,
"Filter": "Status='Draft,InProgress,Submitted' and ServiceAttributes='98,99,100'"
}
ex2:
{
"UserId": 8872,
"ExcludeMetadata": true,
"IncludeRegulatedEntities": true,
"Page": 1,
"PageSize": 25,
"Filter": "Status='Draft,InProgress' AND RegulatedEntity-IMO='Value_2'"
}
ex3:
{
"UserId": 8872,
"ExcludeMetadata": true,
"IncludeRegulatedEntities": true,
"Page": 1,
"PageSize": 25,
"Filter": "Status='Draft,InProgress' AND RegulatedEntity-IMO='Value_2' and PlaceOfSupply='ON'"
}
However the following adding multiple variants of the same filter attribute is not permitted
"Filter": "RegulatedEntity-IMO='Value_2' AND RegulatedEntity-OFFICIAL_NO ='1234' "
The difference between this filter and the previous examples is that RegulatedEntity-IMO OR RegulatedEntity- OFFICIAL_NO are the same filter type RegulatedEntity
Similarly:
"Filter": "Status='Draft’ OR Status=’InProgress’ is not supported but "Filter": "Status='Draft, InProgress’ is supported.
Query a list of ServiceRequest using a Date Range using the “DateRangeUtc” keyword
{
"UserId": 9873,
"ServiceId": 0,
"Services": null,
"OrganizationId": 0,
"IncludeRegulatedEntities": false,
"Page": 1,
"PageSize": 25,
"Filter": "DateRangeUtc=20210801-20210803"
}
DateRangeUtc=20210802 - Query the date for a single given day (inclusive)
DateRangeUtc=20210802-20210802 - Query the date for a given range (inclusive)
Specifying a Sort Order
{
"UserId": 9873,
"ServiceId": 0,
"Services": null,
"OrganizationId": 0,
"IncludeRegulatedEntities": false,
"Page": 1,
"PageSize": 25,
"Filter": "DateRangeUtc=20210801-20210803"
}
OrderBy Syntax
OrderBy-{Id|Date}={Asc|Ascending|Desc|Descending} the query itself is case insensitive
Notes
OrderBy-Id=Ascending is the same as OrderBy-Id=Asc
OrderBy-Date=Ascending is the same as OrderBy-Date=Asc
OrderBy-Id=Descending is the same as OrderBy-Id=Desc and is the same as OrderBy-Id (without using a sort direction)
OrderBy-Date=Descending is the same as OrderBy-Id=Desc and is the same as OrderBy-Date (without using a sort direction)
OrderBy Syntax
OrderBy-{Id|Date}={Asc|Ascending|Desc|Descending} the query itself is case insensitive
Notes
OrderBy-Id=Ascending is the same as OrderBy-Id=Asc
OrderBy-Date=Ascending is the same as OrderBy-Date=Asc
OrderBy-Id=Descending is the same as OrderBy-Id=Desc and is the same as OrderBy-Id (without using a sort direction)
OrderBy-Date=Descending is the same as OrderBy-Id=Desc and is the same as OrderBy-Date (without using a sort direction)
Know Issues
PlaceOfSupply is case sensitive
If an unsupported type is being used, it will be discarded .
Service Requests will be retrieving without taking that condition into account.