Retrieve Classification

Retrieves objects that support document classification.

The Policy Management APIs provide an abstracted layer on top of entity extraction, categorization, and related functionality to allow the definition of policies for the management of information. Classifications can be created to group documents and other objects into collections. Policies enact actions upon documents associated with a collection such as indexing.

Classification involves sorting documents into Collections; all documents in a collection share some common criteria, identified using Conditions.

The collection or collections that a document matches can influence how it is indexed and determine policies that are executed against it.

A Collection Sequence is an ordered list of collections that documents are assessed against; each collection is considered in order until the document matches a collection with a stop on match instruction. Documents can match multiple collections in a collection sequence.

The Retrieve Classification API allows collection sequences, collections, conditions, field sources, lexicons, and lexicon expressions to be retrieved.

Quick Start

Using this API you can retrieve classification objects. For example:

/1/api/[async|sync]/retrieveclassificationobjects/v1?type=collection_sequence&id=1&id=2

The following classification object types can be retrieved:

  • collection. A set of documents that share some common criteria.
  • collection sequence. An ordered set of Collections.
  • condition. Each Collection is identified using one or more Conditions.
  • field source. Information on how to retrieve a property value from a document for Condition assessment.
  • lexicon. A list of terms, phrases, or expressions that can be used when defining Conditions.
  • lexicon expression. An entry in a Lexicon.

Start and max_page_results can be used to specify the first object and the number of objects to return.

The additional parameter takes a JSON object specifying additional parameters that can be provided for Collection, Condition, or Field Source object types.

Collection

An example of the required format for additional JSON for a collection is:

{
    "include_condition" : true,
    "include_children" : false
}

Include_condition indicates whether details should be returned for the conditions of the collection.

Include_children indicates whether child conditions for Boolean and Not conditions should be returned.

Condition

An example of the required format for additional JSON for a condition is:

{
    "include_children" : true
}

Include_children indicates whether child conditions for Boolean and Not conditions should be returned.

Field Source

An example of the required format for additional JSON for a field source is:

{
    "name" : "Field 1"
}

Name is used to request information for a specific field source.

Objects of type collection are returned in the following format when include_condition is true:

