Product
Introducing SSO
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
xmtoolbox
Advanced tools
A Node JS package for interacting with xMatters. Contains functions to interact with xMatters APIs or perform a synchronization, create events, libraries to convert data, and much much more!
Readme
The xmtoolbox is a easy to use, zero dependency, promise based node package to simplify the interaction with xMatters using the xMatters REST APIs. It wraps all documented APIs and adds simple backup, restore, and sync functionality.
All Issues and Questions: https://github.com/xmatters/xmtoolbox/issues
Working examples: https://github.com/xmatters/xmtoolbox-quick-start
xmtoolbox documentation: https://xmatters.github.io/xmtoolbox/
xmtoolbox node package: https://www.npmjs.com/package/xmtoolbox
If you are new to node.js see the Getting Started section.
npm install xmtoolbox --save
The following instructions get you started without an existing node.js project and will get all groups from xMatters. See the examples in xmtoolbox-quick-start for more examples.
Install Node from https://nodejs.org. Install the latest Long Term Support(LTS) release.
In terminal/command prompt, create new node project using the command npm init
and follow prompts. The defaults are sufficient for getting started.
In terminal/command prompt, install xmtoolbox using the command npm install xmtoolbox --save
.
Create a user in xMatters or add an an API key to an existing one. The user must have the role Web Service User Role
. See the user and password sections for more information.
Create a new file in this directory called example.js
and place the contents below in that file. Replace the placeholders for subdomain, username, and password with your details.
const xm = require('../xmtoolbox');
const np = xm.environments.create('subdomain', 'username', 'password');
main();
async function main() {
const groups = await xm.groups.getMany(np);
console.log(JSON.stringify(groups, null, 2));
}
In terminal/command prompt, run the example.js using the command node example.js
The xMatters subdomain is needed so that xmtoolbox know which xMatters environment it is interacting with. If your xMatters url is https://company.xmatters.com, your subdomain is company.
The xmtoolbox needs an xMatters user to make api requests using the xMatters API. The user must have the 'Web Services User Role' role. When creating an xmtoolbox environment you may specific the user as the actual user's username or an API Key created with that user.
To support a variety of deployments and situations, xmtoolbox supports many methods of specifying the password or API key that is used to authenticate the user. The password may be the xMatters user password, api key secret, or an xmtoolbox encryption key if the .xmpw file has been defined. The password can also be undefined
if the encryption key is specified in the environment variable specified when creating the .xmpw file. To encrypt the password and create a .xmpw file, see Encrypted Password If this encryption method is not desirable you may implement any encryption or security mechanism desirable as long as the string form of the password or API key is supplied when creating the xmtoolbox environment.
A xmtoolbox .xmpw file is an aes-256-gcm encrypted file that contains your xMatters password or API Key secret for each xMatters instance. A 32 character key is used to encrypt the file and must be provided to xmtoolbox via the password field or environment variable that is provided after following the instructions below.
To create encrypted xmtoolbox .xmpw file to store your password in encrypted format for each xMatters instance.
npx create-xmpw
from this project directory.After following the steps above, the file is written to project directory with a name similar to the subdomain with extension .xmpw
. The key may be provided in the password field or the environment variable given in the output after following the steps above.
This package has the ability to modify data within xMatters for good and bad. Please use it responsibly. Test in non-production and don't make unnecessary requests against your xMatters instance. Also, be aware that according to xMatters, the inbound events and flow posts share the same bandwidth any interactions with the xMatters APIs, including the ones this package uses, so again please use responsibly.
Full working examples are available in the xmtoolbox-quick-start template.
To improve readability, xm
is a reference to this package. np
and prod
in the below examples are environments that are assumed to exist as demonstrated in getting started. Only the np
(non-production) is included in the setup as an example but depending on your goals you may need to operate with two or more xMatters instances and will need to create them as needed.
const person = await xm.people.get(np, 'amunster', { embed: 'devices' });
console.log(person.firstName); //Arnold
// matches weblogin and email for @example.com
const query = { embed: 'roles,devices', search: '@example.com' };
const people = await xm.people.getMany(np, query);
const syncOptions = {
people: true,
peopleFilter: p => p.targetName.startsWith('U001'), //Optional
devices: true,
groups: true,
shifts: true
};
(async () => {
await xm.sync.xMattersToxMatters(prod, np, syncOptions);
})();
const extractOptions = {
people: true,
devices: true
//groups: true, // include groups
//shifts: true // and shifts too!
}
const path = `./data/${np.subdomain}.people.json`;
(async () => {
const data = await xm.sync.ExtractData(np, extractOptions);
require('fs').writeFileSync(path, JSON.stringify(data, null, 2));
})();
const syncOptions = {
people: true,
devices: true,
//groups: true, // include groups
//shifts: true // and shifts too!
};
const path = `./data/${np.subdomain}.people.json`;
(async () => {
const text = require('fs').readFileSync(path, 'utf8');
await xm.sync.DataToxMatters(JSON.parse(text), np, syncOptions);
})();
This lists below refer to xMatters objects as defined in the xMatters REST API documentation.
Object as defined by xMatters (caveats)
xmtoobox is supported on many version of Node.js however the latest Long Term Support(LTS) version of node.js is recommended.
xmtoolbox is supported on Linux, macOS, and Windows operating systems.
FAQs
A Node JS package for interacting with xMatters. Contains functions to interact with xMatters APIs or perform a synchronization, create events, libraries to convert data, and much much more!
The npm package xmtoolbox receives a total of 68 weekly downloads. As such, xmtoolbox popularity was classified as not popular.
We found that xmtoolbox demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.