Specifying Dates Using Natural Language

As a scheduling application, JAMS uses date specifications for many of its features and functions. Sometimes using an exact date specification is sufficient for scheduling a Job. However, a generic term or phrase, such as using Workdays or First Friday of Month, can provide additional flexibility. JAMS supports natural language for generic date entries throughout the client interface.

Uses for Natural Language in JAMS

There are three key scenarios for JAMS to accept generic date specifications:

Scheduling Jobs to Run

Generic dates can be used when scheduling a Job in JAMS to allow for more flexibility. You can also use generic dates to prevent a Job from running on a date by specifying an exception. See Triggers for more information.

Default Parameters

If a Job parameter’s data type is DATE, you can specify a default value using generic date specifications. This can be useful if you need to pass this date value to another script or application.

When you select a Job, you will see a form to set values for the Job's parameters. Parameters with a data type of DATE are presented using the standard MM/DD/YYYY date field, but JAMS uses the generic date specification to dynamically determine the default date.

When JAMS automatically submits Jobs, prompting for the parameter values is not possible. Instead, the generic date specification is evaluated to obtain the value for the parameter.

Scripting

You can use the ConvertTo-Date PowerShell cmdlet for scripting in your Jobs. You can also use it to validate that a generic date will evaluate to the expected date. For more information on its parameters, see JAMS PowerShell Cmdlets.

How JAMS Interprets Natural Language

When using a modifier, such as LAST, JAMS interprets this to mean " the last occurrence of the specified object." If you specify “Last Monday”, the Job cannot be scheduled because JAMS evaluates this as a date in the past. If today is a Monday, “Last Monday” will give you the date from Monday of last week, and if today is a Tuesday, it will give you yesterday’s date. However, this specification may work as expected if you are using it for scripting or a parameter.

Using PowerShell or Projected Schedules to Validate a Natural Language Specification

To help you validate your natural language specification will work as expected, you can use the ConvertTo-Date PowerShell cmdlet or a Projected Schedule to see the expected date value.

For example, you can enter the following code into PowerShell to see how it will evaluate. This will show you how JAMS will use the date. Because this will always evaluate to a date in the future, JAMS cannot use "1st Workday of Next Month" for scheduling a Job.

Copy 
ConvertTo-Date "1st Workday of Next Month" -server localhost

To use a date other than the current date as a reference, you can use the option below.

Copy 
ConvertTo-Date "1st Workday of Next Month" -server localhost –Today “February 1, 2023” 

You can also use a Projected Schedule to see if your defined Job is expected to run on the days you expect. The Projected Schedule displays a graphical view of future JAMS Jobs and Sequences based on defined schedules. Users can view all scheduled Jobs or filter a subset of Jobs over a specified time range. See Working with Projected Schedules for more information.

Natural  Language Options

JAMS can evaluate date specifications that are relative to the current date or a generic date. See the tables below for information on the options for specifying a date.

Daily or Today

Description Enter "Today" to specify the current date. "Daily" is synonymous with Today and is used primarily for readability.
Examples for Scheduling "Daily", "Today"
Examples for Scripting/Parameters "Today"

Day of the Week

Description Enter the full name of a weekday or the first three letters of a weekday name. When specifying a day of the week, such as MONDAY, JAMS interprets this as “Monday of this week.” In this context, a week begins on Monday and ends on Sunday.

The days of the week can be preceded by a modifier such as LAST, THIS, or NEXT. THIS is the default, so explicitly adding it as a modifier has no effect on the evaluation and is used only for readability.
Examples for Scheduling "Mondays", "This Monday"
Examples for Scripting/Parameters "This Monday", "Next Monday", "Last Monday"

Day of the Month

Description Enter a specific date using the format of month/day for sites in the United States. You can use the day/month format for other locations.
Examples for Scheduling "1/1", "4/1", "7/1", "10/1"
Examples for Scripting/Parameters "1/1", "4/1", "7/1", "10/1"

Weekdays

Description Enter "Weekdays" to default to Mondays through Fridays as Workdays for scheduling. This can also specify the current date, if it is a weekday.
Examples for Scheduling "Weekdays"
Examples for Scripting/Parameters "Weekdays"

Workdays

Description Enter "Workdays" to default to Mondays through Fridays as Workdays for scheduling.

If your site uses different Workdays, you can define them system-wide in the Configuration shortcut menu or override them by using a Date Type in a JAMS Calendar. When you define a Date within a Date Type, you can set the Date to be a workday or a non-Workday. See the Calendars section for more information.

If you specify "Workday" or "Workdays", JAMS determines if a day is a workday by checking the Workdays specified in the Configuration Shortcuts menu and in the Calendar. For the date in question, JAMS checks the following in the Date Definition in the Calendar.

  • If the Workday check box is enabled, the date is a workday.
  • If the Workday box is unchecked, the date is not a workday. However, if the check box is filled, it indicates that the special date should have no effect on the workday status.
Examples for Scheduling "Workday", "Workdays"
Examples for Scripting/Parameters "Workday”, "Workdays"

Tomorrow

Description Enter "Tomorrow" to display the current date plus one day.
Examples for Scheduling None.

This will not schedule a Job because the date will always evaluate to a future date. For example, if the specification is evaluated on a Monday, it will evaluate to Tuesday. The next day, it will evaluate to Wednesday rather than Tuesday, so the Job will not run.
Examples for Scripting/Parameters "Tomorrow"

Yesterday

Description Enter "Yesterday" to display the current date minus one day.
Examples for Scheduling None.

