The contextual engine is the center of ContextHub, adding dynamic capabilities to events generated by your apps through context rules. Context rules are written in JavaScript, and are triggered by events. When you create a rule (also called ‘Context’), you specify an event type. As events are coming in, if their event type matches a rule, it will be executed. Note that it is entirely possible to have more than one rule associated with a certain event type. In this case, multiple rules will execute in parallel.
To make Context Rules more useful, ContextHub provides a number of pre-existing objects that you can interact with when one of your context rules executes:
Details about each object are presented below:
The console object allows you to log activity inside your context rule.
| Method | Description |
|---|---|
| log | Logs a message to the ‘logs’ area in the Developer Portal. |
Logs the message to the console. You can see the logs from the Logs screen in the developer portal.
console.log(message)
| Parameter | Description |
|---|---|
| message | Required. Message to log to the console. |
Nothing.
The event object contains the data from the event that triggered the execution of the context rule. The event object is read-only and contains the following properties:
| Property | Description |
|---|---|
| name | The name of the event. This matches the event type of the context rule. |
| data | The data object contains all the properties relevant to this event type. See below for specific structures. |
| id | A unique identifier for this event. |
| created_at | An ISO8601 timestamp of when the event was received by the server. |
Trigger events are events generated by posting an event through a trigger endpoint for web browsers, servers, JavaScript scripts, and IoT-like devices like the Raspberry Pi or Arduino. All events have a name key, which is the ‘event type’ portion of the trigger URL endpoint that matches the rule and allows it to execute, and a data key that contains the custom data structure passed in the body of the POST request.
Below is a sample of a data structure of a custom event, taken from the [Awareness](/samples/ios/awareness) context rule sample app.
The tick event is a special event that is automatically executed once every minute in the ContextHub server. Using the JavaScript Date() object and checking the time, this allows you the ability to execute commands in ContextHub even with the absence of any events on the server. So instead of your server code simply being reactive to devices, it can be a proactive part of your applications.
Here is the structure of a sample event:
The http object allows you to send http requests to external services in a context rule. This allows you to send data to external servers when interesting events occur inside ContextHub. You will see the status of your request in your logs, but you will not be able to do anything with the response.
| Method | Description |
|---|---|
| get | Makes a http GET request to the specified url. |
| post | Makes a http POST request to the specified url. |
Allows you to perform an http GET request to a specific URL. You can specify optional query parameters and headers with the params, and headers parameters. These need to be in the form of JSON strings.
http.get(url, params, headers)
| Parameter | Description |
|---|---|
| url | Required. The url you are making the request to. |
| params | Optional. Stringified JSON of any query parameters that you want to include. |
| headers | Optional. Stringified JSON of any request headers that you want to include. |
Nothing.
Allows you to perform an http POST request to a specific URL. You can specify optional headers with the headers parameter. This needs to be in the form of a JSON string.
http.post(url, body, headers)
| Parameter | Description |
|---|---|
| url | Required. The url you are making the request to. |
| body | Optional. The body of the post request. |
| headers | Optional. Stringified JSON of any request headers that you want to include. |
Nothing.
The vault object provides access to the vault document store.
| Method | Description |
|---|---|
| create | Adds a new document to the vault. |
| find | Retreives a document from the vault via id. |
| allTagged | Finds vault objects matching all of the given tags |
| anyTagged | Finds vault objects matching any of the given tags |
| search | Finds vault objects containing the given term. |
| keyPath | Finds vault objects with the given key path. |
| update | Updates an existing vault object with new information |
| destroy | Deletes a vault object from the system |
Stores the given json data in the vault with the given tags.
vault.create(data, tags)
| Parameter | Description |
|---|---|
| data | Required. Stringified JSON of the data you want to store in the vault. |
| tags | Required. A comma separated string of tags to associate with the vault object. If you don’t want to tag the vault object, you can pass in null or “”. |
The id of the newly created vault object.
Retreives a document from the vault via id.
vault.find(id)
| Parameter | Description |
|---|---|
| id | Required. The id of the vault object to find. |
A vault object.
| Property | Description |
|---|---|
| data | Your data is stored under the data propery. |
| vault_info | Object containing metadata about the vault object. |
| vault_info Properties | Description |
|---|---|
| id | The vault object id. |
| tags | Array of tags assigned to the vault object. |
| created_at | Timestamp of when the object was created. |
| updated_at | Timestamp of when the object was last updated. |
| tag_string | Tags as a comma separated string |
Finds vault objects that contain all the specified tags.
vault.allTagged(tags)
| Parameter | Description |
|---|---|
| tags | Required. A string containing the tag(s) to search for. Multiple tags can be searched for by separating them with commas. Results will contain vault objects that match all the specified tags. |
An array of vault objects.
Finds vault objects that contain any of the specified tags.
vault.anyTagged(tags)
| Parameter | Description |
|---|---|
| tags | Required. A string containing the tag(s) to search for. Multiple tags can be searched for by separating them with commas. Results will contain vault objects that match any the specified tags. |
An array of vault objects.
Finds all vault objects that contain the given term. You can use the following search operators in your queries to fine tune your results. You can use parentheses to set operator precedence.
| Operator | Example |
|---|---|
| Not | !term |
| And | term1 & term2 |
| Or | term1 | term2 |
vault.search(term)
| Parameter | Description |
|---|---|
| term | Required. A string containing the term to search for. Any documents containing the term will be returned. |
An array of vault objects.
Finds all vault objects that have the specified key path. If a value is provided, then documents that have the value at the key path will be returned.
vault.keyPath(key, value)
| Parameter | Description |
|---|---|
| key | Required. A string containing the key to search for. Use dot notation ‘address.city’ for specifying a nested key. |
| value | Optional. If provided documents that match the value at the key will be returned. Otherwise, all documents that contain the key will be returned. |
An array of vault objects.
Replaces the vault object at the given id with the given data.
vault.update(id, data, tags = nil)
| Parameter | Description |
|---|---|
| id | Required. The id of the vault object to update. |
| data | Required. Stringified JSON of the data you want to store in the vault. |
| tags | Optional. A comma separated string of tags to associate with the vault object. If you don’t want to update the tags, you can omit this parameter. |
Nothing.
Deleting a vault items only requires passing the id to the vault object. The vault item is deleted from ContextHub.
vault.destroy(id)
| Parameter | Description |
|---|---|
| id | Required. The id of the vault object to delete. |
Nothing.