Skip to content

Home

Introduction

Development

IDEs

Services

Service manager

API Explorer

Tracker document

We refer to entries in the index as documents. Documents have a particular set of fields. In the Tracker search index, documents are configured to have the following fields:

Field name Java data type Description SQL Table SQL Column SQL Data Type
internalId String A unique string used to tell documents apart. This is assigned by Tracker and is used to retrieve the document in future sessions, such as when you would like to update it by adding a new state to it. toro_tracker_document internal_id VARCHAR(40)
externalId String A unique string used to identify service invocations apart. A service call made during a certain date at 02:43 PM is different from the call made during 11:45 PM. This ID is assignable by users although by default, this is the current Unix time at which the service was called. toro_tracker_document external_id VARCHAR(40)
documentType DocumentType The name of the integration you want the document to be associated with. By default, when a service is invoked by an Integrate endpoint, the document type is the type of that Integrate endpoint; services invoked via HTTP will have a document type after the name of leading path the call was directed at. toro_tracker_document doc_type_id VARCHAR(100)
stateName String The name of the last recorded state of the integration call. This should indicate the progress of the invocation; for example, from Received -> Processing -> Processed or Error. toro_tracker_document state_name VARCHAR(40)
senderId String The name of the system, user, or address that triggered the call. This can be the IP address where the HTTP inbound request came from or which Integrate endpoint invoked the service. toro_tracker_document sender_id VARCHAR(255)
receiverId String The name of the system, user, or address that is the eventual recipient of the invocation. If the invocation is triggered by an endpoint, then that endpoint's service is marked as the receiver. For HTTP endpoints, this is their relative request URL mapping. toro_tracker_document receiver_id VARCHAR(255)
userName String The user who initiated the call. This can be set to "Anonymous" if the caller is anonymous, or the name of a Marketplace user or Integrate user, if known. toro_tracker_document user_name VARCHAR(150)
timeReceived Timestamp The time the document was created in Tracker. toro_tracker_document time_received TIMESTAMP
logMessages Set<DocumentLog> Log messages that should be associated with the document. toro_tracker_document_log
properties Set<DocumentProperty> Key-value pairs that define additional or custom properties associated to a document. toro_tracker_document_property
states Set<DocumentState> A list of states the document was in throughout the integration. toro_tracker_document_state
childDocuments Set<DocumentRelationship> Parent-child relationship listings wherein the document of interest is the child. toro_tracker_document_relationship
parentDocuments Set<DocumentRelationship> Parent-child relationship listings wherein the document of interest is the parent. toro_tracker_document_relationship

Tracker documents are represented internally by Document objects. This is the same type you'll have to work with if you plan to fetch or set Tracker document properties in your code (e.g. adding your own log messages, properties, or states), in which you'll use the aforementioned class's getter and setter methods.

Customizable field values

Whilst TORO Integrate tries its best to automatically populate document fields, most, if not all, of the values it has set can still be overridden so that it conforms to your organization's preference and most importantly, when doing so, it is important to relay or document those changes.

Document types

A document type serves as a 'tag' for services, making it easier for you to organize and search for service invocations. If no document type is assigned, Tracker automatically creates one for you and uses that newly created tag when creating the Tracker document for the service that was invoked. The default document type differs depending on the type of service invocation that was done.

  • For endpoints, the default document type is the type of endpoint.
  • For Groovy-based Spring web services, Gloop API endpoints, and ad hoc Gloop service endpoints, the default document type is the leading path of the URL that was used to invoke the service.

Document types are represented by DocumentType objects and contain the following fields:

Field Name Java Data Type Description SQL Table SQL Column SQL Data Type
docTypeId String The identifier for the document type. toro_tracker_document_type doc_type_id VARCHAR(100)
docTypeName String The name of the document type. toro_tracker_document_type doc_type_name VARCHAR(100)
document Set<Document> The list of documents that use this document type. toro_tracker_document

It is possible to create, edit, and delete custom document types via Coder:

Adding a new document type

Adding a new document type

Adding a new document type

Log messages

Log messages are represented by DocumentLog objects, which are composed of the following fields:

Field Name Java Data Type Description SQL Table SQL Column SQL Data Type
documentLogId Integer The identifier for the log message. toro_tracker_document_log document_log_id INT(10)
document Document The document which this log message belongs to. toro_tracker_document_log internal_id VARCHAR(40), FK
timeReceived Timestamp The time at which the message was logged. toro_tracker_document_log time_received TIMESTAMP
logType String The type of log message. toro_tracker_document_log log_type VARCHAR(10)
logMessage String The content of the log message itself. toro_tracker_document_log log_message VARCHAR(1024)

Ideally, document log messages should tell us about the service invocation's condition during certain time frames.

Properties

Key-value pairs that define additional or custom properties associated to a document.

Field Name Data Type Description SQL Table SQL Column SQL Data Type
document Document The document which this property belongs to. toro_tracker_document_property internal_id VARCHAR(40), FK
propertyKey String The name of the property. toro_tracker_document_property property_key VARCHAR(30)
propertyValue String The value of the property. toro_tracker_document_property property_value VARCHAR(100)

States

A list of states the document was in throughout the integration. States are so called because they let us know the different, transitioning states of the document (or the service invocation, rather) whilst TORO Integrate was processing it. With states, the data present at certain points of the process (of invoking the service) is made known to us, like when it encounters an error, is starting the invocation, or has successfully completed the task.

States are represented internally by DocumentState objects. This type is comprised of the following fields:

Field Name Data Type Description SQL Table SQL Column SQL Data Type
documentStateId Integer The auto-generated, unique number used to identify document states. toro_tracker_document_state document_state_id INT(10)
document Document The document which owns this state. toro_tracker_document_state internal_id VARCHAR(40)
stateName String The name of the state; does not have to be unique. toro_tracker_document_state time_received TIMESTAMP
timeReceived Timestamp The time at which this state was achieved. toro_tracker_document_state state_name VARCHAR(50)
documentSize Long The size of the state's content. toro_tracker_document_state document_size BIGINT
content DocumentStateContent The payload brought by the state. toro_tracker_doc_stcontent

Document states are an important feature of Tracker. Document state records allow you to store binary and textual data within a document. This means you can save JSON or XML data, spreadsheets, or even PDF and word processor files. What's more, the data is all indexed in a search engine. This means that you can literally do a search within the Tracker search index and see which services are being used, as well as search for the data that's going into them.

Tracker uses Apache Tika to extract data from binary files, which Tracker then indexes to make such data queryable. Tracker will be able to index the data as long as its format is supported by Tika.

A document state's content typically comes in the form of message bodies. A message body is the payload of the message received and sent by TORO Integrate. For service invocations triggered by HTTP, this is the HTTP request and HTTP response1 bodies, by default2. For services triggered by Integrate endpoints, state contents will vary by type. For example, with email endpoints, the starting state can be the files attached in the received email or the body of the email, itself, whilst the final state may contain the endpoint's reply to the email.


  1. Before enabling request and/or response data logging, there are privacy and security concerns that should be addressed by the integration developers. 

  2. It's possible to add your own states to a document, but TORO Integrate, by default, puts states of its own from the data received and sent by the endpoint.