Description
Schedule a service to run later.
The time at which the service should run can be specified by timestamp or a period.
Each scheduled service may be associated with a node, called the schedule node. This is used to:
- Prevents duplicate entries in the schedule.
- Record errors.
If Schedule Service is called twice with the same schedule node before the first service has run, then:
- If the new service is scheduled to run at the same time or after the existing scheduled service, it is ignored.
- If the new service is scheduled to run before the existing scheduled service, it replaces the existing scheduled service.
Scheduled services are run in the background by the RunScheduledServices service.
If the service ends in an error, the derived Error (system.NODE_ERROR) members of the schedule node will be set. If there is no error, the members will not be reset. Further services may not be scheduled with the same node until the error is cleared, though this behaviour should not be relied upon. The error can be cleared by re-derivation of the node.
The service may monitor use of the schedule, and reject service calls that it believes may be problematic (e.g. because they have in the past been long running or cause errors).
If the schedule node is deleted before the scheduled service is run, the schedule service will not be run.
The configuration parameter maximumDelay can be used to set a maximum delay for a service request. It defaults to 10 x 24 x 3600, i.e. 10 days.
Input
<ScheduleService>
<userLogonReference>userid</userLogonReference>
<password>password</password> <action>schedule|cancel|query</action> <nodeIdentifierSchedule/> <nodeVersionReferenceSchedule/> <scheduleTimestamp></scheduleTimestamp> <delay>delay period in seconds</delay> <service> <AnyServiceGoesHere/> </service> </ScheduleService>
The action parameter is one of:
- schedule - schedule the service to run
- cancel - cancel a scheduled service
- query - find out when the service is scheduled to run
The default is schedule.
The schedule node can be specified by identifier or reference. If both are passed, identifier takes precedence. The user must have admin authority over the node.
Schedule
The time at which the service should be run can be specified as a timestamp in format yyyy-mm-ddThh:mm:ss.sss, or as a delay from now in seconds. If both are passed, the delay is added to the timestamp. If neither are passed the service is scheduled to run as soon as possible.
The scheduled timestamp must be within a number of days from now defined by the configuration parameter maximumDelay (typically set to 10 days from now).
A single service is passed in the service element. This will be run with the same credentials as the schedule service run, and should not itself contain any credentials.
Cancel
If the action is cancel, any scheduled service for the node will be cancelled. If no service is scheduled, then schedule service does nothing.
Query
If the action is query, the service will return the schedule timestamp of any scheduled service, if there is one. If there is not one, it will not return a timestamp.
Output
<ScheduleService>
<errorNumber>0</errorNumber> <scheduleTimestamp></scheduleTimestamp>
</ScheduleService>
Schedule timestamp is returned after action of schedule if the service has been scheduled, or after action of query if a scheduled service is found.
After an action of schedule, if the error number is 0 but no scheduleTimestamp is returned, this means that the schedule request has been rejected because there is already a scheduled request associated with the schedule node.
Errors
101 - Not authorised
102 - Not found (i.e. schedule node not found)
103 - Parameter error
106 - Rejected due to existing errors
110 - Temporary error (unable to accept more scheduled jobs)
The service may return 106 either because the schedule node already has an error set, or because ScheduleService detects that the user or schedule node are problematic (e.g. running too often or having too many long-running tasks). This behaviour should not be relied upon.