Skip to content
storywi.se documentation storywi.se documentation storywi.se documentation

Azure DevOps Integration

Transfer your structured requirements to Azure DevOps with a single click while maintaining complete traceability and context.

Key Features

  • One-Click Export: Transfer entire requirement sets to Azure DevOps instantly
  • Complete Context: Preserve all relationships and background information
  • Full Traceability: Maintain links between requirements and original content
  • Rich Content Transfer: Include all associated information:

    • Original requirements context

    • Mockups and screenshots

    • Effort estimates

    • Acceptance criteria

    • Related entities, stories, tasks and epics

    Note: Devops does have some limitations in the API, and some features might not work as expected, depending on the configuration of the Azure DevOps project, the permissions of the user and the configuration of the Azure DevOps instance. Please let us know if you encounter any issues.

Configure Azure DevOps Connection

  • Configure Azure DevOps Connection in the connections page
  • Add your Azure DevOps organization URL (e.g., dev.azure.com/your-organization), your project name and personal access token (PAT)

Note: this will be the user that will be used to create the work items in Azure DevOps.

  • Click on “Save and test”
  • You will get feedback on whether the connection was successful or not.

Connection possibilities

Direct Connection

With the PAT set and an Azure DevOps instance reachable from storywise, you can directly connect to Azure DevOps. If you use a self-hosted Azure DevOps Server, you need to make sure that the host is reachable from storywise (contact us if you need help with this). In the top menu in a project, you will find a “Sync” button. Clicking it will bring you to the project connection page, if you have not connected your project yet. If your project is already connected, you will be able to choose which content you want to sync to Azure DevOps.

Sync Mode: You’ll be able to choose between:

  • Only new content: Only synchronizes epics/stories/tasks that have been created since the last synchronization to Azure DevOps.
  • New content and update existing: Synchronizes new epics/stories/tasks created since the last sync and updates content of existing items - like descriptions, acceptance criteria, screens and links.
  • Delete and resync all: Deletes all previously synchronized stories and transfers them again completely.

Note: If you choose to delete and resync all, storywise will still only delete and recreate work items that were created in storywise.

Note 2: If you have deleted work items in Azure DevOps, you need to do a manual deletion in storywise to delete them.

Epic Options:

Now you can choose which epics you want to sync to Azure DevOps.

Features and Releases:

You can choose for each feature and release if you want to sync it to Azure DevOps. This is the same status as in the pricing and export page. storywise will remember the last choice, if saved, so you get the same result as in the pricing and export page. However, you can override the status without saving the choice if you want to, for example if you want to export a feature without syncing it to Azure DevOps. storywise will also remember who saved the choice.

Safety questions:

You will be asked to confirm the sync if you are choosing to delete and resync all and see the list of epics that will be deleted and recreated.

How to get an Azure DevOps Personal Access Token

Follow these steps to create your token:

  1. Log in to your Azure DevOps account
  2. Click on your avatar and select “Security” from the menu
  3. Click on “Personal Access Tokens”
  4. Click on “New Token”
  5. Enter a name for the token and select the permissions

Note: You need to select the permissions “Work Items (read and write)” and “Project and team (read and write)”

  1. Click on “Create”
  2. Copy the created token and paste it into storywise

Note: This is the only opportunity to copy the token. Otherwise, you will need to create a new token.

Troubleshooting: Azure DevOps error VS402356

If you see VS402356 during sync, Azure DevOps is telling you that the operation targets the Process (inherited process) area and your identity does not have sufficient permissions for that process. It is not a generic HTTP error.

What this usually means

  • The request is trying to modify process metadata: add/modify work item types, states, or custom fields; or otherwise change a process that is not modifiable.
  • This commonly happens when using the Processes or Work Item Tracking Process APIs behind the scenes.

Why you might see it during sync

  • The sync first reads project/process info and then may attempt to create or update work items and, when configured, process-related artifacts (custom fields, states, WITs).
  • If the target project uses a System process (Agile/Scrum/CMMI) or the PAT user lacks org-level process permissions, Azure DevOps will respond with VS402356.

Common root causes

  1. The project uses a System process (Agile/Scrum/CMMI)
  • System processes are read-only. You cannot add/modify WITs, states, or fields via API. Any attempt fails with VS402356.
  1. The PAT user lacks organization-level process permissions
  • Modifying a process typically requires membership in Project Collection Administrators (or equivalent process permissions).
  1. The project is not on an Inherited process
  • Even with rights, if the process is not Inherited, customization calls are blocked.
  1. PAT scopes are insufficient
  • Work Items: Read & write is required for creating/updating items.
  • Project and Team: Read is required for reading project/process metadata.
  • Process modification relies on org permissions, but missing basic scopes can still block operations.
  1. Project-level permissions block work item creation/updates
  • For example, lacking “Edit work items in this node” or restrictive Area Path permissions.

How to confirm what failed

  • In Azure DevOps UI:
    1. Organization Settings → Process → locate the process used by your project/config.
    2. If it shows “System process”, it is not modifiable. Switch the project to an Inherited process to customize.
    3. Check the user owning the PAT: Organization Settings → Users → ensure they are in Project Collection Administrators (or have equivalent process permissions).
    4. In the target project: Project Settings → Permissions → verify the user can create/edit work items for the relevant Area Paths.

Fixes depending on your scenario A) If your sync needs to add/modify fields, states, or WITs

  • Ensure the project uses an Inherited process (not System).
    • Create an inherited process from Agile/Scrum/CMMI.
    • Migrate the project to use that inherited process.
  • Ensure the PAT user is Organization admin / in Project Collection Administrators.
  • PAT scopes:
    • Work Items: Read & write (required)
    • Project and Team: Read
    • If touching identities/attachments, include corresponding scopes as needed.

B) If you cannot change the process or elevate permissions

  • Configure sync to avoid process-level mutations. Use the Basic Process to disable any auto-creation of custom fields/states in your sync settings (when available).

Quick checklist

  • Is the project’s process Inherited? If not, create an inherited one and move the project to it.
  • Is the PAT owner in Project Collection Administrators? If not, add it (even temporarily) to validate the hypothesis.
  • Does the PAT include at least: Work Items: Read & write and Project and Team: Read?
  • Does the user have project-level permissions on the target Area Path(s)?

Mapping this to storywise sync

  • Our sync reads the process and then performs work item operations. If configured to create fields/states/WITs and the target project uses a System process, or the PAT lacks process permissions, Azure DevOps will return VS402356.
  • Two ways forward:
    1. Switch the project to an Inherited process and use a PAT with org-level permissions, or
    2. Use the Basic process for the sync to perform only work item CRUD against the existing schema (no schema changes).