Description
Schedule a service to run later, or submit a service for asynchronous execution.
The time at which the service should run can be specified by timestamp or by a period from now.
Each scheduled service may be associated with a node, called the schedule node. This is used to:
- Prevent duplicate entries in the schedule.
- Record errors.
- Provide a durable schedule identity for cancel and query.
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 normally stored as persistent schedule request nodes and run in the background by the RunScheduledServices service.
A request may also have an identity node. The identity node gives a queued-job identity for deduplication, but does not by itself make the request persistent and is not used as a blocking scope. It cannot be used with a schedule node.
For short-running work, the caller may set persistent to false. If the request does not require persistence, and if the requested delay is short enough for the local asynchronous scheduler, Schedule Service may submit the request directly to the local AsyncScheduler instead of storing a persistent schedule request. This is not a durable request. It will not survive a restart.
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 scheduled service will not be run.
For schedules without nodes, the delay must not exceed the value in the configuration parameter maximumDelay, which defaults to 864,000 (i.e. 10 days). For schedules with nodes, the equivalent parameter is maximumDelayNodes, which defaults to maximumDelay.
Input
<ScheduleService>
<userLogonReference>userid</userLogonReference>
<password>password</password>
<action>schedule|cancel|query</action>
<protected>false|true</protected>
<nodeIdentifierSchedule/>
<nodeVersionReferenceSchedule/>
<nodeVersionReferenceIdentity/>
<nodeVersionReferenceBlock/>
<blocking>true|false</blocking>
<scheduleTimestamp></scheduleTimestamp>
<delay>delay period in seconds</delay>
<persistent>true|false</persistent>
<priority>low|normal|high</priority>
<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 protected parameter will be passed on to the service.
cancel and query both require that a schedule node is passed.
The schedule node can be specified by identifier or reference. If both are passed, identifier takes precedence. The user must have execute authority over the node. The schedule node cannot be used with an identity 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.
Use nodeVersionReferenceIdentity to identify a request for queued-job deduplication. If a request with the same identity is already queued, a later request with that identity is ignored. The identity node does not by itself make the request persistent, and it is not a blocking scope. The user must have execute authority over the identity node. An identity node cannot be used with a schedule node.
Use nodeVersionReferenceBlock to identify a node that defines the scope of blocking/serialisation. Blocking is hierarchical. If a request blocked on node A.B is running, then a request blocked on A will not be started, and neither will one on A.B.C. The user must have execute authority over the block node.
Use blocking to say whether Schedule Service should apply a blocking key. The default is true. If blocking is true and nodeVersionReferenceBlock is supplied, that node is used as the blocking scope. If blocking is true and no block node is supplied, Schedule Service uses the caller's user node as the default blocking scope. This will often have the effect of serialising background work for an account, because scheduled background work is commonly run by the account holder. However, the blocking key is the caller's user node, not the account node. If blocking is false, no blocking key is added, and nodeVersionReferenceBlock must not be supplied.
The schedule node also serialises work for that schedule identity, but it is not used as a hierarchical blocking node. To request hierarchical blocking, supply nodeVersionReferenceBlock.
A block node does not by itself make a request persistent. For a non-persistent request, the block is a local in-memory scheduler block on the server that accepted the request. If the caller needs durable or background blocking, it should allow the request to be persistent.
Use persistent to indicate whether the request should be persisted. The default is true. Set it to false for actions that need not survive a restart, such as short UI requests. Short-running requests should also normally set blocking to false, or provide a more precise block node, if they should not wait behind long-running work for the same user. This is a request to avoid persistence, not an absolute guarantee. Schedule Service may still persist the request, for example if a schedule node is supplied, if the requested delay is too long for the local in-memory scheduler, or if the local scheduler cannot accept the request. If a request with an identity node is persisted, the identity node is stored with the persistent request and used when it is later submitted to the scheduler.
Use priority to express a scheduling preference. The supported values are low, normal and high. The default is normal. Current scheduler policy treats low as a lower priority service execution class, and treats normal and high as normal service priority.
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.