Scheduler Workflows ^BETA

Scheduler Workflows allow you to integrate the Scheduler into your business workflows and applications.

Using Workflows, you can:

Control the recipient’s experience by redirecting them back to your application after they’ve interacted with a Scheduler link
Capture metadata and store it on the Request, so that you can correlate Scheduling Requests with items in your own systems
Configure push notifications to be sent back to your application at various stages in the scheduling flow

Capturing metadata #

Scheduler links accept query string arguments for metadata parameters. The values provided are stored against the Request when a time slot is selected, and are then passed back to your application in later callback notifications or redirects.

The following allow list of parameters is currently accepted. Each is treated as an opaque string, with a length limit of 128 characters.

correlation_id - This is intended to be set to a meaningful value in your system. For example a Candidate ID in an Applicant Tracking System.
utm_source
utm_medium
utm_campaign
utm_term
utm_content

For example, given a Scheduling Request with the URL https://app.cronofy.com/rts/FIDaAWS5, you may pass metadata by sending your recipient the following link:

https://app.cronofy.com/rts/FIDaAWS5?correlation_id=CASE-66

This also works with Public Links:

https://app.cronofy.com/pls/Q5-ZDPM8?utm_source=outreach_campaign&utm_medium=email

Receiving callback notifications #

To receive callbacks, you must set up a Cronofy Internal Developer Application within the Organizational Unit you’re creating Scheduling Requests for.

Once you’ve done this, you should configure a Universal Push Notification URL for that application. Workflows can then be configured to send callbacks to that URL.

Creating the Application #

Navigate to Developer, then Create New App. If you don’t see the Developer navigation item, enable Show the Developer Dashboard under your Cronofy profile page.
If you have multiple Organizational Units, the Application should be created within the same Organizational Unit as your Scheduling Requests are created and your Scheduler Workflows will be configured.
Ensure the Internal Only Application setting is checked

Configuring your Push Notification URL #

Under your application in the navigation menu, choose Notifications. On this page you can configure your Application’s Universal Push Notification URL where all Scheduler Workflow callback notifications will be sent.

Configuring a Workflow #

Scheduler Workflows can be created within your Organizational Unit on the Cronofy dashboard.

They have some essential properties:

Enabling a Workflow #

Workflows can be enabled or disabled. When a Workflow is disabled, none of its configured actions will take effect.

Matching Scheduling Rules #

Workflows are active for any Scheduling Requests made for the selected Organizational Unit Scheduling Rules. This includes both ad-hoc Requests, as well as bookings made via Public Links for those Scheduling Rules.

Steps and Actions #

A Workflow has Actions which take effect at various Steps during the Scheduling process.

The possible Steps are as follows:

When an initial time slot is selected via the link
When a Request is rescheduled by the recipient via the link
When a Request is declined by the recipient via the link
When the recipient visits a link, but there were no slots available
When the recipient requests more times
When a scheduled event starts
When a scheduled event ends

There are two types of Action which can be applied to these Steps

Redirecting the recipient
Callback notifications

Redirects #

Redirects are available for all of the Steps which are a direct interaction with the Scheduling Request link. That is, all of the above Steps except when the scheduled event starts or ends.

When a Redirect action is present on a Workflow, we’ll send the recipient to the desired URL at the appropriate point in time. For example, if you configure a Workflow to redirect the user when they’ve selected their initial time slot, we’ll do that immediately after they’ve confirmed their choice.

The destination URL will have query string parameters added:

scheduling_request_id, matching the same ID that would appear for the request in a Callback Notification Payload
If the Scheduling Request has Metadata from the above list present, we’ll add those parameters as query string values on to the URL you provide.

For example, when specifying a Redirect URL of:

https://example.com/handle_time_chosen

A redirect after the time is selected might look like:

https://example.com/handle_time_chosen?scheduling_request_id=srq_52b65401a5d87bb4f0bee44e&correlation_id=your-value

