Use this two-way integration to push epics or stories into Shortcut and track their state from airfocus.
Benefits
Use airfocus' flexible Shortcut integration to prioritize your stories and epics to build more effective roadmaps. Collaborate on your prioritization scoring to get the right stuff done. Our Shortcut integration keeps high-level strategy in sync with day-to-day development.
- Import Shortcut epics and stories (as items) into airfocus.
- Push prioritized items into Shortcut for development and track their Shortcut status right from within airfocus.
- Create a flexible filtering and mapping workflow, e.g. map multiple Shortcut states to the same airfocus state.
- Keep fields synced between both systems including title, description, state/lane, label (Two-way sync).
Initial setup
Navigate to the airfocus workspace you would like to set up the Shortcut integration with. Go to "Extensions" and then "Add integrations". Locate the Shortcut integration and click "Connect".
Enter a Shortcut API token. To generate one, open the Shortcut app, go to Settings Your Account API tokens and generate an API token. Click "Proceed".
Notes:
- When setting up a Shortcut integration in airfocus, you have to choose whether you want to import & sync Shortcut epics or Shortcut stories with airfocus.
- You can only integrate one Shortcut workflow at a time. If you want to integrate a) multiple Shortcut workflows or b) both workflow (with its projects & stories) AND epics into the same airfocus workspace, please set up multiple integrations.
Integration filters
First you need to choose whether you want to sync your epics or stories from Shortcut.
IF you have chosen stories, then you can additionally narrow down the selection of items for your sync by:
- Optionally choosing a project of you are still using this legacy feature on Shortcut.
- Optionally choosing labels to limit the import to. If you leave this empty all stories matching the remaining filters will be considered.
IF you have chosen epics, then you can additionally narrow down the selection of items for your sync by optionally choosing labels to limit the import to.
Field mapping
Use mapping to define how information in Shortcut should be mapped to airfocus (and vice versa). Story / epic names (required) and descriptions (optional) are always mapped by default when setting up a new integration.
How to set mapping directions
You can define for each of your fields whether you want to have a one-way synchronization or a two-way synchronization between the field in Shortcut and airfocus.
You can set the mapping directions for all fields at once (as far as technically possible) with the “Set direction” button.
By default, the mapping direction is set from Shortcut to airfocus only and can be changed by the user to whatever is available for mapping.
How to add a new field mapping
When selecting a field in the dropdown, only fields that match the field type will be displayed in the dropdown on the other end. After selecting two fields that you want to map you can select the field options and how they should be mapped.
Field mapping options for stories
| Shortcut | airfocus | Shortcut → airfocus | airfocus → Shortcut | airfocus ↔ Shortcut |
| Name | Item name | ✅ | ✅ | ✅ |
| Description | Item description | ✅ | ✅ | ⚠️ |
| State | Status / custom single select field | ✅ | ✅ | ✅ |
| Priority | Custom single select field | ✅ | ✅ | ✅ |
| Severity | Custom single select field | ✅ | ✅ | ✅ |
| Label | Custom multi select field | ✅ | ✅ | ✅ |
| Custom field | Custom single select field | ✅ | ✅ | ✅ |
| Estimate | Custom number field | ✅ | ✅ | ✅ |
| End date | Custom date field | ✅ | ✅ | ✅ |
Field mapping options for epics
| Shortcut | airfocus | Shortcut → airfocus | airfocus → Shortcut | airfocus ↔ Shortcut |
| Name | Item name | ✅ | ✅ | ✅ |
| Description | Item description | ✅ | ✅ | ⚠️ |
| State | Status / custom single select field | ✅ | ✅ | ✅ |
| Label | Custom multi-select field | ✅ | ✅ | ✅ |
| Start date | Custom date field | ✅ | ✅ | ✅ |
| End date | Custom date field | ✅ | ✅ | ✅ |
| Start + end date field (as a pair) | Custom date-range field | ✅ | ✅ | ✅ |
| Estimate | Custom number field | ✅ | ✅ | ✅ |
⚠️ WARNING: Users can now enable two-way sync for the description field. However, the two-way syncing process might result in slight changes in your Shortcut descriptions' content and formatting. This is due to not all Shortcut stylings being natively supported in airfocus yet.
Notes
- airfocus fields that are mapped one-way from Shortcut to airfocus become read-only fields in airfocus, as any changes a user would make to them will be overwritten again with the next sync.
- If one of the date fields on Shortcut is not set or an Shortcut epic has a due date set to before the start date, then airfocus will fill in the start date with a date one day before the due date.
- You can define which label you want to attach to synced Shortcut work items by default if you have at least one multi-select field mapping configured. (Setting will show up as a subsection of that mapping).
Additional settings
When "Archive unknown items" is enabled, previously imported items will be archived in airfocus, if they are not present in Shortcut anymore or they do no longer fall into the filters set for the integration.
When "Automatic sync" is enabled, your integration will automatically sync every 10 minutes and every time you access the workspace.
When you click "View logs", you can view your Shortcut integration activity logs and see what changes were made before the last sync.
To save your settings and import your stories/epics to airfocus, click update and synchronize.
Give feedback on this article
Have feedback about this article? Tell us about your experience here.