Skip to content

from orchestrator import begin

4.7 Upgrade Guide

In this document we describe important changes to be aware of when upgrading from orchestrator-core v4.x to v4.7.

If you are not yet using v4.x, please consult the 4.0 upgrade guide.

About 4.7

This release introduces a deprecation and a breaking change to a beta feature:

  1. Scheduling tasks via decorator is deprecated in favor of using the API
  2. Workflow authorization callbacks (Beta) change from def to async def

Scheduling tasks via decorator is deprecated in favor of using the API

In v4.4.0 we introduced the apscheduler library with a persistent jobstore. The decorator @scheduler.scheduled_job(...) allowed to schedule tasks from code.

In v4.7.0 this has evolved to scheduling tasks via the Scheduler API. Since tasks scheduled from code cannot be related to their task definition in the DB, they cannot be managed through the API. Therefore, using the decorator to schedule tasks is deprecated. This release contains a DB migration which ensures you can update from any v4.x version to v4.7.0.

Please check which of the 3 scenarios applies for you and which action is required.

1. I use the scheduler with only the default schedules

Short answer

If you want to keep using the default schedules, run python main.py scheduler load-initial-schedule from the CLI where you normally run your scheduler.

Otherwise, no action is required.

Long answer

As of v4.6.5, the default core schedules that are scheduled with the decorator were:

In v4.7.0 the only remaining schedule is validate-products. (this will be removed in #1250)

The other 3 schedules have been removed. When you upgrade from anywhere between v4.4.0 - v4.6.x then the DB will still contain the scheduled jobs. You can remove them from the apscheduler_jobs table manually, or simply wait for the scheduler to clean them up, which will produce these 3 messages:

[error    ] Unable to restore job "resume-workflows" -- removing it [apscheduler.jobstores.default]
[error    ] Unable to restore job "clean-tasks" -- removing it [apscheduler.jobstores.default]
[error    ] Unable to restore job "subscriptions-validator" -- removing it [apscheduler.jobstores.default]

If you upgrade from an older v4.x version, this does not apply.

If you want to recreate these 3 schedules by using the API, we have provided a command to do so:

python main.py scheduler load-initial-schedule

You can also choose to only schedule a specific task, or change when they run. For now this can only be done through the API; in the future this will be possible from the UI. (orchestrator-ui-library#2215)

For more information: Scheduler API.

2. I use the scheduler with both the default schedules AND my own schedules

Short answer

Check the actions for scenario 1.

No further action is required as your own schedules will continue to work.

Long answer

Please check scenario 1 regarding the default schedules.

For your own schedules, you may remove their definitions in code and schedule them using the [Schedule API]. However, this is not yet a requirement as the decorator-scheduled jobs can be used alongside API-scheduled jobs. This will only be a requirement for orchestrator-core v5.0.0.

You can determine how jobs have been scheduled by running the show-schedule CLI command and inspecting the source column. For example, an excerpt of the SURF schedule:

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
┃ id                                   ┃ name                      ┃ source    ┃ next run time             ┃ trigger           ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
│ 6db5c270-8239-455c-97e4-14a6a865c68d │ Task Resume Workflows     │ API       │ 2025-12-11 11:07:42+00:00 │ interval[1:00:00] │
│ import-crm-to-ims                    │ Import CRM data to IMS    │ decorator │ 2025-12-11 12:00:00+00:00 │ cron              │
│ 70c0b5ce-88f5-48fb-ba5f-d19422628bef │ Task Clean Up Tasks       │ API       │ 2025-12-11 16:07:42+00:00 │ interval[6:00:00] │
│ import-customers-from-crm            │ Import customers from CRM │ decorator │ 2025-12-11 19:00:00+00:00 │ cron              │

3. I do not use the scheduler

No action required!

Workflow authorization callbacks change from def to async def

In v4.7.0 the workflow authorization callbacks change from synchronous to asynchronous. This was done for consistency with API authorization callback functions which are also async. Additionally, it is always possible to run a sync function in an async context, but the other way around is much harder.

While this is a breaking change, we decided to add it in this minor release since workflow authorization is currently still a beta feature.

Example

Given a synchronous callback, like this:

from oauth2_lib.fastapi import OIDCUserModel
from orchestrator.workflow import workflow, StepList, begin

def authorize_workflow_access(user: OIDCUserModel) -> bool:
    ...

@workflow("My workflow", authorize_callback=authorize_workflow_access)
def my_workflow() -> StepList:
    return begin >> ...

The required change is to make the callback look like this:

async def authorize_workflow_access(user: OIDCUserModel) -> bool:
    ...

Info

Important: check your callback for synchronous I/O calls. These block the eventloop, which has a negative impact on performance of the API.

For example, if your callback performs a requests.get() call or a sqlalchemy query, this will block the eventloop. You can resolve this either using an asynchronous alternative that can be awaited, or by using to_thread to run the synchronous call in a thread. Running in a thread is not as optimal as truly async code, but it's still a lot better than blocking the loop.

For more information see Workflow authorization callbacks.