Callback notifications #

Callback notifications are available for all Step types. When configuring a Callback Action, you’ll have to choose an Application to deliver the notification to. We’ll send a notification to the configured Universal Push Notification URL for that Application.

Your Application should respond quickly with a 2XX successful status. If it does not, we will retry the notification periodically until it succeeds or fails 10 times consecutively.

Callback example #

POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

{
  "notification": {
    "type": "scheduling_request_time_chosen"
  },
  "user": {
    "tzid": "Europe/Paris"
  },
  "scheduling_request": {
    "scheduling_request_id":"srq_80f7fece4f37897d62d86d80",
    "slot_selection": "complete",
    "primary_select_url":"https://app.cronofy.com/rts/LOiwlKXQ",
    "dashboard_url": "https://app.cronofy.com/scheduler/80f7fece4f37897d62d86d80",
    "recipient_operations": {
      "view_url": "https://app.cronofy.com/rts/LOiwlKXQ",
      "reschedule_url": "https://app.cronofy.com/rts/LOiwlKXQ?reschedule=true",
      "decline_url": "https://app.cronofy.com/rts/LOiwlKXQ?decline=true"
    },
    "summary": "Product Manager Interview at Globex",
    "duration": { "minutes": 30 },
    "recipients": [
      {
        "email":"eb@example.com",
        "display_name":"Dr Emmet Brown",
        "select_url":"https://app.cronofy.com/rts/1234abc",
        "slot_selector": true
      },
      {
        "email":"bob@evenitron.com",
        "display_name":"Bob Visser",
        "slot_selector": false
      }
    ],
    "collaborators": [
      { "sub": "acc_7fad963a87459cefb4010b71" }
    ],
    "event": {
      "host": {
        "email": "ihost@evenitron.com",
        "display_name": "Ian Host",
        "sub": "acc_962bfe62001ed91c7e906242"
      },
      "attendees": [
        {
          "email": "ebrown@example.com",
          "display_name": "Dr Emmet Brown"
        },
        {
          "email": "bob@evenitron.com",
          "display_name": "Bob Visser"
        },
        {
          "email": "alice@hiring.evenitron.com",
          "display_name": "Alice McHiring",
          "sub": "acc_7fad963a87459cefb4010b71"
        }
      ],
      "start": {
        "time": "2024-04-19T14:00:00+0100",
        "tzid": "Europe/London"
      },
      "end": {
        "time": "2024-04-19T14:30:00+0100",
        "tzid": "Europe/London"
      },
      "summary":"Product Manager Interview at Globex",
      "metadata": {
        "scheduler": {
          "correlation_id": "foobar",
          "utm_medium": "email",
          "utm_source": "automated_email_workflow",
          "utm_campaign": "candidate_interview_offer_email",
          "captured_data.phone_number": "0118999881999119725 3",
          "captured_data.notes": "No dietary requirements."
        }
      }
    }
  }
}

Notification types:

scheduling_request_time_chosen - When an initial time slot is selected via the link
scheduling_request_rescheduled - When a Request is rescheduled by the recipient via the link
scheduling_request_declined - When a Request is declined by the recipient via the link
scheduling_request_no_times_available - When the recipient visits a link, but there were no slots available
scheduling_request_more_times_requested - When the recipient requests more times
event_start - When a scheduled event starts
event_end - When a scheduled event ends

Note:

recipient_operations will only contain URLs for actions that are available for the Scheduling Request in its current state.

Event-based notifications #

You can configure a callback tied to the start or end time of the scheduled event. This fires when the event in your calendar actually takes place, and is kept in sync with any external changes that might occur.

For example, if the recipient originally chooses 11AM, but then the event is moved in the organizer’s calendar afterwards to 2PM, we’ll send a notification at the new time of 2PM.

We’ll send such notifications within a delivery window of one minute either side of the scheduled time.

Scheduler Workflows BETA