Salesforce Bulk Job Tool

Why?

Salesforce Bulk API 2.0 allows developers to import large volumes of data through an asychronous process. The overall status of these jobs can be monitored through Salesforce's setup menu under the "Bulk Data Load Jobs" section.

Unfortunately, the setup menu does not allow users to view specific details about failed records when using the Bulk API 2.0. This is a simple command-line tool that allows us to retrieve and report on errors from the Bulk API 2.0.

How?

This tool leverages the Salesforce CLI to authenticate with Salesforce's APIs. See: https://developer.salesforce.com/tools/salesforcecli

Once authenticated, we are able to fetch detailed job status and specific errors through the API directly, through the various APIs provided by Salesforce:

• https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/get_all_jobs.htm
• https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/get_job_info.htm
• https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/get_job_failed_results.htm

What?

This is a simple Javascript command-line tool that provides the ability to extract and report on Bulk API 2.0 errors and export them to CSV or JSON formats.

Installation

Install dependencies

First, install the Salesforce CLI tool and node.js:

• https://developer.salesforce.com/tools/salesforcecli
• https://nodejs.org

Next, open a terminal (Mac/Linux) or command prompt (Windows), use the following command to install the bulk-jobs tool from NPM:

npm install -g sf-bulk-jobs

Authenticate your org

Open a terminal or command prompt and authenticate your Salseforce org:

sf org login web -r https://yourorg.my.salesforce.com

Replace the value of https://yourorg.my.salesforce.com above with the appropriate instance URL of your org in the following format:

• For production orgs: https://<my_domain_name>.my.salesforce.com
• For sandbox orgs: https://<my_domain_name>--<sandbox_name>.sandbox.my.salesforce.com

This command will launch a browser for you to complete the authentication process.

Usage

The overall usage is as follows:

bulk-jobs [email protected]

Replace the value of [email protected] above with the username of the org that you would like to use. Note that you must complete the steps in the Installation section above to authenticate your org.

By default, the status of all completed Bulk v2.0 jobs from the current day will be displayed.

Options

The tool supports a variety of options. You may also view the built-in help:

bulk-jobs --help

The tool supports the following command-line options:

• --help: Displays help text and usage information
• --version: Displays the version of the tool
• -i, --ids: Export specific job IDs
• -d, --date: Export jobs for a specific date
• -m, --mode: Choose to export jobs or errors
• -f, --format: Choose between csv or json output formats
• -o, --output: Write exported data into a file

Export Specific Job IDs

To export a specific job ID, use the -i flag:

bulk-jobs [email protected] -i 750W4000003R25dIAC

You may also specify multiple job IDs:

bulk-jobs [email protected] -i 750W4000003R25dIAC 750W4000003R5t7IAC

If this option is specified at the same time as -d or --date, then the provided date parameter will be ignored.

Export to CSV

Use the -f flag to set the format to CSV:

bulk-jobs [email protected] -f csv

This allows the options of:

• json: The default. Exports to JSON format.
• csv: Exports to CSV format.

Export to a File

Use the -o flag to specify an output file. If this option is not specified, results will be written to your terminal's standard output.

bulk-jobs [email protected] -f csv -o jobs.csv

Export Error Details

Use the -m option to control the export mode:

bulk-jobs [email protected] -f csv -m errors

This allows the options of:

• jobs: The default. Provides a summary of jobs including total records processed and total number of errors
• errors: Provides a detailed export of all errors for the jobs.

Export Results for a Specific Date

Use the -d option to specify a date:

bulk-jobs [email protected] -d 2024-06-26

The date provided must be in ISO format (yyyy-mm-dd), or today. The default is today.