{
    "id" : 34,
    "name" : "Collection 1",
    "description" : "Description for collection 1 ",
    "type" : "collection",
    "additional" : {
        "condition" : {
        "type" : "condition",
        "additional" : {
            "type" : "number",
            "field" : "SIZE",
            "operator" : "gt"
        }
    }
    "policy_ids" : [3,4]
}

Objects of type collection sequence are returned in the following format:

{
    "id": 2,
    "name": "Collection Sequence 1",
    "description": "Description for collection sequence 1",
    "type": "collection_sequence",
    "additional": {
        "collection_count": 2,
        "collection_sequence_entries": [{
            "order": 100,
            "collection_ids": [125,77],
            "stop_on_match": false
        }],
        "default_collection_id": 4,
        "full_condition_evaluation": true,
        "modified_timestamp": "2014-12-08T17:54:40.000Z"
    }
}

Objects of type condition are returned in the following format:

{
    "id": 1994,
    "name": "Key Field Exists",
    "description": "",
    "type": "condition",
    "additional": {
        "type": "exists",
        "field": "KEY_FIELD",
        "notes": "Infomation about the condition"
    }
}

Objects of type field source are returned in the following format:

{
      "id": 1,
      "name": "CCE_ADDRESS_AU",
      "description": null,
      "type": "field_source",
      "additional": {
        "field_type": "string",
        "source_arguments": {
          "eduction_onpremise": [
            {
              "entity_type": "address_au.ecr",
              "entity_name": [
                "address/au",
                "address/city_state_postcode/au"
              ],
              "field_source": "DRECONTENT"
            }
          ],
          "eduction": [
            {
              "entity_type": [
                "address_au"
              ],
              "field_source": "CONTENT"
            }
          ],
          "fields": null
        }
      }
    }

Objects of type lexicon are returned in the following format:

{
    "id": 17,
    "name": "Animals",
    "description": "Finds documents relating to animals of interest.",
    "type": "lexicon",
    "additional": {
        "lexicon_expressions": [{
            "id": 17,
            "name": "African Elephant check",
            "description": "Checks for african elephants",
            "type" : "text",
            "expression" : "african DNEAR elephants"
        }]
    }
}

Objects of type lexicon expression are returned in the following format:

{
    "id": 17,
    "name": "African Elephant check",
    "description": "Checks for african elephants",
    "type": "lexicon_expression",
    "additional": {
        "lexicon_id": 17,
        "type": "text",
        "expression": "african DNEAR elephants"
    }
}
Synchronous
https://api.havenondemand.com/1/api/sync/retrieveclassificationobjects/v1
Asynchronous
https://api.havenondemand.com/1/api/async/retrieveclassificationobjects/v1
Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
type
enum The type of classification object.
Optional
Name Type Description
additional
json Specify a JSON object of additional parameters relevant for the type of policy object being retrieved.
id
array<number> The IDs of the object or objects to retrieve.
max_page_results
number The maximum number of results to return. If you have set the Start parameter, max_page_results sets the maximum number of results to return from the total results set. Default value: 6.
start
number The number of the first object to retrieve. Default value: 1.
Enumeration Types

This API's parameters use the enumerations described below:

type
The type of classification object.
collection_sequence Collection Sequence
A Collection Sequence classification object.
collection Collection
A Collection classification object.
condition Condition
A Condition classification object.
field_source Field Source
Defines actions to be taken to populate missing fields.
lexicon Lexicon
A Lexicon classification object.
lexicon_expression Lexicon Expression
A Lexicon Expression classification object.

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Retrieve Classification Response {
results ( array[Results] )
totalhits ( number , optional) The total number of results.
}
Retrieve Classification Response:Results {
One of the following: Collection_sequence or Collection or object,null or Lexicon or Lexicon_expression or Field_source
additional ( , optional) JSON-formatted additional information depending on the object type. See the schema for more details
description ( , optional) The description of the classification object.
id ( number ) The ID of the classification object.
name ( , optional) The name of the classification object.
type ( enum<Type> ) The type of the classification object.
}
enum<Retrieve Classification Response:Results:Type> {
'collection_sequence' , 'collection' , 'condition' , 'lexicon' , 'lexicon_expression'
}
Collection_sequence {
additional ( Additional , optional)
type ( enum<Type> , optional)
}
enum<Collection_sequence:Type> {
'collection_sequence'
}
Collection_sequence:Additional {
collection_sequence_entries ( , optional)
default_collection_id ( , optional)
full_condition_evaluation ( , optional) True causes all conditions within a Boolean OR condition to be evaluated instead of stopping after the first matching condition.
modified_timestamp ( string , optional) The most recent modification datetime of any component of this collection sequence in ISO 8601 YYYY-MM-DDThh:mm:ssTZD
}
Collection {
additional ( , optional)
type ( enum<Type> , optional)
}
enum<Collection:Type> {
'collection'
}
Lexicon {
additional ( , optional)
type ( enum<Type> , optional)
}
enum<Lexicon:Type> {
'lexicon'
}
Lexicon_expression {
additional ( , optional)
type ( enum<Type> , optional)
}
enum<Lexicon_expression:Type> {
'lexicon_expression'
}
Field_source {
additional ( Additional , optional)
type ( enum<Type> , optional)
}
enum<Field_source:Type> {
'field_source'
}
Field_source:Additional {
field_type ( string , optional)
source_arguments ( Source_arguments , optional) The arguments for the field source.
}
Field_source:Additional:Source_arguments {
eduction ( , optional)
eduction_onpremise ( , optional)
fields ( , optional)
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "definitions": {
        "boolean_condition": {
            "properties": {
                "children": {
                    "items": {
                        "$ref": "#/definitions/condition"
                    },
                    "type": [
                        "array",
                        "null"
                    ]
                },
                "operator": {
                    "enum": [
                        "and",
                        "or"
                    ],
                    "type": "string"
                },
                "type": {
                    "enum": [
                        "boolean"
                    ]
                }
            },
            "required": [
                "operator"
            ],
            "type": "object"
        },
        "collection": {
            "properties": {
                "additional": {
                    "properties": {
                        "condition": {
                            "$ref": "#/definitions/condition"
                        },
                        "policy_ids": {
                            "items": {
                                "multipleOf": 1,
                                "type": "number"
                            },
                            "type": [
                                "array",
                                "null"
                            ]
                        }
                    },
                    "type": [
                        "object",
                        "null"
                    ]
                },
                "type": {
                    "enum": [
                        "collection"
                    ]
                }
            },
            "required": [
                "name"
            ],
            "type": "object"
        },
        "collection_sequence": {
            "properties": {
                "additional": {
                    "properties": {
                        "collection_sequence_entries": {
                            "items": {
                                "$ref": "#/definitions/collection_sequence_entry"
                            },
                            "type": [
                                "array",
                                "null"
                            ]
                        },
                        "default_collection_id": {
                            "multipleOf": 1,
                            "type": [
                                "number",
                                "null"
                            ]
                        },
                        "full_condition_evaluation": {
                            "type": [
                                "boolean",
                                "null"
                            ]
                        },
                        "modified_timestamp": {
                            "type": "string"
                        }
                    },
                    "type": "object"
                },
                "type": {
                    "enum": [
                        "collection_sequence"
                    ]
                }
            },
            "required": [
                "name",
                "modified_timestamp"
            ],
            "type": "object"
        },
        "collection_sequence_entry": {
            "properties": {
                "collection_ids": {
                    "items": {
                        "multipleOf": 1,
                        "type": "number"
                    },
                    "type": [
                        "array",
                        "null"
                    ]
                },
                "order": {
                    "multipleOf": 1,
                    "type": "number"
                },
                "stop_on_match": {
                    "type": [
                        "boolean",
                        "null"
                    ]
                }
            },
            "type": "object"
        },
        "condition": {
            "properties": {
                "additional": {
                    "oneOf": [
                        {
                            "$ref": "#/definitions/boolean_condition"
                        },
                        {
                            "$ref": "#/definitions/regex_condition"
                        },
                        {
                            "$ref": "#/definitions/date_condition"
                        },
                        {
                            "$ref": "#/definitions/exists_condition"
                        },
                        {
                            "$ref": "#/definitions/fragment_condition"
                        },
                        {
                            "$ref": "#/definitions/lexicon_condition"
                        },
                        {
                            "$ref": "#/definitions/not_condition"
                        },
                        {
                            "$ref": "#/definitions/number_condition"
                        },
                        {
                            "$ref": "#/definitions/string_condition"
                        },
                        {
                            "$ref": "#/definitions/text_condition"
                        }
                    ],
                    "properties": {
                        "include_descendants": {
                            "type": "boolean"
                        },
                        "notes": {
                            "type": [
                                "string",
                                "null"
                            ]
                        },
                        "target": {
                            "enum": [
                                "all",
                                "children",
                                "container"
                            ]
                        },
                        "type": {
                            "enum": [
                                "boolean",
                                "regex",
                                "date",
                                "fragment",
                                "lexicon",
                                "not",
                                "number",
                                "string",
                                "exists",
                                "text"
                            ]
                        }
                    },
                    "required": [
                        "type"
                    ],
                    "type": "object"
                },
                "type": {
                    "enum": [
                        "condition"
                    ]
                }
            },
            "required": [
                "additional"
            ],
            "type": [
                "object",
                "null"
            ]
        },
        "date_condition": {
            "properties": {
                "field": {
                    "$ref": "#/definitions/field"
                },
                "operator": {
                    "enum": [
                        "before",
                        "after",
                        "on"
                    ]
                },
                "type": {
                    "enum": [
                        "date"
                    ]
                },
                "value": {
                    "minLength": 1,
                    "type": "string"
                }
            },
            "required": [
                "field",
                "value",
                "operator"
            ],
            "type": "object"
        },
        "eduction": {
            "properties": {
                "entity_name": {
                    "items": {
                        "type": "string"
                    },
                    "type": [
                        "array",
                        "null"
                    ]
                },
                "entity_type": {
                    "items": {
                        "type": "string"
                    },
                    "type": "array"
                },
                "field_source": {
                    "type": "string"
                }
            },
            "type": "object"
        },
        "eduction_onpremise": {
            "properties": {
                "entity_name": {
                    "items": {
                        "type": "string"
                    },
                    "type": "array"
                },
                "entity_type": {
                    "type": "string"
                },
                "field_source": {
                    "type": "string"
                }
            },
            "type": "object"
        },
        "exists_condition": {
            "properties": {
                "field": {
                    "$ref": "#/definitions/field"
                },
                "type": {
                    "enum": [
                        "exists"
                    ]
                }
            },
            "required": [
                "field"
            ],
            "type": "object"
        },
        "field": {
            "minLength": 1,
            "type": "string"
        },
        "field_source": {
            "properties": {
                "additional": {
                    "properties": {
                        "field_type": {
                            "enum": [
                                "date",
                                "number",
                                "string"
                            ],
                            "type": "string"
                        },
                        "source_arguments": {
                            "properties": {
                                "eduction": {
                                    "items": {
                                        "$ref": "#/definitions/eduction"
                                    },
                                    "type": [
                                        "array",
                                        "null"
                                    ]
                                },
                                "eduction_onpremise": {
                                    "items": {
                                        "$ref": "#/definitions/eduction_onpremise"
                                    },
                                    "type": [
                                        "array",
                                        "null"
                                    ]
                                },
                                "fields": {
                                    "items": {
                                        "type": "string"
                                    },
                                    "type": [
                                        "array",
                                        "null"
                                    ]
                                }
                            },
                            "type": "object"
                        }
                    },
                    "type": "object"
                },
                "type": {
                    "enum": [
                        "field_source"
                    ]
                }
            },
            "required": [
                "name"
            ],
            "type": "object"
        },
        "fragment_condition": {
            "properties": {
                "type": {
                    "enum": [
                        "fragment"
                    ]
                },
                "value": {
                    "multipleOf": 1,
                    "type": "number"
                }
            },
            "required": [
                "value"
            ],
            "type": "object"
        },
        "lexicon": {
            "properties": {
                "additional": {
                    "properties": {
                        "lexicon_expressions": {
                            "items": {
                                "$ref": "#/definitions/lexicon_expression"
                            },
                            "type": "array"
                        }
                    },
                    "type": [
                        "object",
                        "null"
                    ]
                },
                "type": {
                    "enum": [
                        "lexicon"
                    ]
                }
            },
            "required": [
                "name"
            ],
            "type": "object"
        },
        "lexicon_condition": {
            "properties": {
                "field": {
                    "$ref": "#/definitions/field"
                },
                "type": {
                    "enum": [
                        "lexicon"
                    ]
                },
                "value": {
                    "multipleOf": 1,
                    "type": "number"
                }
            },
            "required": [
                "field",
                "value"
            ],
            "type": "object"
        },
        "lexicon_expression": {
            "properties": {
                "additional": {
                    "properties": {
                        "expression": {
                            "minLength": 1,
                            "type": "string"
                        },
                        "lexicon_id": {
                            "multipleOf": 1,
                            "type": "number"
                        },
                        "type": {
                            "enum": [
                                "regex",
                                "text"
                            ]
                        }
                    },
                    "required": [
                        "lexicon_id",
                        "type",
                        "expression"
                    ],
                    "type": [
                        "object",
                        "null"
                    ]
                },
                "type": {
                    "enum": [
                        "lexicon_expression"
                    ]
                }
            },
            "type": "object"
        },
        "not_condition": {
            "properties": {
                "condition": {
                    "$ref": "#/definitions/condition"
                },
                "type": {
                    "enum": [
                        "not"
                    ]
                }
            },
            "type": "object"
        },
        "number_condition": {
            "properties": {
                "field": {
                    "$ref": "#/definitions/field"
                },
                "operator": {
                    "enum": [
                        "gt",
                        "lt",
                        "eq"
                    ]
                },
                "type": {
                    "enum": [
                        "number"
                    ]
                },
                "value": {
                    "multipleOf": 1,
                    "type": "number"
                }
            },
            "required": [
                "field",
                "value",
                "operator"
            ],
            "type": "object"
        },
        "regex_condition": {
            "properties": {
                "field": {
                    "$ref": "#/definitions/field"
                },
                "language": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "type": {
                    "enum": [
                        "regex"
                    ]
                },
                "value": {
                    "minLength": 1,
                    "type": "string"
                }
            },
            "required": [
                "field",
                "value"
            ],
            "type": "object"
        },
        "string_condition": {
            "properties": {
                "field": {
                    "$ref": "#/definitions/field"
                },
                "operator": {
                    "enum": [
                        "is",
                        "starts_with",
                        "ends_with"
                    ]
                },
                "type": {
                    "enum": [
                        "string"
                    ]
                },
                "value": {
                    "type": "string"
                }
            },
            "required": [
                "field",
                "value",
                "operator"
            ],
            "type": "object"
        },
        "text_condition": {
            "properties": {
                "field": {
                    "$ref": "#/definitions/field"
                },
                "language": {
                    "type": "string"
                },
                "type": {
                    "enum": [
                        "text"
                    ]
                },
                "value": {
                    "type": "string"
                }
            },
            "required": [
                "field",
                "value"
            ],
            "type": "object"
        }
    },
    "properties": {
        "results": {
            "items": {
                "oneOf": [
                    {
                        "$ref": "#/definitions/collection_sequence"
                    },
                    {
                        "$ref": "#/definitions/collection"
                    },
                    {
                        "$ref": "#/definitions/condition"
                    },
                    {
                        "$ref": "#/definitions/lexicon"
                    },
                    {
                        "$ref": "#/definitions/lexicon_expression"
                    },
                    {
                        "$ref": "#/definitions/field_source"
                    }
                ],
                "properties": {
                    "additional": {
                        "type": [
                            "object",
                            "null"
                        ]
                    },
                    "id": {
                        "multipleOf": 1,
                        "type": "number"
                    },
                    "name": {
                        "minLength": 1,
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "type": {
                        "enum": [
                            "collection_sequence",
                            "collection",
                            "condition",
                            "lexicon",
                            "lexicon_expression"
                        ]
                    }
                },
                "required": [
                    "id",
                    "type"
                ],
                "type": "object"
            },
            "type": "array"
        },
        "totalhits": {
            "multipleOf": 1,
            "type": "number"
        }
    },
    "required": [
        "results"
    ],
    "type": "object"
}


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.