Azure Boards integration

With the Azure Boards integration, you can create new work items from failed mabl test runs, link tests to existing work items, and use existing work items to build new mabl tests. This article explains how to connect mabl to Azure Boards, configure the work items that mabl creates, and use the integration day to day.

• Set up the integration
• Create and link work items
• Build tests from work items
• When the connection stops working

Set up the integration

Before you start

You need the following to connect Azure Boards:

• An Azure DevOps organization hosted at https://dev.azure.com/{organization} and connected to Microsoft Entra ID, so that people sign in with work accounts. Azure DevOps Server, the on-premises product, isn't supported, and organizations that use only personal Microsoft accounts aren't expected to work.
• A Microsoft account with normal access to the Azure DevOps project you want to use. Basic access and the Contributor role are enough to create work items. mabl acts on behalf of this account, so the work items it creates show that account as the creator.
• Depending on your organization's Microsoft Entra settings, an administrator may need to approve mabl before anyone can connect. See Ask an administrator to approve mabl.

Connect Azure DevOps

1. In the mabl app, go to Settings > Integrations.
2. In the Available integrations section, find Azure Boards and click Connect.
3. Sign in with your Microsoft account and review the permissions that mabl requests. mabl asks to read and write work items, to read and write test management, which a later results sync to Azure Test Plans will use, to read projects and teams, and to read builds. It doesn't ask for full access to your organization. The access stays active so you don't have to sign in again.
4. Click Accept. Microsoft returns you to mabl, on the configure form for the new integration.

If Microsoft refuses the sign-in, mabl shows Microsoft's reason. The most common one is that your organization requires an administrator's approval.

Ask an administrator to approve mabl

mabl is a verified publisher, and the permissions it requests are ones that a regular user is allowed to approve. Whether you can approve them yourself depends on your organization's Microsoft Entra policy. In organizations that let people approve applications, you approve mabl the first time you connect and move straight on to the configure form.

Many organizations don't let users approve applications. If you see a "Need admin approval" page when you try to connect, mabl shows you a ready-made approval link on a page titled Ask your administrator to approve mabl.

1. Click Copy approval link and send the link to a Microsoft Entra administrator in your organization.
2. The administrator opens the link, signs in, and approves mabl. They don't need a mabl account. Once they approve, they see a confirmation that mabl is approved.
3. Go back to Settings > Integrations and click Connect again. This time the sign-in completes and you land on the configure form.

The approval covers your whole organization, so one approval is enough for every mabl workspace that connects Azure Boards.

Configure the integration

After you sign in, the configure form in the mabl app asks which project the integration should use:

1. Give the integration a name. The default name is "Azure Boards".
2. Enter the Organization URL in the form https://dev.azure.com/{organization}. If you paste the URL of a project or a board instead, mabl reduces it to the organization.
3. Choose the Project. The list shows the projects that your Microsoft account can see. Each integration connects to one project. To file work items in another project or another organization, add a second integration.
4. Choose the Default work item type. mabl suggests the project's bug type, whatever your process calls it. A project on the Basic process has no Bug type, so mabl suggests Issue there. New work items open on this type, and you can pick a different type each time you create one.
5. Under Work item fields, review which fields the new issue form shows for each work item type. See Choose fields and default values.
6. Click Save.

The integration appears in the Active integrations section on saving. If you want to connect to multiple Azure DevOps projects, add an integration for each project you file work items in.

Choose fields and default values

Azure work item types can carry dozens of fields, and most of them aren't things a person filing a bug should have to think about. Under Work item fields on the configure form, you decide, for each work item type, which fields the new issue form shows and what values they start with. mabl already leaves out the fields that Azure DevOps maintains itself, such as State, Reason, and the audit stamps.

1. Pick a Work item type. The table lists every field that mabl can set for that type. Required fields carry a Required badge.
2. To omit a field from the new issue form, turn off the Shown toggle. A required field can only be hidden if it has a default value because Azure DevOps won't accept the work item without one.
3. To pre-fill a field, enter a Default value. For fields with a fixed set of values, such as Priority, choose from the list. For Area Path and Iteration Path, start typing to pick from the project's paths. Fields with default values are not required on the form, and a field with a default and only one possible value is hidden since there's nothing to choose.
4. To drop every custom field at once, click Hide all custom fields. Required custom fields without a default stay visible.
5. Repeat for each work item type your team files from mabl, then click Save.

New integrations start with a Tags default of mabl on the default work item type, so work items filed from mabl are easy to find in Azure Boards. Remove the default before saving if you don't want the tag.

mabl checks these settings against your Azure DevOps process every time the form opens, so a change in Azure DevOps doesn't quietly break it:

• If a hidden field becomes required in Azure DevOps and has no default, the form shows it again.
• If a default is no longer valid, such as a value removed from a picklist, mabl drops the default and shows the field.
• Settings for a type, field, or value that no longer exists in Azure DevOps are listed on the configure form as removed when you save.

Edit, reconnect, or remove the integration

