Developer Hub

Welcome to the EVRYTHNG Developer Hub! Here you will find all the information you need to create your EVRYTHNG apps and integrations. We have conceptual guides, walkthroughs, and tutorials as well as a complete API reference.

Featured Pages

The Reactor is one of the most flexible and powerful features of the EVRYTHNG Platform, available as part of the Enterprise API. It allows developers to write logic in JavaScript and associate them with a Platform application, which provide reactionary logic to certain types of events that occur to other types of resources, such as Thngs or actions.

These scripts are run asynchronously, including any updates that occur as a result of a script execution. This fact should be taken into account when planning and developing a Reactor-based solution. Scripts can consist of many files and include other npm modules as dependencies, allowing a virtually free-form environment.

To get a general introduction to the concepts of Reactor, read the Reactor section in the API Reference, then come back here for a practical introduction.

Note

This walkthrough assumes a basic level of knowledge about some basic EVRYTHNG Platform resources, including projects, applications, Thngs, and devices. You can find out more about all of these in the API Reference section.


Example Use Cases

Reactor is most useful in scenarios where some programmatic logic can be used to derive insights from raw data, react to discrete events specific to the use-case context, or enable deeper integrations with external APIs and services. Some general examples include:

  • Using a simple event to calculate and update more meaningful metadata on the resource itself. For example, number of times a Thng QR code has been scanned, or conditionally updating custom fields or tags.
  • Detect irregular stock movements when an action is created on a Thng that describes a stage in the supply chain. For example, an alert if the item is arriving at the wrong warehouse, or is far away from the expected region (a shipment may have been stolen).
  • Keep track of the number of items at each storage location to help predict and/or analyse potential stock out situations and optimise warehouse stock levels.
  • Perform connected device management through actions that the device can listen to and react to. Examples include remote control operations (turn on, turn off, etc), initiate firmware updates, create and send push notifications based on contextual information, and more.
  • Enabling integration to external APIs and data storage systems. This could enable discount code generation and redemption, pulling data from external sources, or notifying other systems to some EVRYTHNG-related update to drive deeper experiences.

Creating a Reactor Script

There is one Reactor script allocation available per application, expanding to many for a single project by creating multiple applications inside it. Code inside the Reactor script may be virtually any Node.js 6.10.2 compatible code, with minimal limitations. Using the included package.json file, other Node/npm modules can be required by the script, vastly enhancing the possibilities and use-cases. For example, including the request module to talk to other external services and APIs, allowing complex integrations.

Code can be uploaded to an application Reactor in two ways and two formats - through the API or in the Dashboard, as either a plain text string single file or part of a .zip bundle. Uploading a script through the API allows integration with other tools and deployment systems, while the bundle format allows more complex multi-file scripts to be uploaded.

Once new code has been submitted, the Reactor script is built and deployed to the Platform, which will take a few seconds. During this time no events will occur. The status of a Reactor script being updated is displayed in the Dashboard on the application page above the script editor.


Running a Reactor Script

An application's Reactor script is run in response to one or more types of event, with a handler function for each type of event providing the entry point where execution starts. At least one of the handlers named below must be implemented in the main script file in order for the script to run. These include:

  • onThngPropertiesChanged() - When a Thng’s properties are created or updated.
  • onProductPropertiesChanged() - When a product’s properties are created or updated.
  • onActionCreated() - When an action is created on a Thng, product, or collection.
  • onScheduledEvent() - At a specific time, or time interval. This can also be a custom function name with the correct configuration.

See the example script below for examples of each of these, as well as the relevant section of the API Reference for more information on how these are implemented.

There are two important factors that determine if a Reactor script is executed or not:

  • The resource that is triggering it must be correctly scoped to the application's project. For example, an application in a hypothetical ‘Demos’ project will only run its Reactor script if the Thng being updated or product an action is targeting is also scoped to that project.
  • The authenticating API key making the request that would trigger an event must also be in the same project scope. Such a key could be the application’s Trusted Application API Key, or an Application User API Key belonging to the same application.

When the script has finished, it must call the built-in global done() function, to inform the Platform that it is completed. Only after this is done will any logs created with the built-in global logger object be displayed in the Dashboard and available through the API.

In cases where a large number of executions are triggered, it is strongly recommended to make use of Reactor filters to specify when the script should and should not run, based on the properties of the resource that would have triggered it to run, before it is even executed. For example, only a certain action type or property name.


Example Reactor Script

The following is a simple example Reactor script that simply logs a message to the application’s Reactor logs whenever one of the types of events occurs. This is a good starting point for most Reactor script implementations.

Each of the corresponding event type handlers are present, and unfiltered to receive all possible events. Note that done() is always called as expected to enable logs to be saved in the Platform.

// When an action is created
function onActionCreated(event) {
  logger.info(`Action created:\n${JSON.stringify(event)}`);
  done();
}

// When a Thng's properties have changed
function onThngPropertiesChanged(event) {
  logger.info(`Thng properties changed:\n${JSON.stringify(event)}`);
  done();
}

// When a product's properties have changed
function onProductPropertiesChanged(event) {
  logger.info(`Product properties changed:\n${JSON.stringify(event)}`);
  done();
}

// When a Reactor Schedule runs
function onScheduledEvent(event) {
  logger.info(`Scheduled event:\n${JSON.stringify(event)}`);
  done();
}
{
  "dependencies": {
    "evrythng-extended": "^4.1.0"
  }
}

Conclusion

Now that you have been introduced to some of the basic concepts and seen a minimal example script, read the next section for a more in-depth look at some recommended patterns to architect Reactor scripts yourself.