# Background Jobs

## Get All Background Jobs

 - [GET /v1/jobs](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/background-jobs/backgroundjobs_getall.md): Retrieves a paginated list of background jobs for the authenticated client. This endpoint:

- Returns only active jobs (status: Pending or InProgress)
- Completed, failed, or cancelled jobs are not included in this list
- Provides job status information including progress summaries
- Supports pagination for efficient handling of large job datasets

### Job Status Information
Each job entry includes:
- JobId: Unique identifier for the batch job
- JobStatus: Current status (Pending, InProgress, Completed, CompletedWithErrors, Cancelled)
  - Pending: Job has been created and is waiting to be processed
  - InProgress: Job is currently being processed  
  - Completed: Job has completed successfully with no errors
  - CompletedWithErrors: Job has completed but some items failed during processing
  - Cancelled: Job has been cancelled and will not be processed further
- EventType: Type of status event (typically "job.status")
- Summary: Progress statistics (Total, Completed, Failed counts)

### Pagination
This endpoint uses simple numeric pagination:
- pageStart: 1-based index of the first record to return (default: 1)
- pageSize: Number of records to return (default: 100, maximum: 1000)
- Total Pages: Calculate using Math.ceil(total_size / page_size) from response metadata

### Content Negotiation
Clients must use the HTTP Accept header to indicate the desired response format:
- Set Accept: application/json for JSON responses (default)
- Set Accept: text/csv for CSV responses
If the Accept header is omitted, application/json is assumed.

### Base URL
All API requests use the versioned base URL:

    https://api.bcb.bm/v1/jobs

### Sample Request in JavaScript
            
javascript
async function getAllBackgroundJobs(pageStart = 1, pageSize = 50) {
  try {
    // Build URL with pagination parameters
    let url = 'https://api.bcb.bm/v1/jobs';
    const params = new URLSearchParams();
    
    params.append('pageStart', pageStart.toString());
    params.append('pageSize', pageSize.toString());
    
    url += '?' + params.toString();

    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(Background jobs retrieval failed: ${JSON.stringify(errorData)});
    }

    // Parse JSON response
    const result = await response.json();

    // Access pagination info
    const pagination = result.meta.pagination;
    console.log(Page: ${pagination.page_start}, Size: ${pagination.page_size}, Total: ${pagination.total_size});

    // Process background jobs
    result.data.forEach((job, index) => {
      console.log(Job ${index + 1}:);
      console.log(  Job ID: ${job.jobId});
      console.log(  Status: ${job.jobStatus});
      console.log(  Event Type: ${job.eventType});
      console.log(  Summary:);
      console.log(    Total: ${job.summary.total});
      console.log(    Completed: ${job.summary.completed});
      console.log(    Failed: ${job.summary.failed});
      console.log('---');
    });

    return result;
  } catch (error) {
    console.error('Failed to retrieve background jobs:', error.message);
    throw error;
  }
}

// Example usage:

// Get first 50 jobs
getAllBackgroundJobs(1, 50);

// Get next page
getAllBackgroundJobs(2, 50);

// Get all jobs with default pagination
getAllBackgroundJobs();

## Get Job Status

 - [GET /v1/jobs/{jobId}](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/background-jobs/backgroundjobs_get.md): Retrieves the current status and progress information for a specific background job. This endpoint:

- Returns detailed status information for the specified job
- Provides real-time progress statistics (total, completed, failed counts)
- Shows current job status (Pending, InProgress, Completed, Failed, Cancelled)
- Includes event type information for status tracking

### Job Status Information
The response includes:
- JobId: Unique identifier for the batch job
- JobStatus: Current status (Pending, InProgress, Completed, CompletedWithErrors, Cancelled)
  - Pending: Job has been created and is waiting to be processed
  - InProgress: Job is currently being processed  
  - Completed: Job has completed successfully with no errors
  - CompletedWithErrors: Job has completed but some items failed during processing
  - Cancelled: Job has been cancelled and will not be processed further
- EventType: Type of status event (typically "job.status")
- Summary: Progress statistics (Total, Completed, Failed counts)

### Callback Notifications
When a job reaches a completed state (Completed or CompletedWithErrors), the system automatically sends a callback notification to the callbackUrl provided during job creation (if specified).
This callback allows you to receive real-time notifications without polling the status endpoint.

