Learn about the data ingested, benefits of this integration, and how to use it with JupiterOne in the integration documentation.
Install dependencies with
Register an account in the system this integration targets for ingestion and obtain API credentials.
cp .env.example .envand add necessary values for runtime configuration.
When an integration executes, it needs API credentials and any other configuration parameters necessary for its work (provider API credentials, data ingestion parameters, etc.). The names of these parameters are defined by the
src/config.ts. When the integration is executed outside the JupiterOne managed environment (local development or on-prem), values for these parameters are read from Node's
process.envby converting config field names to constant case. For example,
clientIdis read from
.envfile is loaded into
process.envbefore the integration code is executed. This file is not required should you configure the environment another way.
.gitignoreis configured to to avoid commiting the
Running the integration
yarn startto collect data
yarn graphto show a visualization of the collected data
yarn j1-integration -hfor additional commands
Start by taking a look at the source code. The integration is basically a set of functions called steps, each of which ingests a collection of resources and relationships. The goal is to limit each step to as few resource types as possible so that should the ingestion of one type of data fail, it does not necessarily prevent the ingestion of other, unrelated data. That should be enough information to allow you to get started coding!
See the SDK development documentation for a deep dive into the mechanics of how integrations work.
See docs/development.md for any additional details about developing this integration.
Testing the integation
Ideally, all major calls to the API and converter functions would be tested. You
can run the tests with
yarn test, and you can run the tests as they execute in
the CI/CD environment with
yarn test:ci (adds linting and type-checking to
yarn test). If you have a valid runtime configuration, you can run the tests
with your credentials using
For more details on setting up tests, and specifically on using recordings to
simulate API responses, see
The history of this integration's development can be viewed at CHANGELOG.md.
Versioning this project
To version this project and tag the repo with a new version number, run the
major.minor.patch is the version you expect to move to):
git checkout -b release-<major>.<minor>.<patch> vim CHANGELOG.md # remember to update CHANGELOG.md with version & date! git add CHANGELOG.md yarn version <major>.<minor>.<patch> git push --follow-tags -u origin release-<major>.<minor>.<patch>
NOTE: It is critical that the tagged commit is the last commit before merging to main. If any commit is added after the tagged commit, the project will not be published to NPM.
NOTE: Make sure you select the Create a merge commit option when merging the PR for your release branch. Otherwise the publishing workflow will error out.
TIP: We recommend updating your global
~/.gitconfig with the
push.followTags = true property. This will automatically add the
--follow-tags flag to any new commits. See
[push] followTags = true
After the PR is merged to the main branch, the Build github workflow should run the Publish step to publish this project to NPM.