Automation - Matrix Requirements SDK
The Matrix Requirements SDK is a “software development kit” that allows you to write scripts in NodeJS to query and update your Matrix Instance. It is a wrapper around the REST API, which includes parameter validation and a natural object-oriented interface.
The SDK is publicly available in the matrix-sdk GitHub repository: https://github.com/MatrixRequirements/matrix-sdk.
It is also downloadable as an NPM package called matrix-requirements-sdk: https://www.npmjs.com/package/matrix-requirements-sdk.
The software is free to download and use, though you’ll need a Matrix Instance to connect to, as well as an API key to make use of the underlying REST API.
There is a User’s Guide and full reference documentation available here: https://matrixrequirements.github.io/matrix-sdk-docs/
Integration with the Web Application
The SDK also supports integration with the main web application. Points of integration include:
Dashboards
Menu items
Custom controls / field types
Server settings panes
Project settings panes
In this scenario, your code is loaded by the main web application and appears seamlessly integrated with it. Your code should be written in TypeScript or JavaScript, and makes use of the Matrix SDK. Your code is called a Plugin. To get started, we offer a “boilerplate” project on GitHub: https://github.com/MatrixRequirements/matrix-ui-plugin-boilerplate-24.
You can “clone” this project to create a basic Matrix Plugin in order to get started.
Carefully consider the scope of automation efforts
The SDK greatly increases your power to automate important scenarios. Nightly jobs could check new entries for compliance. Items could be created automatically upon certain conditions. To some extent, whatever integration you imagine becomes possible. However, it is wise to limit the number of items you create, as an “out of control” automation process could swap the database with millions of records. Here are some things to watch out for:
Be careful about any process that creates multiple Items per day (or hour) unattended. For example, you might have an automated test runner that goes through thousands of tests every day. If you use the SDK to create a new item for each run of each test, you’ll fill the database with millions of records quite soon. It is likely that your automated build system records are sufficient for such a use case.
The SDK allows you to write “glue code” which funnels data between your Matrix Instance and other systems. Remember to be careful about the security of your proprietary data when communicating with third-party services.
If you’ve got any doubts about your automation scenario, whether it’s already running or only in the planning stages, feel free to contact us. We’re always keen to improve the SDK, especially if we can be guided by what our customers are doing with it.