A Cron Job is a utility to make updates in CRM on a set schedule. A queried Cron Job identifies records that meet specific criteria in CRM and updates these records on a set schedule using a workflow. A Queried Cron has two elements:
- A Cron Job with a query. The query will identify which records should be updated.
- A workflow. The workflow will update the records identified in the query.
Create the workflow
If the workflow needed for the queried Cron Job does not yet exist, create it, and activate the workflow. For more information on creating workflows, see Workflows - Basic Setup.
Note: the Workflow must run on the same entity that the Queried Cron will reference (for example, if the Workflow runs on Memberships, the ‘Entity Target’ field on the Cron Job must be set to the schema for Memberships, “cobalt_membership”).
Create the Cron Job
- Click the +New button in the toolbar
- A new record will open. Fill in the fields needed and save.
- Information about the fields is below.
Name - the name of the Cron Job
Type - select Queried
Instances are Unique - set to No
Note: If it is a Queried Cron Job, Instances are Unique should equal No. If it is a Native Cron Job Instances are Unique should equal Yes.
The purpose of this field is for the system to check the field when it starts a Cron Schedule to make sure Cron Schedules with the same Message Name do not overlap. For example, if there are overlapping Process Queued Payment Cron Schedules (Native Cron Job), it will create duplicate Invoice records.
Because you can have multiple Queried Cron Jobs in the system with the same QueriedCronJob Message Name, we cannot use this fail safe check.
Workflow for Query - this is a lookup the workflow tied to the queried Cron Job
Trigger Interval - this number is milliseconds between workflow requests = Enter the number of milliseconds between requests to run the workflow. For most workflows 50-100 milliseconds should be the default.
Expression - the expression tells the cron job how often to run (once a day, every fifteen minutes, etc. See https://crontab.cronhub.io/ for help finding an expression)
Process - leave this field blank
Entity Target - What type of record will the Queried Cron update (Contacts, Memberships, etc)? The Entity Target must be specified using the schema name of the entity (ie for Membership, this would be "cobalt_membership")
Message Name - message name to be run from the server event handlers (Note: Some systems may have a Business Rule that hides this field for Queried Cron Jobs and automatically sets the value to "QueriedCronJob".) If the Business Rule is not set up in your system, set the Message Name = QueriedCronJob
- Once the Cron Job is saved, Cron Schedules will populate in the ‘Pending Cron Job’ subgrid. After the Cron Job runs, Cron Schedules will appear in the ‘Historical Cron Jobs’ subgrid. (Note: Cron Schedules will not generate if the first schedule is more than a week away. For example, if the expression is set for the 1st of every month at 12am and today is 5th, a Cron Schedule will not generate until midnight 7 days before the 1st)
Set the Query
The Query will determine what records are updated by the Queried Cron / Workflow.
- In the toolbar, click the View Query button. An Advanced Find will open.
- On the Advanced Find, the ‘Look For’ field will be set to the entity in the ‘Entity Target’ field on the Cron Job. The ‘Look For’ can not be changed or the Cron Job will not work.
- Click the Details button to make edits. Add criteria to the Advanced Find and click Save before closing the window.
- Save & Close the Cron Job.
- The query can only search for specific values. For example, a query can search for Contact records where the Email field contains "gmail". A query cannot be created to search for changes in fields. For example, a query cannot search for Contact records where the Email field changed values from "email@example.com" to "firstname.lastname@example.org".
- The query can be particular about "Date and Time" fields. If a query includes criteria for a "Date and Time" field and the Cron Schedule Process Log shows that it is not picking up and evaluating the expected records, then set the field Behavior to "User Local".
Here is an example of the Process Log not picking up/evaluating the expected records.
Here is how the Date and Time Field should be set with Behavior = User Local.
Here is a Process Log that shows the Cron Schedule picking up/evaluating the expected records correctly when the Date and Time field has Behavior set to User Local.