Workplace Shift API (Beta)

Create, read, update and delete shifts and shift covers on Workplace via the Graph API.

Overview

Concepts

This guide assumes familiarity with the general usage patterns of the Workplace Graph API.

The Shift API adds new graph objects to support the creation and maintenance of shift-related information which is presented in the Workplace product. These objects include:

• Company Member: used to lookup person based on external ID.
• Group: a team or squad shares their shifts via a Workplace group used for team communication.
• Group Shift Settings: used to configure shift features at a group level.
• Retrieve shift settings from a group.
• Shift: A single shift attached to the shift settings
• Shift Cover: Optional collection of shift covers for a particular shift.

Conventions

Below are a set of working assumptions regarding the conventions for encoding and validity of different parts of the API:

1. Timestamps values (date time timestamp) are handled as UTC offset epoch milliseconds. The exact sub-second millisecond values may be quantised when returned in API responses.
2. Shifts should typically be created in the ‘future’ relative to the current epoch time.
3. Wherever possible, the API will return error messages indicating errors, so on non-2XX responses please consult the API error messages for developer feedback. These are intended for the developer and should not be surfaced to regular users.
4. Rules for the product (e.g. only members of a group may have a shift published to that group) also apply to shifts and covers created via the API.

Pre-requisites

In order to make calls to the Shift API, it is necessary to use a Workplace app. The Shift API is available to both third-party apps and custom integrations.

Please see the relevant documentation for information on how to set these up:

• Custom Integrations
• Third Party Apps

Permissions

The permission required to make calls to the Shift API is manage_shifts, in addition to any other permissions required by your integration.

Core Flows

Once an instance administrator has enabled an integration with a shift management tool (and that integration holds a valid access token) the shift management tool can use it’s access token to perform shift schedule linking actions to associate a specific external schedule with a team’s scheduling group.

Account Linking

In order to publish an external shift schedule on Workplace, it is necessary to identify which group the Shift Manager would like to publish the group to. The actual mechanism and implementation on the third party platform will be app specific. The below documentation describes the anticipated flow.

Fetch the Member ID for the external user ID

In order to be able to resolve the group a Shift Manager based on the external user identifier.

GET /community/members?external_ids=12356,abc123

All further calls will use the returned member Work User ID.

Fetch the list of groups where shift features are enabled

The expected flow for integration is that the Shift Manager would enable shift management in the group settings they expected to share an external schedule to.

GET /community/groups
  fields=...&shift_feature_setting=ANY_SHIFT_FEATURES

In the general case there will only be a single group which the member has enabled shift related features for. In the case of a single group with shift features enabled in that group, the group ID should then be stored on the third party platform. As a convenience the shift settings support setting an external identifier to allow the group to be easily located once it is selected.

Create / enable shift features on a group

In order to configure shift settings for a group, it is necessary to create the shift settings associated with a group along with the feature selection.

POST /{group_id}/shift_settings?
  external_id=acme:12345&
  shift_feature_setting=ALL_FEATURES_ON

Fetch the group settings for a group

GET /{group-id}?
  fields=shift_settings{shift_feature_setting,external_id}

Given the group for which the Shift Manager has identified they would like to publish shifts, the settings node can be used to store an external identifier, as well as update the enabled shift features for a group.

Update shift settings external ID and Shift Features

In this example we are updating the shift settings object associated with a group and settings the shift features to be shift viewer only (not shift cover).

POST /{shift-settings-id}?
  external_id=acme:12345&
  shift_feature_setting=SHIFT_VIEWER_ONLY

Note that the external ID field is a freeform string field. In the situation where multiple Shift Management Tool integrations are present on the same instance this field may be set on a group by group basis.

Shifts in a Group

This API exposes shifts and shift covers in the context of a group on Workplace. A group represents the squad or team for which a shift schedule would typically be published. Once a schedule or roster is published on the Shift Management Tool, it then needs to be created on Workplace. Once created, it is important for the client integration to maintain the accuracy of the data on Workplace.

Create a Shift for a Group shift settings

At the time of writing Workplace does not have any formal representation of a ‘schedule’ or roster. The UI for shifts provides pagination and exploration functionality over the full collection of shifts associated with a Group instead. When a schedule is published by the Shift Manager, each of its shifts and their data must be created via the API.

Creation follows the standard pattern of posting to an edge, here the shift settings /shifts edge:

POST /{shift-settings-id}/shifts?
  worker_id={work-user-id}&
  start_timestamp=1632304800&
  end_timestamp=1632391200&
  label=Front+Desk&
  external_id={deduplication-key}

See below for details of label restrictions.

Read a Shift

GET /{shift-id}

Update A Shift

Any existing shift can be updated by simply updating its fields:

POST /{shift-id}?
  shift_worker={work-user-id}&
  start_timestamp=20221224T235959Z&
  end_timestamp=20221226T000000Z&
  label=Front+Desk&
  external_id={deduplication-key}

