JSON Search Parameters

Describes a set of complex search criteria broken into search, sorting and grouping rules. This structure is used specifically with the Entity service as input to the Find Data Entity resource method.

Search rules can be added to a search rules list and can be used to match data entities based on specific criteria. This rules list also specifies an operator which determines whether all rules or only one rule in the list is required to be matched.

Search rules can be based on data record values, data entity properties, finishing options, document length, template names and whether an entity's identifier is contained or not contained in a list of identifiers.

Rule sets can also be added to the search rules list. Each rule set can contain its own sub list of search rules and its own rule operator. Rule sets can also be added to the search rule list of an existing rule set which allows for the construction of complex nested search criteria.

Note that as of version 2019.2, search criteria need to specify a "ruleType" instead of a "type" name/value pair (the old format).

Sorting rules can be also added to a sort rules list and (depending on the data entity type) can be used to sort data entity entries in the search results by either data record values or data entity properties.

Every sort rule added will expand the value of the sort key of each entry listed in the resulting JSON Identifier Lists (with Sort Key) structure.

Grouping rules can be also added to a group rules list and (depending on the data entity type) can be used to group data entity entries in the search results by either data record values or data entity properties.

Every group rule added can expand the number of sub lists contained in the resulting JSON Identifier Lists (with Sort Key) structure.

Certain search, sorting or grouping rules can only be used with specific data entity types.

See the Finding Specific Data Entities in the Server page of the Working Examples section for further detail on the available rule combinations.

Structure

The structure consists of an object with the following name/value pairs:

  • entity – the data entity type (value of either DATARECORDS, DATASETS, CONTENTITEMS, CONTENTSETS, JOBS or JOBSETS)

  • setids (optional) - an array of one or more dataset/contentset/jobset IDs

  • search – search criteria, consisting of an object with the following name/value pairs:

    • ruleType – the topmost RULESET

    • condition – the logic rule for this RULESET (value of ALL, ANY, NOTALL or NOTANY)

    • rules – a base list of search rules, consisting of an array of objects each with a specific rule sub-structure depending on the type of rule. This could include nested rule sets.

  • sort – a list of sorting rules, consisting of an array of objects each with the following name/value pairs:

    • type – the type of sorting rule (value of either value or property)
    • name – the name of the data value field or data entity property to sort by (type of string)
    • numeric – whether the data value field is a of a numeric type (type of boolean)
      (only available when sorting on value fields)
    • order – the order that matches to this rule are sorted by (value of either ASC or DESC)

  • group – a list of grouping rules, consisting of an array of objects each with the following name/value pairs:

    • type – the type of grouping rule (value of either value or property)

    • name – the name of the data value field or data entity property to group by (type of string)

    • numeric – whether the data value field is a of a numeric type (type of boolean)
      (only available when grouping on value fields)

    • order – the order that matches to this rule are grouped by (value of either ASC or DESC)

