# 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][2]. **Job Status** : The current status of an individual job instance (**Scheduled**, **Success**, **Cancelled**, etc.), visible from the [Job Status page][2]. **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 to use when replacing 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 a 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. **Usages** : Specifies where in Vault this job is available for configuration and execution. This option is only available for SDK job types. Currently, _Workflow_ is the only available option and this field is not editable. ## How to Edit Job Definitions {#how-to-edit-job-definitions} To edit definitions for an existing job: 1. Navigate to **Admin** > **Operations** > **Job Definitions** and click on the job's title. 2. Make any necessary changes. 3. Set the **Status** to _Active_. When you edit, Vault will always set the status to _Inactive_ automatically. 4. 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. ## How to Define Document Operation Jobs To create a new job definition for a date-based document operation job: 1. Navigate to **Admin** > **Operations** > **Job Definitions** and click **Create**. 2. Enter a **Title** for the job. This value appears in the **Job Definitions** page, audit logs, and automatic notifications to the job owner. 3. 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 API uses to reference the job. 4. In the **Type** field, select _Date Based Document Operation_. 5. 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. 6. Select either an _Hourly_, _Daily_, _Weekly_, or _Monthly_ schedule. See [Job Scheduling][1] for more information. 7. Select an **Action**. Some fields will change based on your selected action. See details below for [_State Change_][2], [_Send a Notification_][3], and _[No Operation][4]_ actions. 8. Select a **Lifecycle**. All jobs are lifecycle-specific and documents must use the selected lifecycle to meet the job's query conditions. 9. Under **Trigger Date Based On**, indicate the conditions for triggering the job. See details below for [_Source Document Dates_][5] and [_Related Document Dates_][6]. 10. 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. 11. 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. 12. 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. 13. Click **Save**. ## 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.
### Triggering Jobs Using Affected Document Dates {#trigger-on-affected} To set up a trigger based on a date from the affected document: 1. Under **Trigger Date Based On**, select **Primary Document Dates**. 2. Select a document field to use as the **Trigger Date**. 3. Choose whether the trigger date should work before and on the job date, or only before the job date. ### Triggering Jobs Using Related Document Dates {#trigger-on-related} To set up a trigger based on a date from a document related to the affected document: 1. Under **Trigger Date Based On**, select **Related Document Dates**. 2. Select one or more **Relationship Types**. This determines the kind of related documents that the job looks at. 3. Select a **Related Document Lifecycle**. The job only looks at related documents in this lifecycle. 4. Select **Related Document States**. The job only looks at related documents in these lifecycle states. 5. Select a document field (on the related documents) to use as the **Trigger Date**. 6. Choose whether the trigger date should work before and on the job date, or only before the job date. ## How to Define Object Operation Jobs To create a new job definition for a date-based object operation job: 1. Navigate to **Admin** > **Operations** > **Job Definitions** and click **Create**. 2. Enter a **Title** for the job. This value appears in the **Job Definitions** page, audit logs, and automatic notifications to the job owner. 3. 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 API uses to reference the job. 4. In the **Type** field, select _Date Based Object Operation_. 5. 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. 6. Select either an _Hourly_, _Daily_, _Weekly_, or _Monthly_ schedule. See [Job Scheduling][1] for more information. 7. Select an **Action**. Some fields will change based on your selected action. See details below for [_State Change_][2], [_Send a Notification_][3], and _[No Operation][4]_ actions. 8. Select an **Object**. For example, if your job should move products into a new state, you would select the _Product_ object. 9. 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. 10. 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. 11. 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. 12. 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. 13. Click **Save**. ## 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: 1. Select an object field to use as the **Trigger Date**. 2. Choose whether the trigger date should work before and on the job date, or only before the job date. ## Details for State Change Actions {#state_change} 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 Send a Notification Actions {#notification} When creating or editing a job with the _Send a Notification_ action, you'll see the following fields in addition to those detailed above: * **Notification Template**: Defines the text that is sent as the notification. You can define these in **Admin > Configuration > Email & Notifications**. * **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. * **Trigger Date**: The job sends the notification every time the job runs and the _Trigger Date_ and _Additional Conditions_ criteria are true. This means that if the job runs daily and it meets the _Trigger Date_ and _Additional Conditions_ criteria, the notification is sent daily. ## Details for No Operation Actions {#no-operation} _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, using the _No Operation_ action or _Optional Notifications_ is better than using the _Send a Notification_ action because [_Optional Notifications_][8] function differently: The _Send a Notification_ action uses the trigger date to select an **unbounded** range of documents or object records: any items with the _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 the _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. We recommend that you consult your Veeva Representative before implementing jobs using this action. ## Details for Optional Notifications {#optional-notifications} _Optional Notifications_ and _Notifications_ (for the [_No Operation_][4] action) send the notification relative to the _Trigger Date_ for documents and object records that meet the Additional Conditions. Each _Notification_ is triggered X days before the _Trigger Date,_ but it is only sent once per _Notification Template_ and _Recipient_ combination. For documents, it is sent once for each version, which means that if the version changes, a notification is sent once for that version.
For example, _5 days before_ only selects items where the _Date_ field is today's date or within five days into the future from today. However, if a new document or object record is created where the _Date_ field is four days before, the notification is still sent, because it meets the criteria for the _5 days before_ rule, but a notification hasn't been sent yet. An example use case is a _No Operation_ action with _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. If you set the _Trigger Date_ as the _Next Periodic Review Date_ and you add _Notifications_ for 60, 30, 15, and 5 days before, the _Recipients_ receive four _Notifications_. Let's say a new document is migrated in, and its _Next Periodic Review Date_ is 20 days from when the job runs, Vault sends the 30-day notification, because the 20 days are between the 30 and 15 day _Notifications_, and Vault knows that the recipients haven't received the 30-day notification yet. Vault does not send the 60-day notification, because the 20 days does not fall between the 60 and 30 day _Notifications_.
## 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 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 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|
## How to Define SDK Jobs {#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: 1. Navigate to **Admin > Operations > Job Definitions** and click **Create**. 2. Enter a **Title** for the job. This value appears in the **Job Definitions** page, audit logs, and automatic notifications to the job owner. 3. 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. 4. 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 API uses to reference the job. 5. Optional: Select **Once** from the **Schedule** drop-down menu if this job is intended for use in a object and document workflow Job step. If selected, a **Usages** field populates with **Workflow** automatically selected. You cannot edit this field. Optional: Select **Auto-complete workflow job step** to complete the associated Job step when the job completes. If this option is not selected, you must manually complete the Job step through Vault API or Vault Java SDK. This option is only available if **Once** is selected from the **Schedule** drop-down menu. 6. 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. 7. 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. 8. Click **Save**. ## How to Define External URL Call Jobs {#how_to_define_external_url_calljobs} 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: 1. Navigate to **Admin** > **Operations** > **Job Definitions** and click **Create**. 2. Enter a **Title** for the job. This value appears in the **Job Definitions** page, audit logs, and automatic notifications to the job owner. 3. 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. 4. 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 API uses to reference the job. 5. In the **Type** field, select _External URL Call_. 6. 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. 7. Select either an _Hourly_, _Daily_, _Weekly_, or _Monthly_ schedule. See [Job Scheduling][1] for more information. 8. In the **URL** text field under **Action Configuration**, enter a URL that Vault will call when this job executes. The URL must include `https://`. 9. 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. 10. 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. 11. 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. 12. 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. 13. Click **Save**. ## 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 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. ## 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 {#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. When setting _Daily_, _Weekly_, or _Monthly_ schedules, Vault uses the Vault Time Zone configured in **Admin > Settings > Language & Region Settings > Vault Information**. You can also reference your local time and time zone below the _Vault Time Zone_ field. If you change your Vault's time zone while a job is active, the new time zone applies to the next active job. If a Vault's Time Zone observes Daylight Saving Time (DST), the job scheduler adjusts scheduled jobs by one hour. For example, a job normally scheduled at 08:00 Pacific Standard Time (UTC -8) will be rescheduled to 09:00 Pacific Daylight Time (UTC -7) once DST begins, and rescheduled back to 08:00 Pacific Standard Time (UTC -8) once DST ends. In relation to UTC, the job remains scheduled at 15:00 UTC, because UTC does not observe DST.
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 five 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.
[1]: #scheduling [2]: #state_change [3]: #notification [4]: #no-operation [5]: #trigger-on-affected [6]: #trigger-on-related [8]: #optional-notifications