List all shifts filtering by filtering parameters

Listing shifts allows filtering parameters including external ID, start timestamp, end timestamp.

GET /{shift-settings-id}/shifts?
  fields=id,external_id&
  start_timestamp=1632304800&
  end_timestamp=1632391200

Note: the start timestamp is treated as greater than or equal to the start of the shift. The end timestamp is treated as less than or equal to the end timestamp of the shift.

Deleting a shift

Deletion of a single shift is transitive and will also result in the deletion of any attached shift covers.

DELETE /{shift-id}

Shift cover for an existing shift

For existing shift objects, if shift cover (a request by an employee) is available via the third party platform, they may also be created associated with a shift to maintain consistency.

Create a shift cover request for an existing shift

POST /{shift-id}/shift-covers?
  approver_id={shift-change-approver-id}

Read shift covers for an existing shift

GET /{shift-id}/shift-covers

Update the details of a shift cover

Shift covers support updates to their state including changing the approver and setting a coverer as well as the shift cover status (TODO).

POST /{shift-cover-id}?
  approver={approver-id}&
  coverer={coverer_id}&
  status=”Approved”

Note: setting the cover offerer and status to covered will also trigger an update to the original shift if one is linked.

Standalone Shift Covers

Shift cover can be used independently from Shift Viewer - in this scenario the settings would likely include ‘shift cover only’ as the setting for the shift setting.

Note: when shift cover is used standalone there may not be a shift associated with it.

Read a Shift Cover

GET /{shift-cover-id}

Read a Shift from the shift cover

If a shift cover was created in the context of a shift event then the underlying event can also be accessed via the shift edge.

GET /{shift-cover-id}/shift

Update a Shift from the shift cover

If a shift cover was created in the context of a shift event then the underlying event can also be accessed via the shift edge.

POST /{shift-cover-id}?
  status=APPROVED&
  requestor={requestor-profile-id}&
  coverer={coverer-profile-id}&
  approver={approver-profile-id}&
  label=Front+Desk&
  start_time=20221224T235959Z&
  end_time=20221226T000000Z&
  external_id=acme:999

Note that the status of the shift cover restricts the valid states for the attributes, e.g. you can’t set a shift cover to approved if there is no coverer set.

Alternate flow: fully automated shift group creation

In the context of a shift management tool where control over the shift group administrators is a key decision in creating new groups primarily for team / squad shift sharing a simpler flow is likely to offer the cleanest integration flow. Assuming the same instance level access for an app and external models of user mapping to Workplace user ID:

Linking phase

For each shift schedule on the external platform:

1. Look up the profile ID for the external ID.
2. Create a new group with the shift schedule managers as administrators.
3. Add all other members of the team as members of the group.
4. Set the shift settings to enable relevant features.
5. Update the external ID of the group shift settings with the external schedule ID.

Then update internal models of the shift schedule to reference the created group.

Publication Phase

When a new shift schedule is published / updated:

1. Lookup (or access cached) group ID for the schedule.
2. [If shift cover enabled] Lookup prior shifts based on any existing ID to check their updated time and details: use these to merge / update local state.
3. Update shift details for existing shifts. If shift cover is enabled, verify whether the shift has been updated, note that shift may have been covered so it is best to check the shift worker profile and updated time.
4. Create new shifts where no prior shift exists.
5. Delete shifts where deletion has occurred.

Web Hooks

The Workplace Shifts product includes web hooks for the following topics and fields following the Workplace webhook conventions.

These webhooks follow the same conventions in terms of data shapes as the above. Please refer to the Workplace Webhook reference for details relating to payload format. Web hooks allow subscription to changes in a ‘field’ set on a specific topic. Note that webhook fields do not represent entity fields.

• Topic: Community Shift Settings updated at a company level
• Field: shift_settings - called when an instance admin changes the company wide feature setting.

• Topic: Group Shift Settings updated at a group level
• Field: shift_settings - called when a group admin changes the group level setting for shift features on / off.

• Topic: Shift Details
• Field: shift - called when any detail of an existing shift is modified, a shift is created or deleted.

• Topic: Shift Cover
• Field: update - called when a shift cover is updated e.g. cover offered or other status change. All feature fields listed in Read a Shift Cover are returned.

Example webhook body for shift

Below is an illustration of the body for a shift detail web hook notification that the shift owner has been updated.

{
  "object":"shift",
  "entry":[
  {
    "id":"{shift_id}",
    “worker":{
      "id":"{Workplace User ID}"
    },
  }, 
  ...]
}

Note: a Webhook call may include a batch of updated shifts in the entry array.

Related Permissions

While this document is predominantly related to shift related features which use the manage_shifts permission granted during app review there are a number of other feature permissions that are likely to be needed to create fully featured integration.

• Manage Groups: group creation, admin management, membership management, shift settings. Needed for orchestration of group administration.

• Manage Company: company level shift feature configuration.