This will not schedule a Job because the date will always evaluate to a past date.
Examples for Scripting/Parameters "Yesterday"

Holidays

Description This is used to add days to the specified date. This is used to identify holidays from a JAMS Calendar. You can create holidays by creating a Holiday Date Type and adding specific dates to it. Dates in the DateType need to manually added and updated.
Examples for Scheduling You can specify “Holidays” as a ScheduledDate to have a Job run on any specified holiday. You would need to specify the JAMS Calendar that contains the Holidays Date Type.

"Last Monday of May", "4th day of July", "first Monday in September", "4th Thursday of November", "25th day of December".

Examples for Scripting/Parameters The AddHolidays Sample Job in the Samples Folder has several examples for adding Holidays.

"Last Monday of May", "4th day of July", "first Monday in September", "4th Thursday of November", "25th day of December"

Every Other Day

Description Enter "Every Other Day" to skip one or more days. JAMS will use the next available occurrence of the specified date type, repeating on each alternate available date. Days can be set using Day-of-Week specifications, Weekday, or Workday.

To determine the next scheduled date for Job, JAMS uses two fields:

  • The Scheduled Date - View the Scheduled Date from the Schedule tab in the Job Definition
  • The Last Autosubmit Dates - View the Last Autosubmit Date from the Definitions screen, if you add the column from the Column Chooser. (Right-click any column heading and select Column Chooser.)

If the Last Autosubmit Date is after the Scheduled Date, the Autosubmit Date is used to calculate the next execution of the Job. If neither date has a value, the current date is used as the start date. The Last Autosubmit Date is used rather than the "Scheduled Start Date", so you can have Jobs that are constantly shifting.

Examples for Scheduling Example A:

You could have a Job scheduled for "First Monday of Month, Every other Monday" and it would run on the following Dates:

  • January 2, 2023
  • January 16, 2023
  • January 30, 2023
  • February 6, 2023 (There is only a one-week gap due to the "First Monday of Month" option.)
  • February 20, 2023 (This is from the "Every other Monday" option, but it shifted due to the previous short gap.)

Example B:

Job A is created on Saturday and scheduled to run "Every Other Workday". The Job will run on Monday, Wednesday, and Friday the first week, and then Tuesday and Thursday the second week, and so on.
Examples for Scripting/Parameters "Every Other Monday"

Date + Number of Days

Description Enter a date and the number of days to add days to the specified date.
Examples for Scheduling "Last Sunday+1 Workday" will run a Job on Mondays, unless the Monday is a non-workday. The Job will then run on the following Tuesday.

NOTE: When JAMS evaluates "Weekdays+1" or "Workdays+1", the scheduled date will always be in the future, so the Job will never run. When evaluated on a Tuesday, the result is Wednesday and so on. The "Last" modifier should be used in conjunction with the base date for this approach to be useful for scheduling.

Examples for Scripting/Parameters "Weekdays+1", "Workdays+1"

Date - Number of Days

Description Enter a date and the number of days to subtract days from the specified date.
Examples for Scheduling "Tuesday -1 Workday" to run a Job on Mondays, unless the Monday is a non-Workday, in which case you want the Job to run on the preceding Friday.

NOTE: "Weekdays-1" or "Workdays-1" will run a Job on Sundays rather than Sunday, Monday, Tuesday, Wednesday, and Thursday.

When JAMS evaluates the specification on a weekday, the resulting day will always be in the past and the Jobs are not scheduled. When the specification is evaluated on a Tuesday, the result is Monday because Tuesday is the next weekday.

On a Sunday, the next weekday is Monday, so it evaluates to Sunday. As an alternative, set the Scheduled Date property to Daily and the Except For Date property to specific days such as Friday or Saturday.
Examples for Scripting/Parameters "Weekdays-1", "Workdays-1"

Date Specification + Period Specification

Description Enter a date and period to identify a date relative to an arbitrary period of time, such as describing a month or fiscal period. A complex date specification may be thought of as two components: The day specification and the period specification.

For example, in the text "1st Workday of Next Month," the day specification is 1st WORKDAY and the period specification is Next Month. Two different options can be used for structuring this specification. If you do not specify the day of period, the default becomes the current day.

  • Day Specification values: "First, Last, 1st, 2nd, 3rd, Integer (st, nd, th)" + "Day-of-week, Workday, Weekday, Day, Month"
  • Period Specification values: "This, Next, Last" + "Year, Month, Month-name, Specific Date, Date-Type Specific-Date-Type"

NOTE: When used in the context of a time period, a week is defined as starting on the first day of the period and continuing for seven days.
Examples for Scheduling "1st Workday of Month", "2nd Day of this Week", "2nd Monday of this Month", "3rd Day of Week", "4th Day of Month"
Examples for Scripting/Parameters "1st Workday of Next Month", "Last Day of Last Month", "First Monday of Next Month", "First Monday of Last January", "6th Weekday of Next Month"

Date Specification + Period Specification + Number of Days

Description Enter a day, period, and number of days to identify a date relative to an arbitrary period of time, such as describing a month or fiscal period and adding one or more days.
Examples for Scheduling "First day of month + 1 workday"
Examples for Scripting/Parameters "Last day of last month + 1 workday"

Date Specification + Period Specification - Number of Days

Description Enter a day, period, and number of days to identify a date relative to an arbitrary period of time, such as describing a month or fiscal period and subtracting one or more days.
Examples for Scheduling "16th Day of Month -1 Workday"
Examples for Scripting/Parameters "16th Day of Month -1 Workday"