Integrations operations

Scheduling Integration Jobs

Use the pollingIntervalCronExpression to set an hour or dayOfWeek value for an integration configuration to run.

Set the Hour

When using the ONE_DAY polling interval, you can pass an optional pollingIntervalCronExpression to specify a time of day for the integration to execute.

The following configuration sets an integration to execute daily between 00:00 and 01:00 UTC.

{
  "pollingInterval": "ONE_DAY",
  "pollingIntervalCronExpression": { "hour": 0 }
}

pollingIntervalCronExpression.hour accepts an integer between 0 and 23.

Set the Day of the Week

When using the ONE_WEEK polling interval, you can pass an optional pollingIntervalCronExpression to specify both a dayOfWeek and hour for the integration to execute.

The following configuration sets an integration to execute weekly on Sunday between 00:00 and 01:00 UTC.

{
  "pollingInterval": "ONE_WEEK",
  "pollingIntervalCronExpression": { "hour": 0, "dayOfWeek": 0 }
}

pollingIntervalCronExpression.dayOfWeek accepts an integer between 0 (Sunday) and 6 (Saturday).

Example Mutation

This is an example of a GraphQL mutation that updates the hour and day of the week for a specific configuration of an integration in JupiterOne:

mutation integrationInstance(
  $id: String!
  $pollingIntervalCronExpression: IntegrationPollingIntervalCronExpressionInput
) {
  updateIntegrationInstance(
    id: $id
    update: { pollingIntervalCronExpression: $pollingIntervalCronExpression }
  ) {
    id
    name
    pollingInterval
    pollingIntervalCronExpression {
      hour
      dayOfWeek
    }
  }
}

Variables for the mutation:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "pollingIntervalCronExpression": {
    "hour": 0,
    "dayOfWeek": 0
  }
}

Variables:

id: the id of the configuration for which you want to update the hour and/or day of week. This ID is visible in each integration configuration in your account. To find the ID in your JupiterOne account, go to Settings > Integration > {integration name} > {configuration name} > value in the ID field.

hour: an integer between 0 and 23 that represents the hour of the day in UTC when you want the integration to run.

dayofWeek: an integer between 0 and 6 that represents the day of the week Sunday through Saturday on which you want the integration to run.

Example Query

This is an example of a GraphQL query that returns the current values in the hour and dayOfWeek parameters for a specific integration configuration:

query integrationInstance($id: String!) {
  integrationInstance(id: $id) {
    id
    name
    pollingInterval
    pollingIntervalCronExpression {
      hour
      dayOfWeek
    }
  }
}

Variable for the query:

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Variables:

id: the id of the configuration for which you want to update the hour and/or day of week. This ID is visible in each integration configuration in your account. To find the ID in your JupiterOne account go to Settings > Integration > {integration name} > {configuration name} > value in the ID field.

Finding an Integration Definition Based on a Type

This query returns an Integration Definition. This query requires an Integration Type.

query testQuery($integrationType: String!) {
  findIntegrationDefinition(integrationType: $integrationType) {
    id
    name
    type
    title
    integrationType
    integrationClass
    configFields {
      key
      displayName
      description
    }
  }
}

Getting an Integration Definition with an ID

This query returns a Integration Definition. This query requires an ID.

query getIntegrationDefinition($id: String) {
  integrationDefinition(id: $id) {
    id
    name
    type
    title
  }
}

List Integration Definitions

This query returns a list of all Integration Definitions.

query testQuery {
  integrationDefinitions {
    definitions {
      id
      name
      type
      title
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

List Integration Jobs

This query returns a list of Integration Jobs for a given Integration Instance.

query testQuery (
  $integrationInstanceId: String!
  $cursor: String
  $size: Int
) {
  integrationJobs(
    integrationInstanceId: $integrationInstanceId
    cursor: $cursor
    size: $size
  ) {
    jobs {
      id
      createDate
      integrationInstanceId
      status
      errorsOccurred
      endDate
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Integration Job Health

The status and errorsOccurred properties indicate the result of the job.

job.status

Status	Definition
IN_PROGRESS	The job is currently ingesting and processing the data retrieved from the source.
COMPLETED	The job completed ingestion and processing without any known errors.
COMPLETED_WITH_WARNINGS	The job completed ingestion and processing with missing data due to ingestion limits or missing provider permissions.
COMPLETED_WITH_ERRORS	The job completed ingestion and processing with unexpected errors. The successfully collected data will be available in JupiterOne.
FAILED	The job failed to ingest and/or process the data. No changes were made to the data within JupiterOne.

job.errorsOccurred

During the execution of a job, if an error level job event is logged, the errorsOccurred boolean is set to true. A job with status FAILED or COMPLETED_WITH_ERRORS will always have errorsOccurred set to true.

Trigger an Integration Job via API

The following values are required in order to trigger an integration job via API: API_KEY - An API Key must be configured before leveraging the JupiterOne API. Review Enable API Key Access for a guide in creating a JupiterOne API Key.

ACCOUNT_ID - This value is the unique ID of your JupiterOne Account, found in Settings under Account Management.

INTEGRATION_INSTANCE_ID - This value is the ID of the specific integration instance that will be triggered, found in Settings under Integrations and then selecting the specific integration that has been configured (Integrations - Configurations - Settings).

Sample request:

Endpoint:

POST https://graphql.us.jupiterone.io

Headers:

{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "JupiterOne-Account": "{Account_ID}",
  "Authorization": "Bearer {API_Key}"
}

Body:

{
  "query": "mutation Invoke {
    invokeIntegrationInstance(id: INTEGRATION_INSTANCE_ID) {
      success
    }
  }"
}

Retrieve JupiterOne Audit Events via API

User events in your JupiterOne account are logged and can be accessed via API.

Sample request:

Endpoint:

POST https://graphql.us.jupiterone.io

Headers:

{
  "Content-Type": "application/json",
  "JupiterOne-Account": "{Account_ID}",
  "Authorization": "Bearer {API_Key}"
}

Body:

{
  "query": "Query($limit: Int, $cursor: String) {
    getAuditEventsForAccount(limit: $limit, cursor: $cursor) {
      items {
        id
        resourceType
        resourceId
        category
        timestamp
        performedByUserId
        data
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }"
}

Scheduling Integration Jobs​

Set the Hour​

Set the Day of the Week​

Example Mutation​

Example Query​

Finding an Integration Definition Based on a Type​

Getting an Integration Definition with an ID​

List Integration Definitions​

List Integration Jobs​

Integration Job Health​

job.status​

job.errorsOccurred​

Trigger an Integration Job via API​

Retrieve JupiterOne Audit Events via API​

Contents