Viewing, creating, modifying, and deleting schedules via the REST Web Service API is available in Exago v2019.2+. This feature requires the installation and proper configuration of the Scheduler Service.
NoteAll requests require a Session ID URL parameter and basic request headers. In the following document, headers are omitted in the interest of brevity.
Schedule JSON
A schedule is represented as a JSON object with the following properties:
| Name | Type | Writable | Description |
|---|---|---|---|
| Id | string | no | The GUID which uniquely identifies this schedule. |
| ScheduleName | string | required-create | The descriptive name of the schedule. |
| ReportName | string | required-create | The name of the report being scheduled including the relative folder path. |
| Status | enum | no | ScheduleJobStatus The read-only current status of the schedule. |
| ExportType | enum | yes | ScheduleExportType The file type of the created report when the schedule runs. |
| Password | string | yes | The PDF or Excel output file password. |
| isArchive | boolean (false) | no | true if the schedule is archived, false if it is not. |
| JobType | enum | no | ScheduleJobType The read-only type of job this schedule will perform. |
| Recurrence | ScheduleRecurrence | yes | A JSON object representing the schedules recurrence pattern (e.g. time, day and range of running). |
| Filters | array of ScheduleFilter | yes | An array of JSON objects representing the filters to apply to the report in this schedule. |
| Parameters | array of ScheduleParameter | yes | An array of JSON objects representing the parameters for this schedule. |
| Batch | ScheduleBatchInfo | yes | A JSON object representing the batch processing information. |
| Recipients | ScheduleRecipientInfo | yes | A JSON object representing the e-mail recipients of this schedule's report. |
Schedule Example
This example represents a schedule named MySchedule which will run a report named MyReport from the Reports folder immediately. When it runs, a PDF file with the password "abcd" will be generated an attached to an e-mail sent to myemail@me.com. No additional filters have been put on the report. A parameter named @MyIntParameter@ will be passed to the report with a value of 4.
{
"ScheduleName": "MySchedule",
"ReportName": "Reports/MyReport",
"ExportType": "pdf",
"Password": "abcd",
"Recurrence": {
"IsImmediate": "true"
},
"Filters": [],
"Parameters": [
{
"Id": "MyIntParameter",
"Value": "4"
}
],
"Recipients": {
"EmailResults": "true",
"AttachOutputToEmail": "true",
"ToAddresses": [
"myemail@me.com"
]
}
}
List All Schedules
GET /schedules
List all of the schedules in the current configuration. Returns an array of ScheduleListItem objects, each representing an individual schedule.
Create New Schedule
POST /schedules
Create a new schedule. The ScheduleName and ReportName are required. Returns with a Schedule object representing the new schedule.
Example
This example creates a new schedule named MyTestSchedule. This schedule will run a report named Products by Employee from the Products folder 10 times, starting on October 17, 2019. The report will run at 2:45 PM only on weekdays. The report will be saved as a PDF file.
{
"ScheduleName": "MyTestSchedule",
"ReportName": "Products/Products by Employee",
"ExportType": "Pdf",
"Recurrence": {
"IsImmediate": false,
"RecurrenceType": "Daily",
"RecurrenceRange": "EndAfterNOccurences",
"ScheduleTime": "14:45",
"RepeatEvery": false,
"RangeStartDate": "2019-10-17",
"OccurrencesToEnd": 10,
"RecurrencePattern": {
"Daily": {
"IsEveryWeekday": true,
"IsDailyEveryNDays": false
}
}
}
}
Show a Schedule
GET /schedules/{scheduleID}
Show the properties of the schedule specified by the scheduleID. Returns a Schedule object representing the schduleID requested.
Edit a Schedule
PATCH /schedules/{scheduleID}
Edit the properties of the schedule specified by the scheduleID. Include only those properties to be updated. Returns no JSON objects but will return HTTP status code 204 to indicate success.
Example
This example changes the ExportType of the schedule with ID aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee to be RTF.
PATCH /schedules/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
{
"ExportType": "Rtf"
}
Delete a Schedule
DELETE /schedules/{scheduleID}
If the specified schedule is active (that is, it is not Completed or Deleted) it will be set to Deleted status. If the specified schedule is inactive, it will be flushed from the scheduler. Therefore, two calls must be made or a seperate call to flush the scheduler must be made if the schedule was active when it deleted and the intention is to flush it. Returns no JSON objects but will return HTTP status code 204 to indicate success.
Example
This example marks schedule with ID aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee as Deleted.
DELETE /schedules/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
Flush the Scheduler
POST /schedules/flush
Flush the scheduler of all Completed and Deleted schedules. An array of ScheduleListItem will be returned with the resulting schedule list after the flush has occured.
ScheduleListItem JSON
A JSON object which represents an item in the schedule list. An array of ScheduleListItem is returned when calling GET /schedules
| Name | Type | Writable | Description |
|---|---|---|---|
| Id | string | no | The GUID which uniquiely identifies this schedule. |
| ScheduleName | string | no | The descriptive name of the schedule. |
| Type | enum | no | ScheduleRecurrenceType Indicates the type of recurrence this schedule has. |
| ReportName | string | no | The name of the report being scheduled including the relative folder path. |
| LastExecDate | string | no | The date and time of the most recent execution of this schedule, in yyyy-mm-dd hh:mm:ss format. If the schedule has never run, returns 0001-01-01 00:00:00. |
| NextExecDate | string | no | The date and time of the next execution of this schedule, in yyyy-mm-dd hh:mm:ss format. If the schedule will not run again, returns 0001-01-01 00:00:00. |
| Status | enum | no | ScheduleJobStatus The read-only current status of the schedule. |
| RunCount | integer | no | The number of times this schedule has been executed. |
| UserId | string | no | The value of the built-in @userId@ parameter for the session running the command. |
| CompanyId | string | no | The value of the built-in @companyId@ parameter for the session running the command. |
Example
This array contains one ScheduleListItem representing a completed schedule.
[
{
"Id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"ScheduleName": "MySchedule3",
"Type": "Once",
"ReportName": "Products/Products by Employee",
"LastExecDate": "2019-10-16 14:36:28",
"NextExecDate": "0001-01-01 00:00:00",
"Status": "Completed",
"RunCount": 1,
"UserId": "",
"CompanyId": ""
}
]
ScheduleRecurrence JSON
A JSON object representing a schedule recurrence pattern.
| Name | Type | Writable | Description |
|---|---|---|---|
| IsImmediate | boolean | yes (false) | Determines if the schedule will run immediately or not. If true the schedule runs immediately. Must be false in order to use the other recurrence properties. |
| RecurrenceType | enum | yes | RecurrenceType The type of recurrence to use. |
| RecurrenceRange | enum | yes | RecurrenceRange Determines when the schedule's recurrence pattern will end. |
| ScheduleTime | string | required | The time at which the schedule should run. Must be formatted in hh:mm format utilziing a 24-hour clock. (e.g. 9:00 AM = 09:00, 1:37 PM = 13:37) |
| RepeatEvery | boolean | yes (false) | If true, the schedule will repeat every RepeatEveryHours hours and RepeatEveryMinutes minutes until RepeatEveryEndTime. |
| RepeatEveryHours | integer | yes | If RepeatEvery is true, the schedule will run every this number of hours. |
| RepeatEveryMinutes | integer | yes | If RepeatEvery is true, the schedule will run every this number of minutes. |
| RepeatEveryEndTime | string | yes | If RepeatEvery is true, the schedule will stop repeating at this time. Must be formatted in hh:mm format utilziing a 24-hour clock. (e.g. 9:00 AM = 09:00, 1:37 PM = 13:37) |
| RangeStartDate | string | yes | The date on which the schedule will start recurring, in yyyy-mm-dd format. |
| RangeEndDate | string | yes | If RecurrenceRange is EndByDate, the schedule will stop recurring on this date, in yyyy-mm-dd format. |
| OccurrencesToEnd | integer | yes | If RecurrenceRange is EndAfterNOccurences, the schedule will stop recurring after this many occurences have run. |
| RecurrencePattern | ScheduleRecurrencePattern | yes | A JSON object representing the pattern that the recurrence should follow. |
Example
This example creates a ScheduleRecurrence object which runs every weekday from 9:00 AM to 5:00 PM every 1 hour. It will start doing this on 10/21/2019 and stop on 10/25/2019.
{
"IsImmediate": false,
"RecurrenceType": "Daily",
"ScheduleTime": "09:00",
"RepeatEvery": true,
"RepeatEveryHours": 1,
"RepeatEveryMinutes": 0,
"RepeatEveryEndTime": "05:00",
"RangeStartDate": "2019-10-21",
"RecurrenceRange": "EndByDate",
"RangeEndDate": "2019-10-25",
"RecurrencePattern": {
"Daily": {
"IsEveryWeekday": true,
"IsDailyEveryNDays": false
}
}
}
ScheduleRecurrencePattern JSON
A JSON object representing a schedule recurrence pattern. The pattern selected here should match the RecurrenceType set in ScheduleRecurrence.
ImportantPick one and only one of the properties.
| Name | Type | Writable | Description |
|---|---|---|---|
| Once | OncePattern | yes | A JSON object that represents a schedule that should run only once. |
| Daily | DailyPattern | yes | A JSON object that represents a schedule which will run on a daily basis. |
| Weekly | WeeklyPattern | yes | A JSON object that represents a schedule which will run on a weekly basis. |
| Monthly | MonthlyPattern | yes | A JSON object that represents a schedule which will run on a monthly basis. |
| Yearly | YearlyPattern | yes | A JSON object that represents a schedule which will run on a yearly basis. |
OncePattern JSON
A JSON object representing a schedule that does not recur, but runs only one time.
| Name | Type | Writable | Description |
|---|---|---|---|
| OnceDate | string | required | The date on which the schedule shall run, in yyyy-mm-dd format. |
DailyPattern JSON
A JSON object representing a schedule recurrence pattern which occurs on a day-to-day basis.
| Name | Type | Writable | Description |
|---|---|---|---|
| IsEveryWeekday | boolean | required | If true, the schedule runs every weekday, Monday through Friday. |
| IsDailyEveryNDays | boolean | required | If true, the schedule runs once a day, every DailyNumberOfDaysBetween days. |
| DailyNumberOfDaysBetween | integer | yes | If IsDailyEveryNDays is true, the schedule will run once a day with this number of days between cycles. |
Example
This Daily recurrence pattern runs every weekday.
{
"IsEveryWeekday": true,
"IsDailyEveryNDays": false
}
WeeklyPattern JSON
A JSON object representing a schedule recurrence pattern which occurs on a weekly basis.
| Name | Type | Writable | Description |
|---|---|---|---|
| WeeklyNumberOfWeeksBetween | integer | required | The schedule will run every this number of weeks. |
| WeeklyDaysOfWeek | array of boolean | required | The schedule will run only on the days contained in the array, with the first element of the array representing Sunday, the second element representing Monday, and so on. The array must contain exactly seven boolean values. Set the value to true to have the schedule run for that day, or false for it to skip that day. |
Example
In this example, the schedule will run every Sunday, Wednesday and Saturday of the week.
{
"WeeklyNumberOfWeeksBetween": "1",
"WeeklyDaysOfWeek": [
true,
false,
false,
true,
false,
false,
true
]
}
MonthlyPattern JSON
A JSON object representing a schedule recurrence pattern which occurs on a monthly basis.
| Name | Type | Writable | Description |
|---|---|---|---|
| IsOnSpecificDayOfMonth | boolean | yes | Determines whether a schedule will recur on a specific day of the month, or on a relative position in the month (e.g. third Monday of the month). Set to true for a specific day, or false for a relative day. |
| MonthlySpecificDayNumber | integer | yes | If IsOnSpecificDayOfMonth is true, this is the calendar day of the month that the schedule will recur. |
| MonthlySpecificEveryNMonths | integer | yes | If IsOnSpecificDayOfMonth is true, the monthly schedule will run every this number of months. |
| MonthlyDayPosition | string | yes | If IsOnpecificDayOfMonth is false, the monthly recurrence will run on a relative position in the month. One and only one of the following values are accepted: first, second, third, fourth, last. Works in combination with MonthlyDayOfWeek. |
| MonthlyDayOfWeek | string | yes | If IsOnSpecificDayOfMonth is false, the days on which the relative monthly recurrence occurs. One and only one of these values may be used: day, weekday, weekendday, sun, mon, tue, wed, thu, fri, sat. |
| MonthlyRelativeEveryNMonths | integer | yes | If IsOnSpecificDayOfMonth is false, the schedule will recur every this number of months. |
Example
In this example, the schedule will run on the second Monday of every other month.
{
"IsOnSpecificDayOfMonth" : false,
"MonthlyDayPosition" : "second",
"MonthlyDayOfWeek" : "mon",
"MonthlyRelativeEveryNMonths" : 2
}
YearlyPattern JSON
A JSON object which represents a yearly schedule recurrence pattern.
| Name | Type | Writable | Description |
|---|---|---|---|
| IsOnSpecificDayOfYear | boolean | required | If true, the yearly schedule will recur on a specific day of the year. Use YearlySpecificMonth and YearlySpecficDayNumber to set the date. If false, the schedule will recur on a relative part of the year. Use YearlyRelativeDayPosition, YearlyRelativeDayOfWeek, YearlyRelativeMonth to select the relative day of recurrence. |
| YearlySpecificMonth | string (January) | yes | If IsOnSpecificDayOfYear is true, this is the month portion of the date on which the schedule will recur. One and only one of these values may be used: January, February, March, April, May, June, July, August, September, October, November, December. Not case-sensitive. |
| YearlySpecficDayNumber | integer (1) | yes | If IsOnSpecificDayOfYear is true, this is the day portion of the date on which the schedule will recur. Any positive integer 1–31 is accepted. |
| YearlyRelativeDayPosition | string | yes | If IsOnSpecificDayOfYear is false, this is the relative week in the month that this schedule will recur. One and only one of the following values are accepted: first, second, third, fourth, last. Works in combination with YearlyRelativeDayOfWeek and YearlyRelativeMonth. |
| YearlyRelativeDayOfWeek | string | yes | If IsOnSpecificDayOfYear is false, this is the relative day of the week in the month that the schedule will recur. One and only one of these values may be used: day, weekday, weekendday, sun, mon, tue, wed, thu, fri, sat. |
| YearlyRelativeMonth | string | yes | If IsOnSpecificDayOfYear is false, this is the number of the month in the year that the schedule will recur. (e.g. "1" for January, "6" for June, "12" for December) |
Examples
This example will run the schedule every year on the last Sunday in September.
{
"IsOnSpecificDayOfYear": false,
"YearlyRelativeDayPosition": "last",
"YearlyRelativeDayOfWeek": "sun",
"YearlyRelativeMonth": "9"
}
This example will run the schedule on April 15th of every year.
{
"IsOnSpecificDayOfYear": true,
"YearlySpecificMonth" : "April",
"YearlySpecficDayNumber" : 15
}
ScheduleFilter JSON
A JSON object representing filters applied to a report.
| Name | Type | Writable | Description |
|---|---|---|---|
| FilterText | string | yes | The field to be filtered, which can include applied formulas. This field must be one of the fields on the scheduled report. |
| Operator | enum | yes | ScheduleFilterOperator The filter operator. |
| AndFlag | boolean | yes | If true, this filter will be logically ANDed with the next filter in the array. If false, this filter will be logically ORed with the next filter in the array. |
| Values | array of number, string or boolean | yes | The values to filter by. When using Operator.Between or Operator.NotBetween the array must contain exactly two values. When using Operator.OneOf or Operator.NotOneOf the array may contain any number of values. All other operators use only one value, which must still be in an array. Date and DateTimes must be represented as strings in yyyy-mm-dd format. |
Filters may be grouped by nesting additional arrays into the Filters array. Consider the following example:
((C.CID = 1 AND C.CID = 2) OR C.CID = 3) OR C.CID = 4
[
[
[
{"FilterText": "C.CID", "Operator": "EqualTo", "AndFlag": true, "Values": [1]},
{"FilterText": "C.CID", "Operator": "EqualTo", "AndFlag": false, "Values": [2]}
],
{"FilterText": "C.CID", "Operator": "EqualTo", "AndFlag": false, "Values": [3]}
],
{"FilterText": "C.CID", "Operator": "EqualTo", "AndFlag": true, "Values": [4]}
]
Example
This filter selects rows whose ProductName is either "Alice Mutton" or "Boston Crab Meat".
[
{
"FilterText": "Products.ProductName",
"Operator": "EqualTo",
"AndFlag": false,
"Values": [
"Alice Mutton"
]
},
{
"FilterText": "Products.ProductName",
"Operator": "EqualTo",
"AndFlag": true,
"Values": [
"Boston Crab Meat"
]
}
]
List All Filters
GET /schedules/{scheduleID}/filters
List all the filters on the schedule specified by scheduleID. Returns an array of ScheduleFilter.
Edit Filters
PATCH /schedules/{scheduleID}/filters
Edit properties of the filters on the schedule specified by scheduleID by sending an array of ScheudleFilter objects to apply to the schedule. Payload must be in an array.
TipUse
GET /schedules/{scheduleID}/filtersto get the the current list of filters first, make updates to the filters and send the entire array back.
ScheduleParameter JSON
A JSON object representing a prompting parameter on the scheduled report.
| Name | Type | Writable | Description |
|---|---|---|---|
| Id | string | required | The Id of the parameter on the scheduled report. To update the parameter's value, the parameter with this Id must appear on the report being scheduled and must be prompting. |
| Value | integer, string or date | yes | The value to set the parameter to, which is the same as setting the value of a prompting parameter when running a report. It does not change the underlying default parameter value. |
List All Parameters
GET /schedules/{scheduleID}/parameters
List all of the prompting parameters on the report in the schedule specified by scheduleID. Returns an array of ScheduleParameter objects.
Example
[
{
"Id": "DoNotPrompt",
"Value": "1"
},
{
"Id": "Market",
"Value": "Boston"
}
]
Edit Parameters
PATCH /schedules/{scheduleID}/parameters
Edit values of the parameters on the schedule specified by scheduleID. Payload must be in an array. Returns no JSON objects but will return HTTP status code 204 to indicate success.
Example
[
{
"Id": "Market",
"Value": "Black"
}
]
TipUse
GET /schedule/{scheduleID}/parametersto get the list of parameters first, make updates to the parameters and then send the entire array back.
ScheduleBatchInfo JSON
A JSON object representing the information for processing individualized scheduled reports, also known as a batch report. The individualized reports will be e-mailed to recipients based on a Data Object field contained within BatchEmailEntityCategory > BatchEmailEntity > BatchEmailField. A summary of the batch report's execution will be sent by e-mail to ToAddresses and CC'ed to CcAddresses.
More information about Batch E-Mailing can be found in the article on Scheduling Reports.
| Name | Type | Writable | Description |
|---|---|---|---|
| AttachReportToEmail | boolean (false) | yes | If true, the report output will be attached to the individualized e-mail messages. |
| ToAddresses | array of string | yes | An array of e-mail addresses to send the batch report results summary to. |
| CcAddresses | array of string | yes | An array of e-mail addresses to carbon copy e-mail the batch report results summary to. |
| BatchEmailEntityCategory | string | yes | The Category that BatchEmailEntity belongs to. The category must exist in Exago. |
| BatchEmailEntity | string | yes | The Exago entity containing the batch recipient information. The entity must exist as a Data Object. |
| BatchEmailField | string | yes | The field which contains the e-mail address of each recipient of the individualized batched report. |
Example
This example sends a copy of the schedule's execution summary to theboss@mycompany.com, and sends the individualized executed report to each entry with an EmailAddress in the Employees data object.
{
"AttachReportToEmail": true,
"ToAddresses": [
"theboss@mycompany.com"
],
"CcAddresses": [],
"BatchEmailEntityCategory": "",
"BatchEmailEntity": "Employees",
"BatchEmailField": "EmailAddress"
}
ScheduleRecipientInfo JSON
A JSON object representing an e-mail to send when the schedule has run and to optionally attach the report to the e-mail.
| Name | Type | Writable | Description |
|---|---|---|---|
| EmailResults | boolean (false) | required | If true, an e-mail will be sent when this schedule cycle has finished running including a summary of the execution. If false, all further properties will be ignored. |
| AttachOutputToEmail | boolean (true) | yes | If true, the report's output will be attached to the e-mail message. |
| ToAddresses | array of string | required | An array of e-mail addresses to send the e-mail to. |
| CcAddresses | array of string | yes | An array of e-mail addresses to CC to. |
| BccAddresses | array of string | yes | An array of e-mail addresses to BCC to. |
| ReplyToAddresses | array of string | yes | An array of e-mail addresses that will appear as the Reply-To: addresses in the e-mail. |
| EmailSubject | string | yes | The subject line of the e-mail message. |
| EmailBody | string | yes | The body text/content of the e-mail message. |
Example
This example attaches the report output file to an e-mail and sends it to firstperson@mycompany.com and secondperson@mycompany.com. The e-mail is CCed to supervisor@mycompany.com and manager@mycompany.com, and BCCed to ceo@mycompany.com. All e-mail messages will have a subject line of "Here is the report you needed" and the message "Attached is the report you had asked for!" will appear in the body of the e-mail.
{
"EmailResults": true,
"AttachOutputToEmail": true,
"ToAddresses": [
"firstperson@mycompany.com",
"secondperson@mycompany.com"
],
"CcAddresses": [
"supervisor@mycompany.com",
"manager@mycompany.com"
],
"BccAddresses": [
"ceo@mycompany.com"
],
"ReplyToAddresses": [],
"EmailSubject": "Here is that report you needed",
"EmailBody": "Attached is the report you had asked for!"
}