Search and Include

Search Criteria

Data returned from an API call can be filtered to a specific subset before being returned based on a search string passed to the API in the request body using the searchCriteria request parameter. A filter is applied as filterName(fieldname,comparisonValue) where the comparison value is applicable based on the filter being used.

Syntax: filterName(fieldname,comparisonValue)

For example, searchCriteria: "where equals(menuItems.active,Y)" returns the active menu item records.

Using Multiple Search Criteria

Multiple search criteria can be strung together using AND and OR logical operators and grouped by using parentheses when nesting search criteria.

Syntax: filterName(fieldname,comparisonValue) <Logical Operator> filterName(fieldname,comparisonValue)

For example, searchCriteria: "equals(active,1)" limits the response to only contain rows where the top level field active has a value of 1. The statement searchCriteria: "(equals(active,1) and equals(type,1))" further limits the response to only rows that were both active and of type 1.

Negating the Filter Condition

Use the symbol ! to apply a value of NOT to any filter that reverses the filter condition.

Syntax: !(filterName(fieldname,comparisonValue))

For example, the statement searchCriteria: "!(equals(active,1))" further limits the response to the rows that are not active.

Available Search Criteria Filters

Consider the following example from a guest check API response:

{
    "curUTC": "2019-07-20T17:59:59",
    "locRef": "1234",
    "guestChecks":[{
        "guestCheckId":124563,
        "chkNum": 7,
        "chkName": "Check Name",
        "opnBusDt": "2019-07-20",
        "opnUTC": "2019-07-20T15:20:20",
        "clsdBusDt": "2019-07-20",
        "clsdUTC": "2019-07-20T16:16:10",
        "reopnClsdChkClsdBusDt":"2019-07-20",
        "reopnClsdChkClsdUTC":"2019-07-20T16:16:10",
        "lastUpdatedUTC": "2019-07-20T16:16:10",
        "clsdFlag": true,
        "gstCnt": 2,
        "subTtl": 123.50,
        "autoSvcTtl": 0.00,
        "svcChgTtl": 2.50,
        "nonTxblSlsTtl":1.25,
        "txblSlsTtl":22.00,
        "taxExmpSlsTtl":1.75,
        "taxCollTtl": 1.45,
        "chkTtl": 25.00,
        "dscTtl": 3.00,
        "payTtl": 0.00,
        "balDueTtl": 0.00,
        "reopenFrmChk": 1,
        "reopenToChk": 1,
        "spltFrmChk": 1,
        "rvcNum": 123,
        "otNum": 12,
        "tblNum": 123,
        "tblName": "123",
        "empNum": 21334,
        "chkInfo": "Manually Entered Text",
        "taxes":[{
            "taxNum":123,
            "txblSlsTtl":12.34,
            "taxCollTtl":1.34,
        }]
         .....
         .....
    }]
}

You can use the following filters to filter the response in the API request:

Filter Name Filter Description Supported Data Type Parameter 1 Parameter 2 Example

equals

Searches for records where the specified column's value is exactly equal to the comparison value

All

Column name

Comparison value

equals(guestChecks.chkNum,7)

equalsIgnoreCase

Searches for records where the specified column's value is equal to the comparison value without considering the string value's case

String

Column name

Comparison value

equalsIgnoreCase(guestChecks.chkName,"Check Name")

greaterThan

Searches for records where the specified column's value is greater than the comparison value

Any numeric type

Column name

Comparison value

greaterThan(guestChecks.dscTtl,0)

lessThan

Searches for records where the specified column's value is less than the comparison value

Any numeric type

Column name

Comparison value

lessThan(guestChecks.chkTtl, 5)

isNull

Searches for records where the specified column's value is equal to null

All

Column name

N/A

isNull(guestChecks.tblName)

contains

Searches for records where the specified column's value contains the comparison value

String

Column name

Comparison value

contains(guestChecks.chkInfo,"review")

startsWith

Searches for records where the specified column's value starts with the comparison value

String

Column name

Comparison value

startsWith(guestChecks.chkName,"Check")

endsWith

Searches for records where specified column's value ends with the comparison value

String

Column name

Comparison value

endsWith(guestChecks.chkName,"Name")

Search Criteria Considerations

  1. The type of data applied for "comparisionValue" must be of the same as the underlying type of "fieldName".

  2. Enclose strings in single quotes when using "comparisonValue".

  3. Nested objects must be indicated by prepending the parent object name(s) to the field.

    For example, for the following structure, the response returned inside the revenue centers listed may be limited based on Service Charge Number 12345 by passing "searchCriteria: equals(revenueCenters.serviceCharges.svcNum,12345)" in the API request body.

    {
        "locRef":"1234",
        "busDt: "2020-07-20",
        "revenueCenters":[{
            "rvcNum": 1372,
            "serviceCharges":[{
                "svcNum": 12345,
                "ttl": 1234.56,
                "cnt": 123
        }]
    }

Include

All the Oracle MICROS REST APIs return a set of default attributes as part of the response. There could also be some default attributes which might not be returned in the response in case their value is Null, 0, or False. Please refer the detailed API documentation for understanding the attributes in the response. The optional attributes can be retrieved using the include request parameter.

 Use the include request parameters to retrieve a specific attribute from the API response. Using the include parameter will override the default behavior of the attributes in the response and will return only the response attributes mentioned in the request.

Syntax: include: "fieldName1, fieldName2....fieldNameN"

For example, using include: "locRef, busDt, revenueCenters.num, revenuCenters.name" returns the revenue center name and revenue center number from the getRevenueCenterDimensions API instead of the entire response.

{
    "locRef":"1234",
    "busDt: "2020-07-20",
    "revenueCenters":[{
        "num": 152,
        "name": "Bar"
    }]
}

Note:

Use the parent object's name with the object name when using the include request parameter.