Sample Callback Payload:
json
{
  "eventType": "job.completed",
  "jobId": "badabb89-8cdb-4d3d-aaf0-c714f487f1bc",
  "jobStatus": "Completed",
  "summary": {
    "total": 1,
    "completed": 1,
    "failed": 0
  }
}


### Message Signing
Callback notifications are signed. When your client configuration enables response signing, callbacks use the asymmetric option (RSA-PSS + SHA-256) and include Bcb-Signature, Bcb-Timestamp, Bcb-Nonce, and Bcb-Signature-Version (e.g., rsa-v1). If asymmetry is not configured, callbacks use the HMAC option with your Message Signing Secret and no Bcb-Signature-Version header. See the Message Signing guide for verification steps.

### Content Negotiation
Clients must use the HTTP Accept header to indicate the desired response format:
- Set Accept: application/json for JSON responses (default)
- Set Accept: text/csv for CSV responses
If the Accept header is omitted, application/json is assumed.

### Base URL
All API requests use the versioned base URL:

    https://api.bcb.bm/v1/jobs/{jobId}

### Sample Request in JavaScript
            
javascript
async function getJobStatus(jobId) {
  try {
    const url = https://api.bcb.bm/v1/jobs/${jobId};

    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(Job status retrieval failed: ${JSON.stringify(errorData)});
    }

    // Parse JSON response
    const jobStatus = await response.json();

    // Display job information
    console.log('Job Status:');
    console.log(  Job ID: ${jobStatus.jobId});
    console.log(  Status: ${jobStatus.jobStatus});
    console.log(  Event Type: ${jobStatus.eventType});
    console.log(  Progress Summary:);
    console.log(    Total Items: ${jobStatus.summary.total});
    console.log(    Completed: ${jobStatus.summary.completed});
    console.log(    Failed: ${jobStatus.summary.failed});
    console.log(    Progress: ${((jobStatus.summary.completed / jobStatus.summary.total) * 100).toFixed(1)}%);

    return jobStatus;
  } catch (error) {
    console.error('Failed to retrieve job status:', error.message);
    throw error;
  }
}

// Example usage:

// Get status for a specific job
getJobStatus('550e8400-e29b-41d4-a716-446655440001');

## Cancel Job

 - [DELETE /v1/jobs/{jobId}](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/background-jobs/backgroundjobs_canceljob.md): Cancels a background job and stops processing of all pending and in-progress items. This endpoint:

- Cancels the specified job if it's in a cancellable state
- Stops processing of all pending and in-progress items within the job
- Marks cancelled items with appropriate error messages
- Returns the updated job status after cancellation
- Provides immediate feedback on cancellation success

### Cancellation Rules
A job can only be cancelled if it's in one of these states:
- Pending: Job has been created but not yet started processing
- InProgress: Job is currently being processed

Jobs in these states cannot be cancelled:
- Completed: Job has already finished successfully
- CompletedWithErrors: Job has finished with some failures
- Cancelled: Job has already been cancelled

### What Happens During Cancellation
1. Job Status Update: The job status is changed to "Cancelled"
2. Item Cancellation: All pending and in-progress items are marked as "Cancelled"
3. Error Messages: Cancelled items receive the error message "Job was cancelled by user request"
4. Counter Updates: Job completion counters are recalculated from the database
5. Immediate Effect: Processing stops immediately for all affected items

### Content Negotiation
Clients must use the HTTP Accept header to indicate the desired response format:
- Set Accept: application/json for JSON responses (default)
- Set Accept: text/csv for CSV responses
If the Accept header is omitted, application/json is assumed.

### Base URL
All API requests use the versioned base URL:

    https://api.bcb.bm/v1/jobs/{jobId}
    
### Idempotency
The API supports idempotency through the optional Idempotency-Key header:
- If no idempotency key is provided, the request is processed normally (duplicates are possible)
- If a valid UUID idempotency key is provided, the system stores the key and associates it with the batch job
- If the same idempotency key is received again, the system returns the previously stored response
- Idempotency keys are user-specific - different users with the same keys don't share cached responses
- The idempotency key must be a valid UUID format (e.g., "123e4567-e89b-12d3-a456-426614174000")

### Sample Request in JavaScript
            