The search rule sub-structure consists of an object with rule specific groupings of name/value pairs.
These include the following:

    Data Value search – Search for data entities based on the value of a data record field.
    Comprises objects containing the following name/value pairs:

    • ruleType – VALUE

    • fieldName – the name of the data record field (type of string)

    • condition – the comparison condition (value of either EQ (=), NE (!=), LT (<), GT (>), LTE (<=), GTE (>=), CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH, LIKE, NOT_LIKE)

    • value – the comparison value
      Can be one of either of the following, depending upon data field selection:

      • For data field name:  These comprise objects containing the following name/value pairs:

        • type – FIELD

        • value – the comparison value (type of string)

      • For data field value:  value1 – the comparison value (type of string)


    Property Value search – Search for data entities based on the value of a data entity property
    Comprises objects containing the following name/value pairs:

    • ruleType – PROPERTY

    • property – the name of the data entity property (type of string)

    • condition – the comparison condition (value of either EQ (=), NE (!=), LT (<), GT (>), LTE (<=), GTE (>=), CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH, LIKE, NOT_LIKE)

    • value – the comparison value
      Can be one of either of the following, depending upon property type selection:

      • For property name:  These comprise objects containing the following name/value pairs:

        • type – FIELD

        • value – the comparison value (type of string)

      • For property value:  value – the comparison value (type of string)


    Value In search – search for the data values contained within a list.
    Comprises objects containing the following name/value pairs:

    • ruleType – VALUEIN

    • field – the field name (type of string)

    • dataType – the data type to search (value of either FIELD or PROPERTY)

    • condition – the comparison condition (value of either IN or NOT_IN)

    • values – the list of data entities (type of string, or array of strings


    ID In search – search for the ID values contained within a list.
    Comprises objects containing the following name/value pairs:

    • ruleType – IDIN

    • condition – the comparison condition (value of eitherIN or NOT_IN)

    • values – the list of IDs (type of number, or array of numbers


    Document Media search – search on the media used.
    Comprises objects containing the following name/value pairs:

    • ruleType – DOCMEDIA

    • attribute – the document media attribute being searched for (value of either media name (NAME), or front/rear (FRONT_COATING/BACK_COATING) sheet coating)

    • condition – the comparison condition (value of either CONTAINS or NOT_CONTAINS)

    The comparison value. Can be one of either of the following, depending upon the attribute selection:

    • name – the media name (type of string)
      (only available for attribute = NAME selections)

    • coating – the specified media sheet coating (value of either UNSPECIFIED, NONE, COATED, GLOSSY, HIGH_GLOSS, INKJET, MATTE, SATIN or SEMI_GLOSS)
      (only available for attribute = FRONT_COATING or BACK_COATING selections)


    Document Binding search – search on how the finished documents are bound.
    Comprises objects containing the following name/value pairs:

    • ruleType – DOCBINDING

    • attribute – the document binding attribute being searched for (value of STYLE, SIDE, LOCATION,or ANGLE)

    • condition – the comparison condition (value of either CONTAINS or NOT_CONTAINS)

    The comparison value. Can be one of either of the following, depending upon the attribute selection:

    • bindingStyle – the binding style of the media used (value of either NONE, DEFAULT, STAPLED, GLUED, STITCHED, ADHESIVE, SPINETAPING, RING, WIREDCOMB, PLASTICCOMB or COIL)
      (only available for attribute = STYLE selections)

    • bindingEdge – the binding edge of the media used (value of either DEFAULT, LEFT, RIGHT, TOP or BOTTOM)
      (only available for attribute = SIDE selections)

    • bindingType – the binding type of the media used (value of either DEFAULT, SADDLE, SIDE or CORNER)
      (only available for attribute LOCATION selections)

    • bindingAngle – the binding angle of the media used (value of either DEFAULT, VERTICAL, HORIZONTAL or ANGLE)
      (only available for attribute = ANGLE selections)


    Document Size search – search on document size.
    Comprises objects containing the following name/value pairs:

    • ruleType – DOCSIZE

    • entity – the document size attribute being searched for (value of PAGE, SHEET, or SECTION)

    • condition – the comparison condition (value of either EQ (=), NE (!=), LT (<), GT (>), LTE (<=) or GTE (>=))

    • value – the comparison value (type of number)


    Duplex search – search on whether the document contains any duplex sheets.
    Comprises objects containing the following name/value pairs:

    • ruleType – DUPLEX

    • condition – whether the document contains any duplex sheets or not (value of either "HAS_DUPLEX" or SIMPLEX_ONLY)


    Template search – searches based on the name of the template used during Content Creation.
    Comprises objects containing the following name/value pairs:

    • ruleType – TEMPLATE

    • condition – the comparison condition (value of either EQ (=) or NE (!=))

    • name – the comparison value (type of string)


    Rule Set searches – construct a set of rules that are evaluated collectively.
    Comprises objects containing the following name/value pairs:

    • ruleType – RULESET

    • condition – the logic rule for this RULESET (value of ALL, ANY, NOTALL or NOTANY)

    • rules – a sub-list of search rules, consisting of an array of objects each with a certain rule sub-structure depending on the type of rule

Example

The following is an example of this structure:

{
    "entity": "CONTENTITEMS",
    "search": {
        "ruleType": "RULESET",
        "condition": "ALL",
        "rules": [
            {
                "ruleType": "DUPLEX",
                "condition": "HAS_DUPLEX"
            },
            {
                "ruleType": "TEMPLATE",
                "condition": "EQ",
                "name": "Rural"
            },
            {
                "ruleType": "RULESET",
                "condition": "ALL",
                "rules": [
                    {
                        "ruleType": "DOCMEDIA",
                        "attribute": "NAME",
                        "condition": "CONTAINS",
                        "name": "Impact"
                    },
                    {
                        "ruleType": "DOCMEDIA",
                        "attribute": "FRONT_COATING",
                        "condition": "CONTAINS",
                        "coating": "HIGH_GLOSS"
                    },
                    {
                        "ruleType": "DOCMEDIA",
                        "attribute": "BACK_COATING",
                        "condition": "CONTAINS",
                        "coating": "SEMI_GLOSS"
                    }
                ]
            },
            {
                "ruleType": "RULESET",
                "condition": "ALL",
                "rules": [
                    {
                        "ruleType": "DOCBINDING",
                        "attribute": "STYLE",
                        "condition": "CONTAINS",
                        "bindingStyle": "STAPLED"
                    },
                    {
                        "ruleType": "DOCBINDING",
                        "attribute": "SIDE",
                        "condition": "CONTAINS",
                        "bindingEdge": "LEFT"
                    },
                    {
                        "ruleType": "DOCBINDING",
                        "attribute": "LOCATION",
                        "condition": "CONTAINS",
                        "bindingType": "SIDE"
                    },
                    {
                        "ruleType": "DOCBINDING",
                        "attribute": "ANGLE",
                        "condition": "CONTAINS",
                        "bindingAngle": "ANGLE"
                    }
                ]
            },
            {
                "ruleType": "RULESET",
                "condition": "ALL",
                "rules": [
                    {
                        "ruleType": "DOCSIZE",
                        "entity": "PAGE",
                        "condition": "GT",
                        "value": 4
                    },
                    {
                        "ruleType": "DOCSIZE",
                        "entity": "SHEET",
                        "condition": "GT",
                        "value": 2
                    },
                    {
                        "ruleType": "DOCSIZE",
                        "entity": "SECTION",
                        "condition": "GT",
                        "value": 1
                    }
                ]
            }
        ]
    },
    "sort": [
        {
            "type": "value",
            "name": "LastName",
            "numeric": false,
            "order": "ASC"
        }
    ],
    "group": [
        {
            "type": "value",
            "name": "Gender",
            "numeric": false,
            "order": "ASC"
        }
    ]
}