This article explains how to set up the integration between your OnePlan group/environment and Azure DevOps: Epics.
Before beginning, the following assumptions are made in order for this integration setup to be successful:
- Office 365 is up and running
- Azure DevOps is up and running and joined to the same Active Directory as Office365
- OnePlan group is setup in the same Office365 tenant
OnePlan setup
In order to do the OnePlan setup, you need to be an admin, meaning you are a user with Owner permissions in OnePlan. If the Advanced Settings are enabled for your group, continue to the next steps. If the Advanced Settings are NOT enabled, skip to the alternate steps below.
- Log in to your OnePlan group with your Office365 account.
- Open the Admin pages by clicking on the Settings gear.
- Select Integration in the admin navigation.
- Click the + (plus) icon in the Authentication Keys section.
- Save the key name & generated key somewhere (such as in a notepad doc), as once you navigate away, the key cannot be seen. To be used at a later step in the OneConnect configuration.
Follow these steps if you don't see the Integration Settings heading in your OnePlan Group, which means the Advanced Settings are not enabled.
Navigate to https://my.oneplan.ai/config/code to generate your Integration Key.
Save the key name & generated key somewhere (such as in a notepad doc), as once you navigate away, the key cannot be seen. To be used at a later step in the OneConnect configuration.
Add Backlog App to OnePlan
If you haven't already done so, add the Backlog App. By adding the Backlog App, the the Backlog work type is created. This integration will map from Azure DevOps to the Work Plan, specifically the type: Backlog.
For instructions how to install an app click here: How do I add apps?
Azure DevOps
AzureDevOps permissions?
Log in to your organization's Azure DevOps environment (eq. dev.azure.com/Organization).
On the top right-hand corner, click on the 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.
- Click the Create button.
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.
This token will be used in the later step in the OneConnect configuration.
OneConnect setup
You must be logged in as the Tenant Admin.
- Go to https://my.oneconnect.ai.
- Configure the following integration: OnePlan and Azure DevOps Epics. Click the Configure button.
ONEPLAN
- Authentication Key: Enter/paste the OnePlan Key that you saved from the earlier OnePlan Setup steps.
- Click the Next button.
INTEGRATOR
Click the Next button.
AZURE DEV OPS
- Your Azure DevOps URL: Enter your organization Azure DevOps URL that you also used to create the token.
- Your Azure DevOps API key: Enter/paste the Azure DevOps token key from the earlier Azure DevOps token steps.
3. Expand Additional Options:
Allow user to select which Work Item Types under Epics to bring into OnePlan as backlog work type under tasks. By default, the value will be Task and Bug if none specified.
4. Click the Next button.
Integration information
Functionality
This integration has two main use cases for functionality.
- Create or Update Plans from OnePlan as Epics in Azure DevOps.
- Create or Update work items under the Epics in Azure DevOps into OnePlan WorkPlan Tasks (Backlog work type).
- Create or Update sprints from Azure DevOps into OnePlan.
NOTE: The backlog item sync is bi-directional even after the initial sync. You can create or edit data in OnePlan or Azure DevOps and then sync to the other system. The only fields that are not editable in OnePlan are the ones you choose to only sync from DevOps to OnePlan.
Scheduled jobs
The following scheduled jobs are installed by default.
- SynchTeamProjects
- Synchronize all team projects (including sub team projects) into a default choice fields in OnePlan (Team Projects Areas).
- OnePlanUpdate
- Synchronize Epics from Azure DevOps as Plans in OnePlan, and its Work Items beneath the Epics as WorkPlan Tasks of Backlog Work Type.
- Work item types synchronized are based on the ones specified at the Azure DevOps configurations steps above in OneConnect.
- OnePlanPublish
- Synchronize OnePlan plans as Epics in Azure DevOps.
Default field created
The following field is created in OnePlan at the time of setting up the integration: Team Projects Areas
- This field is auto created during integration installation at the Plan level in OnePlan.
- This field is a choice text field.
- This field will be used to indicate which Azure DevOps Team Projects a plan should get created in Azure DevOps.
- This field will be auto populated when SynchTeamProjects schedule job is running.
Default field mappings
Plans (OnePlan) <--> Epics (Azure DevOps)
| OnePlan Fields | Azure Dev Ops Fields | Direction | Notes |
|---|---|---|---|
| Name |
Title | Both | Required |
| Team Projects Areas | Area ID | Both | Required (Important) |
| Owner | Assigned To | Both | Required |
| Portfolio Plan Type | Work Item Type | Azure DevOps to OnePlan | Required |
Backlogs (OnePlan) <--> Items (Azure DevOps)
| OnePlan Fields | Azure DevOps Fields | Direction | Notes |
|---|---|---|---|
| Name | Title | Both | Required |
| Parent ID (Structure) | Parent Item ID |
Azure DevOps to OnePlan | Required (Important) |
| Assigned To | Assigned To |
Azure DevOps to OnePlan |
Required |
| Portfolio Plan Type | Work Item Type | Azure DevOps to OnePlan |
Required |
| Start | Iteration Start Date | Azure DevOps to OnePlan |
Optional |
| End | Iteration Finish Date | Azure DevOps to OnePlan |
Optional |
| Iteration (OnePlan System) | Iteration Path | Azure DevOps to OnePlan |
Required for Sprint |
| Status | State | Azure DevOps to OnePlan |
Optional |
| Effort | Original Estimate | Azure DevOps to OnePlan |
Optional |
| Remaining Effort | Remaining Work | OnePlan to Azure DevOps | Optional |
Lookup Tables (OnePlan) <--> Team Area Projects (Azure DevOps)
| OnePlan Fields | Azure Dev Ops Fields | Direction | Notes |
|---|---|---|---|
| Team Projects Areas (Plan) |
Project/Area Name | Azure DevOps to OnePlan | Required (Important) |
Additional mappings for existing users (before 01 October 2021)
To use the Sprints feature of the OnePlan and Azure DevOps integration, users who were using the integration before the 01 October 2021 need to update mappings to the following:
NOTE: This mapping will allow work items that are synchronized as backlog items in OnePlan be referenced to its corresponding sprint. This setting is be needed for new users (after 01 October 2021) as it will be mapped by default.
Additional Notes
- Start Date and Finish Date at the Backlogs and Items mapping level are based on the iteration start and finish date in Azure DevOps.
- Task and Bug need to be in an iteration in order for them to synch into OnePlan.
- Plans that are synchronized into Azure DevOps need to have a valid Team Projects Areas field filled with value.