Scheduled Imports

Scheduled imports allow you to automate the execution of your Assets imports at regular intervals, eliminating the need for manual triggering. This feature is particularly useful for keeping your Assets data synchronized with external systems that are frequently updated.

Overview

With scheduled imports, you can:

• Automate data synchronization: Keep your Assets data up-to-date without manual intervention
• Configure flexible schedules: Run imports once, daily, weekly, or monthly
• Maintain data freshness: Ensure your Assets data reflects the latest state of your external services
• Track execution history: View all scheduled import runs with clear indicators in the import history

Supported import types

Scheduled imports are supported for the following import types:

• CSV imports: From uploaded CSV files or URLs
• JSON imports: From uploaded JSON files or URLs
• External imports: Including Forge apps and other third-party integrations
• Data Manager imports: From saved search results

How scheduled imports work

The scheduled import feature is managed by the Assets backend infrastructure using an internal scheduling service. When you create a schedule, the system:

1. Stores your schedule configuration (frequency, time, timezone)
2. Triggers the import at the specified times
3. For external imports (Forge apps), calls your app's callback URL with the necessary parameters
4. Tracks the execution in the import history with a "Scheduled" indicator

Schedule frequencies

Scheduled imports support the following cadences:

• Once: Run once at a specific date and time
• Daily: Run once per day at a specified time
• Weekly: Run on specific days of the week at a specified time
• Monthly: Run on a specific day of the month at a specified time

All times are stored and processed in UTC, but you can specify your preferred timezone when creating a schedule.

API endpoints

Base path

All scheduled import endpoints use the following base path:

1
2
/jsm/assets/workspace/{workspaceId}/v1/importsource/{importSourceId}

Create a schedule

Create a new schedule for an import source.

Endpoint: POST /importsource/{importSourceId}/importschedule

Request body:

1
2
{
  "runFrequency": "DAILY",
  "startTime": "2025-12-30T03:50:33Z",
  "timezone": "America/New_York",
  "callbackUrl": "https://your-app-callback-url.com"
}

Parameters:

• runFrequency (required): One of ONCE, DAILY, WEEKLY, MONTHLY
• startTime (required): ISO 8601 formatted datetime string in UTC
• timezone (required): IANA timezone identifier (e.g., "America/New_York", "Europe/London")
• callbackUrl (optional): Required only for external imports (Forge apps). This is the URL that will be called when the schedule triggers

Response:

1
2
{
  "id": "schedule-uuid",
  "importSourceId": "import-source-uuid",
  "runFrequency": "DAILY",
  "startTime": "2025-12-30T03:50:33Z",
  "timezone": "America/New_York",
  "isActive": true,
  "createdAt": "2025-12-30T10:00:00Z",
  "updatedAt": "2025-12-30T10:00:00Z"
}

The response includes an id field (the importScheduleId) which is required for subsequent GET, PUT, and DELETE operations.

Get schedule details

Retrieve the details of an existing schedule.

Endpoint: GET /importsource/{importSourceId}/importschedule/{importScheduleId}

Response:

1
2
{
  "id": "schedule-uuid",
  "importSourceId": "import-source-uuid",
  "runFrequency": "DAILY",
  "startTime": "2025-12-30T03:50:33Z",
  "timezone": "America/New_York",
  "isActive": true,
  "createdAt": "2025-12-30T10:00:00Z",
  "updatedAt": "2025-12-30T10:00:00Z"
}

Update a schedule

Update an existing schedule configuration.

Endpoint: PUT /importsource/{importSourceId}/importschedule/{importScheduleId}

Request body:

1
2
{
  "runFrequency": "WEEKLY",
  "startTime": "2025-12-31T08:00:00Z",
  "timezone": "Europe/London"
}

All fields that were provided during schedule creation can be updated.

Delete a schedule

Delete an existing schedule. This will stop all future scheduled executions.

Endpoint: DELETE /importsource/{importSourceId}/importschedule/{importScheduleId}

Scheduled imports for external applications

External applications (such as Forge apps) need to implement additional logic to handle scheduled import callbacks.

Prerequisites

Before setting up scheduled imports for an external application:

1. The import source must be fully configured with a valid mapping
2. The external application must expose a callback endpoint
3. The callback URL must be provided when creating the schedule

