A Cron Job is a utility that makes updates in RAMCO on a set schedule. A Queried Cron Job identifies records that meet specific criteria and runs a workflow on a set schedule to update these records.
A Queried Cron has two elements:
- A Cron Job with a query. The query will identify the records that should be updated.
- A workflow, which will update the records.
Create the workflow
- If necessary, first create and activate the workflow. For more information on creating workflows, see Workflows - Basic Setup.
Note: The Queried Cron must reference the entity type the workflow runs on.
For example, if the workflow runs on membership records, the Entity Target field on the Cron Job record must be set to the schema name for memberships (cobalt_membership).
Navigate to Cron Jobs
- Select Settings > Cron Jobs.
Create the Cron Job
- Select + New
- Fill in the required fields and save.
Information about the fields is listed below:
Name - the name of the Cron Job
Type - select Queried
Instances are Unique - set to No
Note: If Type is Queried, "Instances are Unique" should equal No. If Type is Native, "Instances are Unique" should equal Yes.
The system will check this field when it starts a Cron Schedule to ensure Cron Schedules with the same Message Name do not overlap.
For example, if there are overlapping Process Queued Payment Cron Schedules (Native Cron Job), the process will create duplicate Invoice records.
Because you can have multiple Queried Cron Jobs in the system with the same Message Name (QueriedCronJob), we cannot use this fail safe check.
Workflow for Query - use the lookup to select the workflow
Trigger Interval - the number of milliseconds between requests to run the workflow. For most workflows 50-100 milliseconds should be the default.
Expression - how often to run (once a day, every fifteen minutes, etc. Use https://crontab.cronhub.io/ for help finding an expression)
Process - leave this blank
Entity Target - The type of record (Contacts, Memberships, etc.) that the Queried Cron will update. Enter the schema name of the entity (i.e. for Membership, this would be cobalt_membership)
Message Name - the message name to be run from the server event handlers.
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, manually set the Message Name to 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.
- In the toolbar, click the View Query button. A new window will open.
- The Look For field will be set to the same record type as the Entity Target field on the Cron Job record. If this is changed the Queried Cron Job will not work.
- Click Details > Select to add criteria.
- Save the advanced find view before closing the window.
- Save the Cron Job record.
Note: The query can only search for specific values.
A query cannot search for changes in fields.
For example, a query can search for contact records where the email field contains "gmail;" however, it cannot search for contact records where the email field changed from "test@yahoo.com" to "test@gmail.com".
NOTE:
Certain "Date" field criteria will not work at this time if there are any records within the entity that have a null value for the "Date" field that is being used in the query. Any date operator that doesn't have a right-hand value (for example "today", "last year", "this year", "next year", "yesterday") or is in the specific list below will not work if any records have a null value for the given field regardless of whether the records are active or inactive. This should be corrected in Cobalt 4.1. The workaround for now if using a "Date" field in the criteria is to use firm dates and operators such as "on", "on or after", "on or before" where you will set a right-hand value or update any records within the entity that have a null value for the date field included in the query.
- lastxweeks
- nextxweeks
- lastxmonths
- nextxmonths
- lastxhours
- nextxhours
- lastxdays
- nextxdays
- olderthanxmonths
- lastxyears
- nextxyears
- lastxfiscalyears
- lastxfiscalperiods
- nextxfiscalyears
- nextxfiscalperiods
- infiscalperiod
- infiscalyear
Additionally, 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.
