Developing Custom Integrations
In addition to our collection of pre-configured integrations, JupiterOne provides the ability to develop and utilize custom integrations within your JupiterOne workspace.
Depending on your work environment and the nature of your integration, you can additionally create and run custom integrations from your own environment. This is useful for on premise applications such as Jira or GitHub Enterprise.
Custom integrations allow you to add bespoke data to the JupiterOne platform and are perfect for:
- Integrating with a provider that does not have an integration with JupiterOne
- Integrations that need access to local systems or data
- Executing integrations in your own environment
Custom integrations can be created with the help of the open source SDK. For more information on creating integrations see the SDK README and the integration-template repository.
Create a custom integration
Creating and running a custom integration requires you to both create the integration instance within your JupiterOne workspace, and set up a local integration in your environment to communicate with JupiterOne.
In your JupiterOne workspace
Similarly to our adding a managed integration, you can configure your custom integration within the JupiterOne workspace:
- On the Integrations page in the JupiterOne app, click the "Custom" integration tile.
- Provide an Account Name, Description, and any Tags, then click Create.
- At the bottom of the page, click New API Key.
- Copy both the
API keyand instance
idto be used later.
In your environment
In the directory where your custom integration is set up, create a
.env file. Add the following to your
.env file from information:
JUPITERONE_ACCOUNTID can found by going to the Settings Icon > Account Management > Account Id.
JUPITERONE_API_KEYcomes from the API Key you generated earlier for the custom integration.
Then add any other configuration fields your integration needs to run or authenticate.
Executing the integration
To execute a custom integration, run the following command. You can find the
integrationInstanceId from the top of the instance details page where you
generated the API key.
yarn j1-integration run -V --integrationInstanceId c6200b3a-df93-4a61-8ac3-079c96713058
This will start a new integration job, collect data, and upload it to the JupiterOne platform to be synchronized. It's recommended to use the
-V flag when running jobs to disable entity schema validation.
Integration job information will be available in the UI just like a managed integration.
Seeing the results
After your integration has completed and synchronization has finalized you can view the data your integration uploaded with the following J1QL Query. Just replace the id with the id of your custom instance.
FIND * with _integrationInstanceId = "c6200b3a-df93-4a61-8ac3-079c96713058"
For more information on creating a custom integration, proceed to our in-depth guide on integration development.