Callback workflow

When a scheduled import is triggered:

1. The Assets backend calls your application's callback URL
2. The callback receives the workspaceId and importsourceId in the request body
3. Your application must create a new import execution with "scheduled": true in the request body
4. Your application starts the import process using the standard workflow

Creating an execution for scheduled imports

When your callback is triggered, you must create a new execution and include the scheduled flag:

Endpoint: POST /jsm/assets/workspace/{workspaceId}/v1/importsource/{importsourceId}/executions

Request body:

1
2
{
  "scheduled": true
}

Handling errors during scheduled imports

If your application encounters errors during the scheduled import process, you should report these failures so they are visible to users in the import history.

Endpoint: POST /jsm/assets/workspace/{workspaceId}/v1/importsource/{importsourceId}/executions/{executionId}/history/failed

Request body:

1
2
{
  "failureReason": "Failed to fetch data from third-party API: Connection timeout"
}

Parameters:

• failureReason (required): A string describing why the import failed. Maximum length is 1024 characters.

Common scenarios to report failures:

• Validation errors when the import configuration is invalid
• Third-party API errors when fetching data fails
• Authentication failures when credentials are expired
• Data transformation errors when data cannot be properly mapped
• Rate limiting when API limits are exceeded

Example workflow for external applications

When your external application receives a callback from the Assets backend, follow these REST API calls:

Step 1: Create a new execution

1
2
POST /jsm/assets/workspace/{workspaceId}/v1/importsource/{importsourceId}/executions
Content-Type: application/json

{
  "scheduled": true
}

Response:

1
2
{
  "links": {
    "submitResults": "https://api.atlassian.com/jsm/assets/workspace/{workspaceId}/v1/importsource/{importsourceId}/executions/{executionId}/data"
  }
}

Step 2: Submit your data chunks

1
2
POST /jsm/assets/workspace/{workspaceId}/v1/importsource/{importsourceId}/executions/{executionId}/data
Content-Type: application/json

{
  "objectTypeId": "object-type-id",
  "objects": [
    {
      "externalId": "asset-1",
      "label": "Asset Name",
      "attributes": {
        "attributeKey1": ["value1"],
        "attributeKey2": ["value2"]
      }
    }
  ]
}

Step 3a: Signal completion (success)

After all data chunks have been submitted:

1
2
POST /jsm/assets/workspace/{workspaceId}/v1/importsource/{importsourceId}/executions/{executionId}/history/completed
Content-Type: application/json

Step 3b: Report failure (if errors occur)

If your application encounters errors before completion:

1
2
POST /jsm/assets/workspace/{workspaceId}/v1/importsource/{importsourceId}/executions/{executionId}/history/failed
Content-Type: application/json

{
  "failureReason": "Failed to fetch data from third-party API: Connection timeout"
}

Best practices

When implementing scheduled imports, consider the following best practices:

1. Choose appropriate frequencies: Balance data freshness needs against system load and API rate limits
2. Use meaningful error messages: When reporting failures, provide clear, actionable information to help users troubleshoot
3. Handle errors gracefully: Always wrap your import logic in try-catch blocks and report failures properly
4. Test thoroughly: Test your scheduled import implementation including error scenarios
5. Consider timezones: Allow users to specify their preferred timezone when creating schedules
6. Monitor execution history: Regularly check the import history to ensure scheduled imports are running as expected
7. Respect rate limits: Ensure your schedule frequency doesn't cause your application to exceed platform quotas or third-party API limits

Important considerations

• Execution timing: Scheduled imports have an SLA of approximately 1 minute, meaning imports may be delayed by up to 1 minute from their scheduled time
• Concurrent executions: If a scheduled import is triggered while a manual import is already running, the scheduled import will throw an error
• Import expiration: Import executions expire after 24 hours. All data chunks must be submitted within that timeframe
• Configuration requirements: The schedule can only be created after the import source has been fully configured with a valid mapping
• History tracking: Import execution history will show scheduled imports with a "Scheduled" tag to distinguish them from manual imports

Related resources

• Imports REST API workflow
• Schema and mapping configuration
• Authorization for Imports API
• Importing third-party data into Assets using Forge