javascript
async function cancelJob(jobId) {
  try {
    const url = https://api.bcb.bm/v1/jobs/${jobId};

    const response = await fetch(url, {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(Job cancellation failed: ${JSON.stringify(errorData)});
    }

    // Parse JSON response
    const jobStatus = await response.json();

    // Display cancellation result
    console.log('Job Cancellation Result:');
    console.log(  Job ID: ${jobStatus.jobId});
    console.log(  Status: ${jobStatus.jobStatus});
    console.log(  Event Type: ${jobStatus.eventType});
    console.log(  Final Summary:);
    console.log(    Total Items: ${jobStatus.summary.total});
    console.log(    Completed: ${jobStatus.summary.completed});
    console.log(    Failed: ${jobStatus.summary.failed});
    console.log(    Cancelled: ${jobStatus.summary.total - jobStatus.summary.completed - jobStatus.summary.failed});

    return jobStatus;
  } catch (error) {
    console.error('Failed to cancel job:', error.message);
    throw error;
  }
}

// Example usage:

// Cancel a specific job
cancelJob('550e8400-e29b-41d4-a716-446655440001');

## Get Job Results

 - [GET /v1/jobs/{jobId}/results](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/background-jobs/backgroundjobs_getresults.md): Retrieves the detailed results for a specific background job. This endpoint:

- Returns paginated results for all items processed in the job
- Provides detailed information about each item's processing outcome
- Shows processing status, attempts, HTTP responses, and error details
- Includes original payload and result data for auditing
- Supports pagination for efficient handling of large result sets

### Job Results Information
Each result entry includes:
- Id: Internal numeric identifier for this item result
- JobId: Identifier of the parent batch job
- ExternalItemId: Client-supplied item identifier from the original batch
- PayloadJson: Original request payload serialized as JSON
- Status: Current processing status (Pending, InProgress, Completed, Failed, Cancelled)
- Attempt: Number of processing attempts made for this item
- HttpStatusCode: HTTP status code returned by the target endpoint
- ResultJson: Response payload from the target endpoint (if successful)
- ErrorMessage: Error details (if processing failed)

### Pagination
This endpoint uses simple numeric pagination:
- pageStart: 1-based index of the first record to return (default: 1)
- pageSize: Number of records to return (default: 100, maximum: 1000)
- Total Pages: Calculate using Math.ceil(total_size / page_size) from response metadata

### Content Negotiation
Clients must use the HTTP Accept header to indicate the desired response format:
- Set Accept: application/json for JSON responses (default)
- Set Accept: text/csv for CSV responses
If the Accept header is omitted, application/json is assumed.

### Base URL
All API requests use the versioned base URL:

    https://api.bcb.bm/v1/jobs/{jobId}/results

### Sample Request in JavaScript
            
javascript
async function getJobResults(jobId, pageStart = 1, pageSize = 50) {
  try {
    const url = https://api.bcb.bm/v1/jobs/${jobId}/results;
    const params = new URLSearchParams();
    
    params.append('pageStart', pageStart.toString());
    params.append('pageSize', pageSize.toString());
    
    const fullUrl = url + '?' + params.toString();

    const response = await fetch(fullUrl, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(Job results retrieval failed: ${JSON.stringify(errorData)});
    }

    // Parse JSON response
    const result = await response.json();

    // Access pagination info
    const pagination = result.meta.pagination;
    console.log(Page: ${pagination.page_start}, Size: ${pagination.page_size}, Total: ${pagination.total_size});

    // Process job results
    result.data.forEach((item, index) => {
      console.log(Result ${index + 1}:);
      console.log(  Item ID: ${item.externalItemId});
      console.log(  Status: ${item.status});
      console.log(  Attempts: ${item.attempt});
      console.log(  HTTP Status: ${item.httpStatusCode});
      
      if (item.errorMessage) {
        console.log(  Error: ${item.errorMessage});
      }
      
      if (item.resultJson) {
        console.log(  Result: ${item.resultJson});
      }
      
      console.log('---');
    });

    return result;
  } catch (error) {
    console.error('Failed to retrieve job results:', error.message);
    throw error;
  }
}

// Example usage:

// Get first 50 results for a job
getJobResults('550e8400-e29b-41d4-a716-446655440001', 1, 50);

// Get next page of results
getJobResults('550e8400-e29b-41d4-a716-446655440001', 2, 50);

// Get all results with default pagination
getJobResults('550e8400-e29b-41d4-a716-446655440001');