Configuring Job Definitions

The job scheduler provides a simple, streamlined way for an Admin to create a batch operation and schedule it to repeatedly execute. Organizations can use Vault’s job scheduling functionality to move documents and objects into new lifecycle states or to send out notifications.

Accessing Job Scheduling

You can schedule jobs and review job statuses from Admin > Operations. Access to this area is controlled by the Admin: Operations and Admin: Jobs permissions.

Glossary of Job Terms

When defining a job, there are several key elements:

Jobs: A series of activities (always a primary action and sometimes additional date-based notifications) that execute against the results of a query.
Job Definitions: The set of rules and configurations which define what a job does and when it does it.
Job Instance: An individual run of a defined job. The instance executes the actions as outlined in the job definition at the time the instance begins. Each time the job runs, it is a unique instance. Details about job instances are available in the audit log, making actions traceable. Admins can also monitor job instances from the Job Status page.
Job Status: The current status of an individual job instance (Scheduled, Success, Cancelled, etc.), visible from the from the Job Status page.
Action: The primary operation that completes, for example, the document status change.
Conditions: Define the query that finds and selects qualified documents for a document operation job. For example, documents must have: Type = Site Management and Status = Approved for Use.
Trigger Date: The special date (based on a document or object field) that acts as a reference against which Vault evaluates whether to run a date-based document or object operation job. Trigger dates can be date or datetime fields on the documents or object records changing state, or date or datetime fields on related documents.
Optional Notifications: Notifications bundled together with a document or object operation job. These notifications use the same conditions and trigger date as the job’s primary action, but can have different offsets from the trigger date. For example, a notification can occur seven days before the trigger date to notify document owners that the scheduled job will update their documents.
Run As: Defines which user account your Vault uses to complete an external URL call job. With most security profiles, you’ll only be able to select yourself, but users with the standard Vault Owner profile can set up a job that runs using any user’s account. This selection is important because it determines which user and session IDs will replace the tokens in the URL.
Primary Documents: The documents affected by the job. For example, a state change job moves primary documents from one state to another and notification job notifies the owners of a primary document.
Related Documents: Documents related to the primary documents through some kind of document relationship like Linked Documents and Supporting Documents. Scheduled jobs will not affect related documents, but you can use date fields from related documents to trigger jobs on the primary document.

How to Define Document Operation Jobs

To create a new job definition for a date-based document operation job:

Navigate to Admin > Operations > Job Definitions and click Create.
Enter a Title for the job. This value appears in the Job Definitions page, audit logs, and automatic notifications to the job owner.
Optional: If needed, change the Name for the job. The field autofills based on the Title, but is editable. This is the value the API uses to reference the job.
In the Type field, select Date Based Document Operation.
Select a user or group (recommended) as the Job Owner. Job owners receive automatic notifications about exceptions encountered during a job instance. Successful jobs do not generate these notifications. Making a user the job owner does not grant any additional application access, so verify that the selected job owners have permission sets with the necessary access.
Select either an Hourly, Daily, Weekly, or Monthly schedule. See Job Scheduling for more information.
Select an Action. Some fields will change based on your selected action. See details below for State Change, Send a Notification, and No Operation actions.
Select a Lifecycle. All jobs are lifecycle-specific and documents must use the selected lifecycle to meet the job’s query conditions.
Under Trigger Date Based On, indicate the conditions for triggering the job. See details below for Source Document Dates and Related Document Dates.
Optional: Under Additional Conditions, select a document field, operator, and field value to add another condition to the document query. If you need more than one additional condition, you can click the plus (+) icon to add them.
Optional: Under Optional Notifications or Notifications, create additional notifications by clicking Add. To add more than one notification, continue to click Add. For Send Date, specify the number of days before the action’s trigger date. Select a Message Template for the notification. Select one or more document roles as Recipients. See details on notifications and message templates.
Optional: To make the job run at the next scheduled time, set the Status to Active. The job definition will not schedule job instances if it is inactive.
Click Save.

How to Define Object Operation Jobs

To create a new job definition for a date-based object operation job:

Navigate to Admin > Operations > Job Definitions and click Create.
Enter a Title for the job. This value appears in the Job Definitions page, audit logs, and automatic notifications to the job owner.
Optional: If needed, change the Name for the job. The field autofills based on the Title, but is editable. This is the value the Vault REST API uses to reference the job.
In the Type field, select Date Based Object Operation.
Select a user or group (recommended) as the Job Owner. Job owners receive automatic notifications about exceptions encountered during a job instance. Successful jobs do not generate these notifications. Making a user the job owner does not grant any additional application access, so verify that the selected job owners have permission sets with the necessary access.
Select either an Hourly, Daily, Weekly, or Monthly schedule. See Job Scheduling for more information.
Select an Action. Some fields will change based on your selected action. See details below for State Change, Send a Notification, and No Operation actions.
Select an Object. For example, if your job should move products into a new state, you would select the Product object.
Optional: Under Additional Conditions, select an object field, operator, and field value to add another condition to the object record query. If you need more than one additional condition, you can click the plus (+) icon to add them.
Under Trigger Date, select an object field to use as the Trigger Date. Choose whether the trigger date should work before and on the job date, or only before the job date.
Optional: Under Optional Notifications or Notifications, create additional notifications by clicking Add. To add more than one notification, continue to click Add. For Send Date, specify the number of days before the action’s trigger date. Select a Message Template for the notification. Select one or more object lifecycle roles as Recipients. See details on notifications and message templates.
Optional: To make the job run at the next scheduled time, set the Status to Active. The job definition will not schedule job instances if it is inactive.
Click Save.

About Notifications for Date Based Jobs

Vault evaluates the value of the object or document field selected as a job’s Trigger Date against the job’s run date to determine whether to send notifications. This can result in different behavior between Date and DateTime type trigger dates.

Vault sends only one notification based on the selected Notification Template for the document. If the document is configured to receive additional notifications based on the same Notification Template, Vault will not send another notification. For example, if you select Assign View Owner as the Notification Template, Vault will only send one notification for a date based job based on this template.

The following shows the behavior of a job run at 11:00 AM on 06/15/2023 with a Send Date value of one (1) day before the trigger date:

Trigger Date Field Type	Trigger Date Field Value	Result
Date	06/16/2023	Vault sends notifications
Date	06/15/2023	Vault does not send notifications
DateTime	06/16/2023 11:01 AM	Vault sends notifications
DateTime	06/16/2023 11:00 AM	Vault does not send notifications

The following shows the behavior of a job run at 11:00 AM on 6/15/2023 with a Send Date value of zero (0) days before the trigger date:

Trigger Date Field Type	Trigger Date Field Value	Result
Date	06/16/2023	Vault does not send notifications
Date	06/15/2023	Vault sends notifications
DateTime	06/16/2023 11:01 AM	Vault does not send notifications
DateTime	06/16/2023 11:00 AM	Vault does not send notifications
DateTime	06/16/2023 10:59 AM	Vault sends notifications

Note: If the Send Date field has a value of zero (0), set the Trigger Date to work before and on the job date. Otherwise, Vault will display incorrect results.

How to Define External URL Call Jobs

External URL jobs are sent from an IP address associated with Vault. To use external URL jobs, you must update your organization’s allowlist to support the *.veevavault.com domains. Learn more about Veeva IP addresses.

To create a new job definition for an external URL call job:

Navigate to Admin > Operations > Job Definitions and click Create.
Enter a Title for the job. This value appears in the Job Definitions page, audit logs, and automatic notifications to the job owner.
Optional: To make the job run at the next scheduled time, set the Status to Active. The job definition will not schedule job instances if it is inactive.
Optional: If needed, change the Name for the job. The field auto-fills based on the Title, but is editable. This is the value the Vault REST API uses to reference the job.
In the Type field, select External URL Call.
Select a user or group (recommended) as the Job Owner. Job owners receive automatic notifications about exceptions encountered during a job instance. Successful jobs do not generate these notifications. Making a user the job owner does not grant any additional application access, so verify that the selected job owners have permission sets with the necessary access.
Select either an Hourly, Daily, Weekly, or Monthly schedule. See Job Scheduling for more information.
In the URL text field under Action Configuration, enter a URL that Vault will call when this job executes. The URL must include https://.
Optional: From the Fields area, search for tokens (Job ID, user details, and Vault details) to include in the URL. To add a field’s token, double-click on the field name.
Optional: When ready, click Validate to automatically check that your URL is valid. Note that Vault does not attempt to connect to the remote host; validation only covers the structure of the URL and validity of any tokens.
Optional: Select the Post Session Credentials via Form Data with Key “Session.id” checkbox to post session credentials through form data. This will allow your URL to call the Vault API, etc. Your URL must be ready to retrieve this session ID. Learn more in the Developer Portal.
In the Run As picklist, select a user account that Vault will utilize when executing the external call. If you have any security profile other than Vault Owner, you can only choose yourself.
Click Save.

How to Define SDK Jobs

To define an SDK job definition, you must first create and deploy a job processor using the Vault Java SDK. Job processors are created by your organization and deployed to your Vault using the Vault Java SDK. You can view the details of the job processors currently deployed to your Vault from Admin > Configuration > Job Processors.

You must also create an SDK Job Metadata record for the job.

Learn more about Vault Java SDK jobs in the Developer Portal.

To create a new job definition for an SDK job:

Navigate to Admin > Operations > Job Definitions and click Create.
Enter a Title for the job. This value appears in the Job Definitions page, audit logs, and automatic notifications to the job owner.
Optional: To make the job run at the next scheduled time, set the Status to Active. The job definition will not schedule job instances if it is inactive.
Optional: If needed, change the Name for the job. The field auto-fills based on the Title, but is editable. This is the value the Vault REST API uses to reference the job.
In the Type field, select SDK Job. At least one SDK Job Metadata record must exist in your Vault for this type to be available for selection.
Select the Job Code this job will execute. This is the value of the Job Code field in the SDK Job Metadata record for the job. You can only select job processor code that has been deployed.
Click Save.

How to Edit Job Definitions

To edit definitions for an existing job:

Navigate to Admin > Operations > Job Definitions and click on the job’s title.
Make any necessary changes.
Set the Status to Active. When you edit, Vault will always set the status to Inactive automatically.
Click Save.

Note that when a job’s conditions reference an inactive component, for example, an inactive lifecycle, you’ll see (Undefined Value) instead of a value for the condition. You must either remove the inactive component or make it active again in order to update the job definition.

Details for State Change Actions

When creating or editing a job with a State Change action, you’ll see the following fields in addition to those detailed above:

(Document operations only) Document Version is the version of the document on which the job will run. All other versions are ignored. Select Absolute Latest to run the job on the latest version of the document whether or not it’s in a steady state. Select Latest Steady State to run the job on the latest steady state version of the document.
(Document operations only) Start States is part of the job’s query for document operations. The document must be in one of the specified states on the trigger date in order to be selected for the job. Note that, with this action type, you cannot add a Status field condition under Additional Conditions.
(Document operations only) Destination State is the state that the job will move the documents into. For example, an expiration job could move documents from the start state Approved to the destination state Expired. Vault will enforce entry actions and criteria for the destination state. Note that state changes via job do not require that a user action configuration exists for the start state.
(Object operations only) Change State To is the state that the job will move the object records into. For example, an expiration job could move object records into the Expired state. Unlike in document operations, you don’t specify a starting state. If you need to filter object records by current state, use Additional Conditions.
The Cancel existing workflows to perform action setting, if enabled, will cancel open workflows (except Read & Understood workflows) on any documents/object records found by the query in order to complete the action. If this setting is disabled, Vault does not perform the action on documents/object records with an open workflow, and logs errors for those items. If Vault cancels a workflow, the document/object record first moves into the cancel state, and then moves into the destination state specified by the job. This triggers entry actions on both states and may have implications based on your Vault’s configuration. Note that this action will not cancel workflows on documents included in a multi-document workflow.
The Override checkout to perform state change setting, if enabled, will allow a State Change action to proceed even when a minor version of the document is checked out. This functionality is only available when the configured Current State is the lifecyle’s configured steady state type and the Destination State is the lifecycle’s configured obsolete state type.

Note that in some cases, document state change jobs can move jobs to documents states in which users can no longer complete Read & Understood workflows. In this case, an Admin must cancel the workflow manually.

Details for Notification Actions

When creating or editing a job with the Send a Notification action, you’ll see the following fields in addition to those detailed above:

Message Template: Defines the text that is sent as the notification. You can define these from Admin > Configuration > Messages. See details below.
Recipients: Defines the users (through their document roles for document operations or through their object lifecycle roles for object operations) that will receive the notification.

Details for No Operation Actions

No Operation is a special type of job action that allows Admins to locate documents or object records that meet specified criteria and send notifications, but not take any action against the located items. In certain situations, this is better than using the Send a Notification action because Optional Notifications function differently: The Send a Notification action uses the trigger date to select an unbounded range of documents or object records: any items with [Date Field] before today, which may be a very large number of items, some of which may no longer be relevant. Optional Notifications use a bounded trigger date: X days before trigger date. For example, “5 days before” only selects items where [Date Field] is today’s date or within 5 days into the future from today.

For example, use a No Operation action with optional notifications (part of the same job) to alert document owners that their content is coming due for Periodic Review. Vault notifies the users, but does not actually change the content (even if the Periodic Review becomes overdue) if the responsible party does not take action.

Please consult with Veeva Support before implementing jobs using this action.

When creating or editing a job with the No Operation action, there are no additional details to specify.

Details for External URL Call HTTPS Post Action

An external URL call navigates to a URL for an external service that understands the parameters being passed and can take additional actions beyond that. If the Post Session Credentials via Form Data with Key “Session.id” checkbox is selected, the action passes a session ID, the service may call back into Vault using the Vault REST API and take any number of actions as the user specified in the Run As parameter. The actions may include querying for more data, creating documents, etc. Your external service must be ready to retrieve this session ID. Learn more in the Developer Portal.

