Azure DevOps Integration: Two-Way Work Item Sync with Shorter Loop
Overview#
The Shorter Loop and Azure DevOps (ADO) integration is a robust two-way synchronization system designed to keep your product backlog in perfect harmony with your engineering team's execution.Unlike simple one-way imports, this integration ensures that changes in either platform are reflected in the other, while strictly maintaining the parent-child hierarchy of your work items.
Key Features#
Two-Way Sync: Updates flow bi-directionally. A status change in ADO updates Shorter Loop, and a title change in Shorter Loop updates ADO.
Hierarchy Preservation: The integration respects your full hierarchy (Epics → Features → User Stories). Moving a User Story to a different Feature in Shorter Loop will update the parent link in ADO, and vice versa.
Multi-Project Support: Connect multiple ADO projects to a single Shorter Loop Initiative. Each project can have its own unique mapping configuration.
Automatic Webhooks: No manual configuration required. Shorter Loop programmatically sets up webhooks in ADO to listen for changes.
Loop Prevention: Intelligent logic prevents infinite update loops between the two systems.
Getting Started#
Prerequisites#
To set up this integration, you will need:✅ Azure DevOps Organization URL: The URL of your organization (e.g., https://dev.azure.com/your-org).
✅ Personal Access Token (PAT): A security token from ADO with Full Access (or at least Read/Write permissions for Work Items and Webhooks).
How to generate a PAT in Azure DevOps:2.
Click the User Settings icon (next to your profile photo) → Personal access tokens.
4.
Name it "Shorter Loop Integration".
5.
Set Organization to "All accessible organizations".
6.
Select Full Access (recommended for ease) or custom scopes for Work Items (Read & Write) and Service Hooks (Read & Write).
7.
Click Create and copy the token.
Setting Up the Integration#
Step 1: Connect to Azure DevOps#
1.
In Shorter Loop, navigate to Product Settings → Integrations.
3.
Enter your Personal Access Token (PAT) and Organization Name.
Step 2: Select Projects & Teams#
Shorter Loop will fetch all available projects from your ADO organization.1.
Select the Projects you want to sync.
2.
For each project, map it to a Shorter Loop Team. This ensures work items land in the correct team's backlog.
Step 3: Map Work Item Types#
Define how ADO work item types map to Shorter Loop's hierarchy. You can configure this differently for each connected project.| Shorter Loop Level | Common ADO Types |
|---|
| Epic | Epic |
| Feature | Feature |
| User Story | User Story, Bug, Task |
Step 4: Map Fields#
Map specific fields to ensure data consistency.Description ↔ System.Description
State ↔ System.State (Mapped to To-Do, In-Progress, Done)
How Synchronization Works#
🔄 Two-Way Sync Logic#
From ADO to Shorter Loop: Webhooks instantly push changes (Creation, Updates, Deletions) to Shorter Loop.
From Shorter Loop to ADO: Changes made in Shorter Loop (e.g., prioritizing an item, changing description) are pushed to ADO via API.
Idempotency: The system checks if an update is actually new before processing, preventing duplicate updates and infinite loops.
📊 Status Mapping Logic#
The integration uses a specific logic to map Azure DevOps states to Shorter Loop progress statuses:To-Do: If the Azure DevOps state is "To Do" (case-insensitive), it maps to To-Do in Shorter Loop.
Done: If the Azure DevOps state is "Done" (case-insensitive), it maps to Done in Shorter Loop.
In-Progress: Any other state (e.g., "Active", "Resolved", "New", "Removed") is automatically mapped to In-Progress in Shorter Loop.
🏗️ Hierarchy Integrity#
The integration places a high priority on structure:If you create a User Story under a Feature in Shorter Loop, it will be created as a child of that Feature in ADO.
If you move a Feature to a different Epic in ADO, Shorter Loop will update the relationship to match.
Orphaned Items: If a child item is imported but its parent hasn't been synced yet, the system attempts to fetch and link the parent to maintain the tree structure.
Troubleshooting#
"Authorization Failed"#
Your PAT may have expired. Generate a new PAT in ADO and update the integration settings in Shorter Loop.
Ensure the PAT has access to the specific projects you are trying to sync.
Infinite Loops or Duplicate Items#
The integration has built-in safeguards, but if you notice odd behavior, ensure you haven't set up other automation tools (like Zapier) that might be conflicting with Shorter Loop's native sync.
Webhook Issues#
Shorter Loop manages webhooks automatically. Do not manually delete webhooks in Azure DevOps that start with azure-shorterloop-. Doing so will stop the sync.
If sync stops, try disconnecting and reconnecting the project in Shorter Loop to regenerate the webhooks.
Modified at 2025-12-05 11:06:19
