Skip to main content

Azure DevOps Epics Integration - Integration Setup

  • Updated

This article explains how to set up the Azure DevOps Epics to OnePlan Plans integration.

To set up this integration, you need:

  • to have OnePlan and OneConnect approved by an Office365 tenant admin

  • to be a OnePlan admin, meaning you are a user with Owner permissions in OnePlan

  • to be a OneConnect Administrator or Editor in the OneConnect group where you want to set up the integration

  • to be an Azure DevOps admin

OnePlan Setup

The following video walks through the steps to set up OnePlan for the Azure DevOps Epics to OnePlan Plans integration.

For the integration configuration, you will need to collect the following information from OnePlan:

  • the group name

  • an authentication key

  • the authentication key name

  1. Log in to your OnePlan group with your Office365 account.

  2. Generate a new authentication key

    1. Open the Admin pages by clicking on the Settings gear.

    2. Select Integration in the admin navigation.

    3. Click the + (plus) icon in the Authentication Keys section.

    4. Enter a name for the new authentication key. Then click ADD to create the key.

      Note

      It is best practice to create a new authentication key for each integration, and to name each authentication key so you know which integration it belongs to. For this integration, we recommend a name like "Azure DevOps Integration".

    5. Save the key name and generated key somewhere secure. Once you navigate away, the key is hidden.

      ADOINtegration_OnePlanGenerateAuthenticationKey.png

Azure DevOps Setup

The following video walks through the steps to set up Azure DevOps for the Azure DevOps Epics and OnePlan Plans integration.

For the integration configuration, you will need to collect the following information from Azure DevOps:

  • the Azure DevOps URL

  • an Personal Access Token

Note

It is best practice to create a service account to use for the integrations. We strongly recommend setting up an Azure DevOps service account with admin permissions to use in this configuration.

  1. Copy and save the root of the URL (i.e. https://dev.azure.com/Organization).

  2. Generate an Azure DevOps Personal Access Token.

    1. Go to Azure DevOps.

    2. On the top right-hand corner, click on User Settings and select Personal Access Tokens. Once you are redirected to the user settings page, click New Token and fill out the information.

      • Make sure to provide a token name and only allow the token access within the organization you are going to connect in OneConnect.

      • Set the Expiration to be the maximum (Azure DevOps only allows 1 year as the maximum token validity) by selecting Custom Defined and select the dates.

      • Set the Scopes for the token to Full Access.

        Note

        If your Organization does not allow Full Access for any reason, we understand. The integration requires the following permissions at minimum:

        Scope Name

        Permission Level

        Identity

        Read and Manage

        Work Items

        Read, Write, and Manage
        ADOINtegration_ADOTokenInfo.png

    3. Click Create. After you click Create, you will be provided with the token. Make sure to save the token name, key and expiration date somewhere (notepad, doc, etc.), as once you close the tab, the key will remain hidden. Also, note the expiration date to extend the token once it expires.

OneConnect Setup

  1. Go to https://my.oneconnect.ai.

  2. Navigate to OnePlan Plans and Azure DevOps Epics. Click the Configure button. The integration configuration form will open.

    ADO_Epics_Integration_Button.png

  3. Complete the integration configuration form.

    1. Complete the OnePlan Section.

      Note

      Expand the Additional Options heading to see all the necessary fields to be filled in.

      • Group Name: Enter the OnePlan Group name you will be integrating into.

      • Authentication Key: Enter the OnePlan Authentication Key generated from OnePlan.

      • (Optional) Alternate OnePlan Environment URL: If using an alternative environment than https://my.oneplan.ai, please enter the appropriate URL here.

        Note

        Options currently are: https://au.oneplan.ai, https://ca.oneplan.ai, https://eu.oneplan.ai.

      • (Optional) Button Name: If connecting multiple Azure DevOps organizations to a single OnePlan Group, use this field to create a custom name for the Azure DevOps button connecting to the listed Azure DevOps organization.

      • (Optional) OnePlan Default Plan Type: This is to be used in replace of the Portfolio Plan Type field mapping, should one not be provided automatically within the integration. This is to provide a default plan type for any plan level work items that are brought into OnePlan. A single value should be entered.

      ADO_Epics-_OnePlan_Configuration_Section.png

    2. Click Next.

    3. Complete the Azure DevOps Section.

      Note

      Expand the Additional Options tab to see all the necessary fields to be filled in.

      • Azure DevOps URL: Enter the Azure DevOps organization URL (e.g., https://dev.azure.com/{OrganizationName}).

      • Azure DevOps Personal Access Token: Enter the Personal Access Token of the organization that will be integrating into OnePlan.

        ADO_Epics-_ADO_Configuration_Section_1.png

      • Azure DevOps Plan Level Type: Enter a single Azure DevOps work item type that will be the Plan level item in OnePlan. If there are more than one work item types listed, no plans will be brought in.

      • Azure DevOps Work Item Type: Enter any work item type desired to be imported from Azure DevOps into OnePlan as a Backlog/Task level item.

        ADO_Epics-_ADO_Configuration_Section_2.png

      • (Optional) Bring In Tasks and Bugs that are not in an iteration/sprint: (Default) When unchecked, only the tasks and bugs that are in a sprint will be brought in. When the box is checked, all items will be brought in (even if no sprint is selected).

      • (Optional) Allow creation and editing of work items in OnePlan to be brought into Azure DevOps: (Default) When unchecked, users in OnePlan will be unable to:

        • Create new tasks

        • Export changes made on tasks in OnePlan back into Azure DevOps

    4. Click Next.

OnePlan Changes When Integration Setup is Complete

Once the integration is complete, three things will occur in the OnePlan integration page:

  • An integration line item is made.

  • An integration event is created.

  • Azure DevOps is now available in the Connected Systems icon.

Integration Line item

Each item within the Integration section shows the OneConnect integrations connected to the OnePlan Work Plan.

Integration_Line_Item_ADO.png

Integration Event

Integration events are automated responses that will bring data over from OnePlan into Azure DevOps.

What this event does is trigger the OnePlanPublish strategy for any item that is connected to Azure DevOps. This will bring any values that are mapped to go from OnePlan to Azure DevOps to be updated.

What triggers this event is after a connected item has been saved in OnePlan. At the plan details page, this occurs after an item has been modified and then is automatically saved. At the backlog level, this is done after editing a field, and then clicking Save.

Connected Systems

Any item that is connected to Azure DevOps will show the Azure DevOps icon at both the My Portfolio page, and for any item in the Work Plan Backlog page for plans and tasks that are connected to Azure DevOps.

To connect an item from OnePlan into Azure DevOps, navigate to the Work Plan - Backlog page, click on the plug icon (Connected Systems Icon) and select the options of connecting to an existing item within Azure DevOps, or creating a new item. Once the plan is connected, the Connected Systems window can also be used to Import, Export, or Open the Azure DevOps Plan level item.

Related articles

Comments

0 comments

Article is closed for comments.