To edit the integration, find it in the Active integrations section and click on the pencil icon. Changing the project clears the field settings, because they belong to the old project's process. To sign in to Microsoft again, click Reconnect. See When the connection stops working.

To remove the integration, click on the trash icon in its row and confirm. Tests keep their linked issues, but you can no longer file or link work items from mabl, or build tests from work items. Nothing changes in Azure Boards.

Create and link work items

You can create and link work items from the following places in the mabl app:

• From a failed test run: on the test output page, click on Create issue below the failure analysis, or on the failed step.
• From a test: on the test details page, open the Issues tab and click on + New issue.
• From the issues page: click on Tests in the left-hand navigation, open the Issues tab, and click on + New issue.

Create a work item from a failed run

In the New issue form, enter the following information:

1. Choose your Azure Boards integration in the Issue Tracker dropdown.
2. Select "Create new".
3. Choose the Project and the Work item type. The list includes every type in the project's process, so it may be long. The integration's default type is listed first.
4. Click Next. The form shows the fields you chose to show for that type, with any default values filled in. For a work item created from a failed run, mabl pre-fills the title with the failure analysis's title and the description with the rest of the analysis. You can edit both.
5. Fill in anything else and click Submit.

A success message appears at the bottom of the screen. Click on the link to open the work item in Azure Boards in a new tab.

For a failed test, the type you want is almost always Bug, or Issue on the Basic process, which has no Bug type. mabl preselects the project's bug type, and an admin can change the default on the integration. Some teams file fixes as Task. The list of types can't be trimmed, but an admin can shape each type's form with field settings.

What a created work item contains

A work item created from a failed run carries everything a developer needs to start on the problem:

• Title: the failure analysis's title, or whatever you changed it to on the form.
• Description: the rest of the failure analysis, the screenshot of the page as the run left it, and a footer with two links: View the failed test run in mabl and Open the test in mabl. The description is written in markdown.
• Attachments: the final-state screenshot, the DOM snapshot, the HAR file, and the Chrome trace from the failing run.
• Links: hyperlinks to the mabl test run and the mabl test, next to the work item's other links.

Attachments are added on a best-effort basis. A file over 25 MB is skipped, and if a file can't be uploaded, the work item is still created without it.

Link an existing work item

To link a mabl test or test run to a work item that already exists, open the New issue form and take the following steps:

1. Choose your Azure Boards integration in the Issue Tracker dropdown.
2. Select "Link existing".
3. Choose the Project.
4. Under Issue to Link, search for the work item by title or enter its ID.
5. Click Submit.

A success message appears at the bottom of the screen, and the work item appears on the test's Issues tab.

Manage work items in mabl

You can review all linked work items on the issues page, Tests > Issues, or on the Issues tab of a specific test. Click on the work item link to open it in Azure Boards, or re-run the mabl test to reproduce the problem or validate a fix.

mabl shows work items as either "Open" or "Closed". About every 10 minutes, mabl checks each linked work item. Closing, reopening, deleting, or restoring a work item in Azure Boards updates the issue in mabl on the next check.

To remove a work item from a test, open the Issues tab on the test details page, select the issues you want to remove, click on Unlink, and confirm. The work item itself stays in Azure Boards.

Build tests from work items

If a work item already describes the behavior you want to test, you can hand it to the mabl agent when building a new test or editing an existing one. User stories, product backlog items, and requirements with acceptance criteria work well, as do bugs with steps to reproduce and test cases in Azure Test Plans. When the workspace has an enabled Azure Boards integration, the + menu below the prompt on the Build tests page includes an Azure Boards work item option.

1. Go to Build tests and, on the New test or Edit test tab, click + below the prompt and choose Azure Boards work item.
2. If the workspace has more than one Azure Boards integration, choose which one to search.
3. Search by title, or enter a work item ID such as 123 or AB#123, or paste the work item's URL. Each picked work item appears as a chip. You can add up to five.
4. Describe anything the work item doesn't cover, such as test data or the starting state, and send the prompt.

The agent reads the fields that describe the behavior for that kind of work item: the title, description, and acceptance criteria of a user story, the steps to reproduce on a bug, or the steps and expected results of a test case, including shared steps. It never reads comments, history, attachments, or custom fields. In the conversation, the agent refers to a work item by its ID in the form AB#123.

When the connection stops working

The Microsoft connection behind an integration can stop working. Microsoft expires it when it goes unused for about 90 days, when the connecting account's password is reset, or when an administrator revokes mabl's access. When that happens, creating a work item fails with a message asking you to reconnect the integration.

To reconnect:

1. Go to Settings > Integrations and click on the pencil icon for the Azure Boards integration.
2. Click Reconnect and sign in with your Microsoft account. The account needs to see the integration's project. It doesn't have to be the account that connected originally.
3. Back on the form, the message "Signed in to Azure DevOps again" confirms the new connection. Click Save.

Reconnecting keeps the integration's work items and field settings as they are. It only replaces the sign-in.