Placeholders

Placeholders let you pass context from your own application into a Scheduling Request, so that it can be inserted into the event’s content — for example the job title, the interview stage, or a link back to a page in your product.

Cronofy provides a set of placeholders out-of-the-box, such as the host’s name and the invitee’s first name — the values a Scheduling Request can “know” about itself. This page covers the additional placeholders you can supply yourself, by setting them on the Embedded Scheduler element.

Once enabled, your placeholders are presented to the coordinator in the Scheduler UI to insert into the event description, and can be used in Templates to eliminate manual work entirely.

Setting placeholders on the element #

Alongside the standard Embedded Scheduler options, supply each placeholder as an attribute on the cronofy-scheduler-button element. Every placeholder attribute shares a common prefix — metadata-evenitron- in the examples below:

<cronofy-scheduler-button
  id="my-scheduler-button"
  embed-token="{EMBED_TOKEN}"
  correlation-id="event-1234"
  recipient-email="doc@evenitron.com"
  recipient-name="Dr Emmet Brown"
  recipient-organization-name="Evenitron"
  event-duration-minutes="45"
  metadata-evenitron-job_title="Product Manager"
  metadata-evenitron-interview_stage="Phone Screen"
  metadata-evenitron-candidate_portal_url="https://ats.evenitron.com/candidates/1234"
></cronofy-scheduler-button>

Each attribute after the prefix names one of your enabled placeholders. Values are sent as strings of up to 256 characters. Any attribute that isn’t one of your enabled placeholders is ignored.

Using placeholders in event content #

Reference a placeholder in event content by its name. For example, metadata-evenitron-job_title becomes {{ evenitron.job_title }}:

• From: {{ evenitron.job_title }} interview ({{ evenitron.interview_stage }})
• To: Product Manager interview (Phone Screen)

Placeholder values are commonly used within the description of an event to provide context and links to both the candidate and the interviewers.

Handling invalid placeholders #

Alongside the standard UI state events, the cronofy-scheduler-button emits a cronofyschedulerwarning event when a Scheduling Request is created with metadata that could not be used — for example a placeholder that has not been enabled for your application. The unused metadata is not written to the Scheduling Request.

document
  .getElementById("my-scheduler-button")
  .addEventListener("cronofyschedulerwarning", function(event) {
    console.log("Cronofy Scheduler warning", event.detail);
  });

The event’s detail describes the metadata that was ignored:

{
  "message": "Some metadata fields were invalid and were ignored",
  "invalidMetadata": {
    "evenitron": {
      "unknown_key": {
        "data_type": "string",
        "value": "..."
      }
    }
  }
}

The same invalidMetadata detail is also included on the cronofyschedulerrequestcreated event when metadata was ignored, so a single listener can reconcile the request and any ignored values together.