Job Service

Jobs allow developers to define and asynchronously execute a series of tasks. Jobs also allow for scheduling, so these tasks can repeatedly execute. Before developing with jobs, make sure you are familiar with the Glossary of Job Terms.

A job developed with Vault Java SDK is called an SDK job. In the Vault UI, this is a job definition with the type SDK Job.

Creating an SDK job has the following steps:

Developers Create a Custom Job Processor: This contains the logic to execute for the job. Learn more about how to develop a custom job processor.
Vault Admins Create SDK Job Metadata: Before you can use a custom job processor in a Job definition, you must define additional metadata for the SDK job in a Jobmetadata component. This metadata provides additional information needed to define the job. For example, this metadata defines the job queue and the chunk_size and defines which job processor to use in the job_code attribute. Learn more about creating SDK job metadata in Vault Help.

Executing an SDK job has different steps for developers and Vault Admins:

Developers Execute Jobs with JobService: Developers can use JobService to initiate jobs from custom Vault Java SDK code. Only job processors that are configured in the @JobInfo annotation as adminConfigurable are available to execute from custom Vault Java SDK code. Learn how to execute jobs with Vault Java SDK.
Vault Admins Configure a Job Definition: Vault Admins can run an SDK job by configuring it in the Vault UI as a job definition. Only job processors that are configured in the @JobInfo annotation as adminConfigurable will appear in the Vault UI for configuration. Learn more about configuring an SDK job definition in Vault Help.

See the Javadocs to learn more about the other interfaces in the job package and to see example code.

SDK Job Limits

The following limitations apply to SDK jobs per Vault:

The maximum chunk size is 500 JobItem instances.
The maximum size of a JobTask is 128 KB.
The maximum number of JobTask instances is 5000.
The maximum size of JobParameters is 8 KB.
The maximum number of JobParameters instances is 8000.
The maximum number of Job queues is 25.
The maximum number of queued SDK Job instances is 1000.

Creating Job Processors

Job processors provide logic to process jobs in bulk. A job processor is a Java class that implements the Job interface and has the @JobInfo annotation. The @JobInfo annotation has the following attributes:

adminCancellable: Determines if this job processor permits the cancellation of job instances which are in the QUEUED or QUEUEING state. This does not fully control the ability for a job instance to be cancelled, for example, jobs in the SCHEDULED state can always be cancelled. Learn more about jobs eligible for cancellation in Vault Help. You can use Vault API or VQL to retrieve the status of a job instance.
adminConfigurable: Determines if this job processor is available for Vault Admins to configure as a Job Definition in the Vault UI and if custom SDK code can invoke this job processor.
idempotent: Indicates if this job processor is idempotent.
isVisible: Determines if a job will appear in the Scheduled, Running, and History tables in the Job Admin UI. Learn more about the Vault UI’s Job Status page in Vault Help.

You can invoke a job processor using triggers and actions in Vault Java SDK code. A job processor can also form the logic for a new job definition. Learn more about job definitions in Vault Help.

You can use the Job interface with the following methods to create a job processor:

The Job#init method prepares data and performs other initialization logic.
The Job#process method executes tasks on the previously initialized data.
The Job#completeWithSuccess method runs if all previously processed tasks completed successfully.
The Job#completeWithErrors method runs if any of the previously processed tasks encountered errors.

You must associate your custom job processor with a job by adding it to the Job Code field of an SDK Job Metadata record, which corresponds to the job_code field of the Jobmetadata component. Learn more about administering SDK job metadata in Vault Help.

The following is a basic skeleton of a job processor:

@JobInfo(adminConfigurable = true, idempotent = true, isVisible = true)
public class CustomSdkJob implements Job {

    public JobInputSupplier init(JobInitContext context) {
        
    }

    public void process(JobProcessContext context) {

    }

    public void completeWithSuccess(JobCompletionContext context) {

    }

    public void completeWithError(JobCompletionContext context) {
  
    }
}

Executing Jobs

You can use JobService to initiate a job from custom Vault Java SDK code.

To initiate a job from code, you must first define the job parameters. The JobParameters interface provides methods to set the start time, title, and parameter values for the job.

To set a job parameter value, you can pass a String to JobParameters#setValue. Alternatively, the JobParamValue interface allows you to create more complex job parameter values. For example, the following code creates a custom job parameter value for record IDs:

@UserDefinedClassInfo()
public class CustomSdkJobParameters implements JobParamValue {

    private List<String> recordIds;

    public List<String> getRecordIds() {
        return recordIds;
    }

    public void setRecordIds(List<String> recordIds) {
        this.recordIds = recordIds;
    }
}

After defining the job parameters, identify the job to run by passing the name of the Jobmetadata component for the job to the JobService#newJobParameters method.

The following example identifies the job as custom_sdk_job__c and sets the job parameters with the user-defined CustomSdkJobParameters value. It then calls JobService#run to start the job 2 minutes after invocation. This calls the job processor associated with custom_sdk_job__c.

public void updateRecordsAsynchronously(List<RecordChange> recordChanges) {

    JobService jobService = ServiceLocator.locate(JobService.class);

    List<String> recordIds = VaultCollections.newList();

    recordChanges.forEach(recordChange -> recordIds.add(recordChange.getNew().getValue("id", ValueType.STRING)));

    if (!recordIds.isEmpty()) {
        JobParameters jobParameters = jobService.newJobParameters("custom_sdk_job__c");

        CustomSdkJobParameters customSdkJobParameters = new CustomSdkJobParameters();
        customSdkJobParameters.setRecordIds(recordIds);
 
        jobParameters.setValue("custom_parameters", customSdkJobParameters);
        jobParameters.setJobRunTime(ZonedDateTime.now().plusMinutes(2));

        jobService.run(jobParameters);
    }
}