MTAPI-SRQL Language Specifications

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 Service Request Assignees by specifying user Ids (the Assignees) in a comma delimited list

{
  "Assignees": "11577,11578",
  "IncludeRegulatedEntities": true,
  "Page": 1,
  "PageSize": 25
}

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.

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.

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

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

The .Contains('text') indicates partial matches.

Query a list of ServiceAttributes (by specifying the ServiceAttribute Ids in a comma delimited list)

Query a list of ServiceRequest Statuses (by specifying the ServiceRequest Statuses in a comma delimited list)

We should be able to use the filters in multiple permutations

ex1:

ex2:

ex3:

However the following adding multiple variants of the same filter attribute is not permitted

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

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

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.