Configure scheduled jobs

This page explains how to configure the recurring jobs in Signing Workflow.

Se also Configuration reference

Reconfigure without restart

Configurations mentioned on this page can be reconfigured at runtime, i.e. you don't have to restart Signing workflow after modifying the config.json file.

Schedule syntax

When scheduling a job (setting schedule) you can choose between two styles.

  • Quartz Cron Expression
  • ISO-8601 Duration

Quartz Cron Expression

Use this if you need a job-firing schedule that recurs based on calendar-like notions such as “every Friday at noon”, “every weekday and 9:30 am”, or even “every 5 minutes between 9:00 am and 10:00 am on every Monday, Wednesday, and Friday during January”.

Example: "0 15 22 * * ?" means at 10:15 pm daily.

More info can be found in the official documentation for Quartz.

The first execution will happen at the scheduled time. The delay configuration is only used to delay the scheduling. You can set this to PT0S to schedule immediately. 

ISO-8601 Duration

Sets the delay between job executions. The first execution will happen after given delay from booting Signing Workflow and repeating every schedule duration.

Examples: 

PT30S Every 30 seconds
P1DT1H Every 1 day and 1 hour (i.e. every 25 hours)

More info can be found at Wikipedia.

Document Retention

The documents stored in the file area can automatically be removed by activating the document retention job. As documents are permanently deleted from the file area it is very important to have a backup scheme in place for recovery and rollback.

The metadata about the document in the database is not removed by this job.

The function can be activated by setting the configuration parameter documentRetention.enabled to true.

Note that if the file area contains many documents the initial time for a full clean-up can take some time. Activation is best done outside office hours and the file area and log files should be monitored for any problems.

  "documentRetention": {
    "batchSize": 100,
    "completedDocumentAge": "P30D",
    "delay": "PT0S",
    "enabled": true,
    "inactiveDocumentAge": "PT12H",
    "schedule": "0 0 2 * * ?",
    "unconsumedDocumentAge": "PT12H"
  },
Click to copy

Retention age policy

The document age policy can be configured for three types:

Configuration parameters:

completedDocumentAge: Max age for all documents that are active and the corresponding order are in state ACCEPTED, REJECTED, CANCELED, or EXPIRED.

inactiveDocumentAge: Max age for all documents that are inactive or in the corresponding order are in state REJECTED, CANCELED, or EXPIRED.

unconsumedDocumentAge: Max age for all documents that are not attached to a signing order. This happens when you upload a document but don't add any signers to it.

Note that ongoing (PENDING) documents are never deleted by this job.

Recovery and rollback

In the case of file area, database corruption, or change in retention age policy to retrieve old documents, the documents can be rolled back by the following procedure:

  1. Stop the application
  2. Restore the document files from the backup to the file area.
  3. Optionally change or disable document retention while investigating root causes.
  4. Run SQL command: UPDATE documents SET file_state = 0
  5. Start the application

When the periodic schedule is activated again the documents will be deleted according to (new) settings.

THIS WILL NOT WORK IF YOU HAVE ACTIVATED deleteOrdersJob. Because that will delete data about the documents from the database. You could also restore the database from a backup.

Delete old signing orders

Enable this job to delete old signing orders from the database.

The statusFilter selects what kind of orders to delete. 

A default value for maximum age is set using defaultAgeLimit, which can be overridden by setting one of the status-specific age limits. E.g. acceptedAgeLimit, cancelledAgeLimit, etc. All age limits are calculated from the time where the order was set to that specific state. totalAgeLimit is calculated from the date the order was created, but will be ignored if left unset.

Documents that are attached to the order will be deleted from storage and from the database.

  "deleteOrdersJob": {
    "acceptedAgeLimit": "",
    "batchSize": 100,
    "cancelledAgeLimit": "",
    "defaultAgeLimit": "P50Y",
    "delay": "PT0S",
    "enabled": false,
    "expiredAgeLimit": "",
    "failedAgeLimit": "",
    "pendingAgeLimit": "",
    "rejectedAgeLimit": "",
    "totalAgeLimit": "",
    "schedule": "0 0 0,1,2,3,4,5 * * ?",
    "statusFilter": "REJECTED, CANCELLED, EXPIRED, FAILED"
  }
Click to copy

Notifications

The system can be configured to send out email notifications to order solicitors and signers.

Notifications, reminders, and warning emails are sent in batches.

  "orderReminder": {
    "batchSize": 25,
    "beforeExpiration": "P2D",
    "delay": "PT3S",
    "enabled": true,
    "schedule": "PT35S"
  }
Click to copy

Notifications contains some informational message and a link, pointing to the Workflow server. 

Each order has the property linkType, which determines the link action.

Link type Link action
0 After authentication, the user will be directed to the Workflow UI, where she can choose an order to sign or reject.
1 After authentication, the user will be directed directly to the Signing Service, where the document is displayed and the user can choose to sign. After signing the document, the user will be directed back to the Workflow UI.

Note: the property linkType has default value 0. Currently, linkType can only be set when using the Automation API to create orders.

Downloading files

When an order has been signed by all selected signers, the order solicitor is notified with an email. The email contains a link that can be configured in two different ways.

This feature is governed by the configuration parameter notifications.downloadLink (true/false). By default, the direct download option is enabled.

downloadLink Link action
false Link to the order view in the Workflow app. This means that the solicitor, after login, is redirected to the web application app where she can choose to click a button to download the file
true (default) Link directly to file download. This means that the solicitor will be prompted to log in, after which the file will be downloaded directly, without presenting the web application 
  "notifications": {
    "downloadLink": true
  },
Click to copy

Order deletion reminder job

If the document retention is enabled, you can also enable the order deletion reminder job, which sends out reminders before the document is deleted. The order deletion reminder job only works on completed errands, which means only completedDocumentAge will be used as a corresponding metric. See more below. To configure this job, you can add the following parameters to your config.json file:

{
  "orderDeletionReminderJob": {
    "enabled": true | false,
    "delay": "PT1M",
    "schedule": "PT5M",
    "batchSize": 1000,
    "timeBeforeDeletion": "P2D"
  }
}
  • enabled - Whether or not the job is enabled. If the document retention job is disabled, the order deletion reminder job will be disabled as well.
  • delay - The delay of the job startup. See more in the section "Schedule syntax".
  • schedule - The schedule of the job. See more in the section "Schedule syntax".
  • batchSize - The size of the number of users that will receive an email for that job run. If this is set to 10, we should send emails to 15 users and the next job run is in 12 hours, we will send 10 emails now and 5 the next job run. Will default to 1000 if not set.
  • timeBeforeDeletion - How long before the document retention job schedules a document deletion. This means that if the completedDocumentAge is set to P30D and the timeBeforeDeletion is set to P5D, the reminder email will be sent out 25 days after it has reached completed status, 5 days before the document will be deleted.

Expire orders job

Orders expire the day after the due date is passed and is expired by the expireOrdersJob. This job does two things: expire orders where the due date has passed and sends emails to the solicitor and all signers, regardless if the signers have the notifyAllSigners option or not. An event is also created, called ORDER_EXPIRED.

Default config:

"expireOrdersJob": {
    "batchSize": 100,
    "delay": "PT0S",
    "enabled": true,
    "schedule": "0 0,30 * * * ?"
}
Click to copy
  • batchSize - The number of orders processed by each job run. If the number of orders to expire exceed the batch size, the outstanding number of orders will be handled the next time the job runs
  • delay - At what delay the job should start
  • enabled - Whether the job is enabled or not
  • schedule - At what schedule the job should run. Could be expressed in cron (as the default configuration) or as as an ISO8601 string.