Manually run a job to evaluate pre-existing schedules

Using a service that can evaluate records against the Rule service’s core rules.

Overview

The Rules service only evaluates work records that are created or edited after the point at which the service is turned on in an environment. Records created before that point will not be automatically evaluated so the evaluation process needs to be triggered manually for time periods preceding the Rules service being introduced.

Automatically evaluating all records in environments with high volumes of data, which is typically the case in most customer environments, can create significant system load and likely impact the overall performance and stability of the Rules service and Skedulo’s back-end systems more generally. For this reason, we have developed a service to be used when needed to trigger the evaluation of existing records. Periods of up to six months at a time can be submitted for evaluation per environment. The Rules service then evaluates all records within that period against the core rules and generates any applicable conflicts.

Examples of when the service can be used

  1. When existing customers start using the new rule conflict management feature: The Rules service won’t automatically evaluate any already existing records. As most of our customers schedule in advance, this can be used to trigger the evaluation of all core rules that have been enabled against all existing records.

  2. When turning on a core rule that was previously turned off and wanting to evaluate if that rule has been broken by any of the existing records.

Key information about the service

  • This service works for all core rules.

  • This is an async process that runs in the background.

  • A customer can submit a period of up to six months. If you need to process more than six months, subsequent requests can be made. Note that only one request per environment can be queued at a time, so you will need to wait for the request to complete before submitting a request for the next period.

  • There’s no user interface for this service. It requires someone with developer experience and knowledge to use it.

  • Rules service generally processes from the current date/time forward - so the processing of these requests is via a separate pathway to the Rule service’s normal processing and shouldn’t impact the responsiveness for day-to-day scheduling.

  • Time periods before the current time are not supported. The service evaluates work item records that were created in the past, but are scheduled for the future. As a result, only time periods in the future can be submitted to the service.

Run the service to evaluate records

The examples of requests to send to the API and the response you can expect are documented below.

Example 1: Evaluate all rules rules from midnight 1st January 2024 to midnight 31st January 2024 (30 days)

Request

curl --request POST \
  --url https://api.skedulo.com/asyncJobs/evaluateViolations \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
	"startTime": "2024-01-01T00:00:00.000Z",
	"endTime": "2024-01-31T00:00:00.000Z",
	"ruleIds": {
		"include": "all"
  }
}'

Response

{
	"result": {
		"jobId": "27a8f4b8-59eb-4340-aab9-827ca60434e5"
	}
}

Example 2: Evaluate past records - from midnight 1st June 2024 to midnight 11th June 2024 (10 days) - for only the ‘workOverlap’, ‘jobOverallocated’, and ‘missingJobTags’ rules

Request

curl --request POST \
  --url https://api.skedulo.com/asyncJobs/evaluateViolations \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
	"startTime": "2024-06-01T00:00:00.000Z",
	"endTime": "2024-06-11T00:00:00.000Z",
	"ruleIds": {
		"include": "only",
		"ids": [
			"workOverlap", "jobOverallocated", "missingJobTags"
		]
  }
}'

Response

{
	"result": {
		"jobId": "7f09ffa0-82f3-4dec-804a-00462f1fd4ec"
	}
}

Query the status of a request

The API to query the status of an evaluate violations job is documented here with an example request and response.

To query the state of an async job, it is necessary to capture the async job ID returned when initiating the async job to evaluate violations.

Example of a status query

Request

curl --request GET \
  --url https://api.skedulo.com/asyncJobs/7f09ffa0-82f3-4dec-804a-00462f1fd4ec \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json'

Response

{
	"result": {
		"jobId": "7f09ffa0-82f3-4dec-804a-00462f1fd4ec",
		"type": "BatchEvaluateViolations",
		"status": "Completed",
		"createdBy": "000137ad-89f7-4c1c-9981-f6c7710d0b85",
		"createdTime": "2023-07-17T00:22:46.359Z",
		"inProgressTime": "2023-07-17T00:22:46.456Z",
		"completedTime": "2023-07-17T00:22:47.613Z",
		"parameters": {
			"startTime": "2024-06-01T00:00:00.000Z",
			"endTime": "2024-06-11T00:00:00.000Z",
			"ruleIds": {
				"ids": [
					"missingJobTags",
					"workOverlap",
					"jobOverallocated"
				],
				"include": "only"
			},
			"type": "BatchEvaluateViolations"
		},
		"tasks": {
			"total": 30,
			"queued": 0,
			"inProgress": 0,
			"success": 30,
			"failure": 0
		}
	}
}