When defining an external URL call, you must use an HTTPS URL.

Trigger Dates on Documents

Vault can trigger a job based on dates from the affected/primary document or dates from a related document. For example, your Vault might include two jobs that move documents into Review Required state: one using dates from the primary document and the other using dates from a related document. These jobs would both use the State Change action type with optional notifications.

In Job A, the trigger date comes from the primary document. Four weeks before the Reapproval Date on CholeCap Brochure, Vault sends a notification to Tracy, the document owner. On the Reapproval Date, the scheduled job moves CholeCap Brochure into Review Required state.
In Job B, the trigger date comes from a document related to the primary document. This type of trigger date uses the related document’s lifecycle state, as well as the date, to determine whether to trigger the job. CholeCap Brochure (the primary document) has references to the document Study 2039 Report, so there is a Linked Document relationship between these documents. Four weeks before the Expiration Date on Study 2039 Report, Vault sends a notification to Tracy, the document owner for CholeCap Brochure), letting her know the linked document is due to expire. On the study report’s Expiration Date, the scheduled job moves CholeCap Brochure into Review Required state.This job is important because the expiring related reference document means the brochure will require review.

Note: Triggering based on a related document is only supported for State Change and Send a Notification jobs. This functionality is only available for relationship types where the target document is version-specific.

Triggering Jobs Using Affected Document Dates

To set up a trigger based on a date from the affected document:

Under Trigger Date Based On, select Primary Document Dates.
Select a document field to use as the Trigger Date.
Choose whether the trigger date should work before and on the job date, or only before the job date.

To set up a trigger based on a date from a document related to the affected document:

Under Trigger Date Based On, select Related Document Dates.
Select one or more Relationship Types. This determines the kind of related documents that the job looks at.
Select a Related Document Lifecycle. The job only looks at related documents in this lifecycle.
Select Related Document States. The job only looks at related documents in these lifecycle states.
Select a document field (on the related documents) to use as the Trigger Date.
Choose whether the trigger date should work before and on the job date, or only before the job date.

Trigger Dates on Objects

Vault can trigger a job based on dates from the affected object record. For example, your Vault might move object records into Review Required state on the Approval Ends date.

Triggering Jobs

To set up a trigger based on a date from the affected object record:

Select an object field to use as the Trigger Date.
Choose whether the trigger date should work before and on the job date, or only before the job date.

Document & Object Notifications & Notification Templates

Vault sends a notification each time a job definition with the Send Notification action is scheduled to run. All other notifications (both as primary action and date-based) associated with job definitions are “expiry” notifications. This means that, for each unique combination of recipient, document version or object record, and notification template, Vault will only ever send one notification. This is true even across different jobs and across different notifications within the same job. To account for this, you must define separate messages for each notification instance.

For example, if you have a job to expire documents and you want to send notifications to the document owner 28, 14, and 7 days before the state change occurs, you will need to define three distinct messages.

Audit Logging

Actions that occur as part of a document operation job are included in the Document Audit History. Actions based on object operation jobs are included in the Object Record Audit History. In the logs, these actions appear with the user name System.

Vault does not track external URL calls in the audit logs.

Job Monitoring

If any action encounters an error, Vault notifies the job owner (user or group) via email. Vault also provides extended options for real-time job tracking and working with scheduled and completed job instances.

Job Scheduling

On the Job Definition page, schedule a job to repeat from once an hour to once a month:

Hourly: Repeats on the specified hourly interval.
Daily: Repeats once a day at the given time.
Weekly: Repeats on one or more specified days of the week at the given time.
Monthly: Repeats either by the specified calendar day or weekday at the given time. For example, to have the job always run on the 13th day of every month, use the Day of Month repeat option. To always run the job on the second Wednesday of every month, use the Day of the Week option.

Note: When setting Daily, Weekly, or Monthly schedules, ensure you select the correct time zone when setting the Time, as this sets the context for the trigger date. Vault evaluates ‘today’ as ‘today in the specified time zone.’ The time zone applies only to the scheduled job and is different from your Vault’s time zone. However, if the scheduled job is to activate a user’s account, it will automatically use your Vault’s time zone.

When there are scheduled jobs configured, Vault puts the job into a queue of tasks at the scheduled start time. If Vault is unavailable at that time because of maintenance, a system outage, or too many simultaneous jobs, the job continues trying to run for approximately 5 hours after the scheduled time. If the job cannot start within that window, Vault skips the instance. These jobs show the Missed Schedule completion status. If your jobs regularly miss their schedules, contact Veeva Support. You may need to stagger your jobs’ start times or reduce the total number of jobs by combining similar jobs.

Note: An hourly job may start at the half hour (for example, 5:30) if the job’s time zone contains a 30 minute offset and your physical time zone does not have a 30 minute offset.