Skip to content

Toro Cloud Dev Center


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)
type Type The name of the application you want the document to be associated with. By default, when a service is invoked by a Martini endpoint, the document type is the type of that Martini 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 system, user, or address that triggered the call. This can be the IP address where the HTTP inbound request came from or which Martini endpoint invoked the service. toro_tracker_document sender_id VARCHAR(255)
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 Martini 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 Martini user, if known. toro_tracker_document user_name VARCHAR(150)
timestamp long The time the document was created in Tracker. toro_tracker_document time_received TIMESTAMP
logs Collection<Log> Log messages that should be associated with the document. toro_tracker_document_log
properties Collection<Property> Key-value pairs that define additional or custom properties associated to a document. toro_tracker_document_property
states Collection<State> A list of states the document was in throughout the service invocation. toro_tracker_document_state
children Collection<String> Parent-child relationship listings wherein the document of interest is the child. toro_tracker_document_relationship
parents Collection<String> Parent-child relationship listings wherein the document of interest is the parent.

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 Martini tries its best to automatically populate document fields with default values, they can still be overridden so that it conforms to your organization's preference.

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 document type 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 Type objects and contain the following fields:

Field Name Java Data Type Description SQL Table SQL Column SQL Data Type
id String The identifier for the document type. toro_tracker_document_type doc_type_id VARCHAR(100)
name String The name of the document type. toro_tracker_document_type doc_type_name VARCHAR(100)

It is possible to create, edit, and delete custom document types in Martini:

Adding a new document type

Adding a new document type

Adding a new document type

Log messages

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

Field Name Java Data Type Description SQL Table SQL Column SQL Data Type
id Long The identifier for the log message. toro_tracker_document_log document_log_id INT(10)
timeReceived long The time at which the message was logged. toro_tracker_document_log time_received TIMESTAMP
type String The type of log message. toro_tracker_document_log log_type VARCHAR(10)
message 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
key String The name of the property. toro_tracker_document_property property_key VARCHAR(30)
value 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 service invocation. States are so called because they let us know the different states the service invocation transitioned through whilst Martini 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 State objects. This type is comprised of the following fields:

Field Name Data Type Description SQL SQL Column SQL Data Type
id Long The auto-generated, unique number used to identify document states. toro_tracker_document_state document_state_id INT(10)
name String The name of the state; does not have to be unique. toro_tracker_document_state time_received TIMESTAMP
timeReceived long The time at which this state was achieved. toro_tracker_document_state state_name VARCHAR(50)
canBeResubmitted boolean
contentFileName String
contentSize long
indexed boolean

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 Martini. For service invocations triggered by HTTP, this is the HTTP request and HTTP response1 bodies by default2. For services triggered by Martini 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 application developers. 

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