Instead of Craft vs. TFS / VSTS, let's talk about using Craft with TFS / VSTS. In Craft, you can enable a two-way integration with TFS / VSTS. This will allow your development team to keep using TFS / VSTS for sprint execution while using Craft for ideation, definition, prioritization, planning and workflow management. You can also use Craft to manage your none-development resources, such as UX, Content, Research, Marketing and other teams.
Main difference between TFS and VSTS is that TFS is an on-premise solution, while VSTS is a cloud-based offering. Further in this article, we will refer only to TFS, but integration works in the same way for VSTS as well.
The following Craft entities can be synced with TFS:
Connect Craft to TFS
- Go to main Craft sidebar, select the product and click Sync.
- The Sync your Product panel opens on the right side of the screen. Click Connect next to TFS (Visual Studio) in Development section.
- Enter your TFS URL, username, and personal access token. Note: You will need to specify the scope that this token will authorize: please select Work items (read and write). When you are done, click Next.
- Select a TFS project you want to sync with.
- Now you can choose to select a TFS area and/or team to sync with. This steps are optional - if you leave them blank, entire TFS project will be synced with Craft. Click Next.
- If you want to sync TFS team workflow with workflow of one of the Craft teams, enable Sync Workflow toggle, and select a Craft and TFS teams to sync (Note: if you already selected a TFS team in the previous step, it will be used for workflow sync). This will sync statuses (columns) in both systems for selected teams.
Sprints: Craft and TFS sprints will be synced automatically as long as they have the same name. Please make sure to name your Craft and TFS sprints the same. Sprints that have different names will appear in both systems after sync.
- Click Next.
- Field Mapping opens. Map Craft item fields you want to be synced with TFS item fields and click Next. See more in Field Mapping section of this document.
- Click Sync Data with TFS (or you can choose to do it later. You can sync each item separately, see Single Item Sync below).
- Select one of the ways to perform sync ("Override" options):
- Override TFS items with Craft items.
- Override Craft items with TFS items. Note: On the first sync, this will import all TFS items to Craft. Keep in mind that for further sync from TFS to Craft, you will need to connect a webhook in TFS (see Set TFS to Craft sync via Webhook below).
- Sync according to the last updates. This option allows to pick the last update from both systems by timestamp and sync accordingly.
- Click Sync.
- Choose what to sync:
- All Product - Will sync entire Craft product with selected TFS project/area/team.
- Containers - Choose one or more Craft containers to sync only items that are assigned to these container.
- Sprint Backlog - Choose one or more Craft sprints to sync only items that are assigned to these sprints.
Note: "Override" and "What to Sync" options will be available each time you want to push changes.
- Click Sync and wait until sync is finished. Depending on the size of project, it can take from several seconds to several minutes.
Set TFS to Craft sync via Webhook
To be able to automatically sync back to Craft from TFS, add a webhook in your TFS account by following these steps:
- In TFS, select a project you want to sync with Craft.
- Click Settings icon and select Service Hooks.
- Click "+" button.
- From the Service pop up, select Web Hooks and click Next.
- In the Trigger window, in Trigger on this type of event, select the Work Item Created.
- If you want to sync only specific type(s) of item, select item type in Work item type, i.g. User Story. You will need to create a new webhook for each item type you want to sync or leave [Any] if you want to sync all item types. Click Next.
- In the Action window, enter the URL provided here. Click Finish.
- Click Finish.
- Repeat the same actions for Work item updated trigger.
Note: webhook will automatically sync new and updated items from TFS to Craft. To sync changes from Craft to TFS, you will need to do a manual push.
Sync by Product, Container, or Sprint
When your integration is connected, you can go to Sync panel and click Push next to TFS connection:
You will be prompted with "Override" options (see in Connect Craft to TFS above)
After that, you will be able to choose what you want to sync: Product, Container(s), or Sprint(s).
If you have a large project in TFS, we recommend to push changes by Container or Sprint to make a sync faster.
Single Item Sync
After you connected your TFS account to Craft, you will be able to sync a single item with TFS. For that, in Craft navigate to the item you want to sync, open a TFS pane, and click Sync Item.
Sync Settings (Workflow Sync)
By going to Sync panel > TFS > 3-dot menu, and selecting Settings, you can modify Workflow sync settings.
- Switch on Sync Workflow toggle.
- Select Craft team.
- Select TFS team. Note: if you already selected a TFS team in the Sync to TFS step, it will be used for workflow sync and you cannot change it here.
- Click Save. This will sync statuses (columns) in both systems for selected teams.
Type mapping between Craft and TFS is done automatically in the following way:
By going to Sync panel > TFS > 3-dot menu, and selecting Field Mapping, you can map item fields between Craft and TFS.
You can assign TFS fields for the following Craft fields:
- Story Points
- Link to Craft
- Custom Fields
Select a TFS field for each Craft field you want to sync.
Some fields have pre-mapped values that correspond to similar TFS fields. If you don't want a specific field to by synced, just unselect its pre-mapped value in the dropdown.
Note: you can sync Craft and TFS custom fields. For this, create a Craft custom field. It will appear in Field Mapping, and you'll be able to select a TFS custom field for it.
Once you save these settings, mapped fields will be synced between Craft and TFS.
See Last Sync Log
To see the last sync log, go to Sync panel > TFS > 3-dot menu, and select Show Last Sync Log.
The log summary will open. It will display how many items and sprints were successfully synced, and how many items were skipped.
You will also be able to download a log file with more details on what items were synced.
Disconnect TFS Integration
To disconnect integration, go to Sync panel > TFS > 3-dot menu > Disconnect. This action will remove links between Craft and TFS items.