Developing Loupe 4 - New Server Extension API for System Integration
If you look back at our plans for version 4 you’ll notice that rich defect tracking integration is one of our “must do” items. We’ve had defect tracking integration for years - it predates Loupe Server. And therein is the problem: The extensibility API that it relies on was limited to the features available in Loupe Desktop alone. When Loupe 3.5 came along and added Issue and Application Event tracking to the server we didn’t go back and extend the API at that time to expose the same information to addins.
We’ve had the belief for years that Loupe should complement the team’s existing defect tracking/workflow system. Yes, if you didn’t have any workflow system then you could just use the built-in Issue tracking capabilities and be done with it. But, we’ve deliberately avoided adding fancier workflow features to Loupe because there are many existing systems that focus just on that problem - and they are intended to track all of the work your team has, not just problems detected in the wild. For Loupe 3.8 we’re going to get rid of any awkward seams between Loupe and your workflow system. At a minimum, we believe this requires:
- Activating an Issue in Loupe Opens One in the External System: No one wants to double-enter items; if an issue is activated in Loupe then it should reach out to the external system and create a new work item.
- Navigate Back and Forth between the External System and Loupe: When an issue creates a work item they should be linked so that you can navigate in the web UI of both systems back and forth. It may not save a lot of time, but it’s just exasperating to have to do searches to find items when you know there’s a link available.
- Automatically Resolve an Issue in Loupe if the Work Item is Closed: When you fix an item you’re going to update your workflow system. That should in turn cause Loupe to mark the related issue as being resolved (and figure out the correct version to attribute the resolution to). That way the status views in Loupe are trustworthy and accurate without manual effort.
To enable this we’ve significantly extended the Loupe AddIn API available on Loupe Server. After some experimentation we’ve come up with a different approach for exposing this new functionality from the current API. The primary difference is that the server exposes events and a single addin need only implement one interface to get access to all of the workflow-related functionality.
New Server-side Events
An extension can register a handler for one of the new server-side events to be notified when server data changes, including:
- Session Added
- Session Data Added
- Session Data Removed
- Log Event Added.
- Log Event Changed.
- Application Event Added.
- Application Event Changed.
- Application Event Review.
- Issue Added
- Issue Activated
- Issue Changed
- Issue Closed
- User Added
- User Changed
- User Removed
To be clear, most of this isn’t required for integrating with a defect tracking system but we decided to do a little extra work and be comprehensive. After all, extensibility is about enabling you to handle scenarios we didn’t think of!
How would you update an external workflow system using this API? For pushing updates from Loupe to the external system you’d want to register for the Issue Activated and Issue Closed events. This lets you open (or re-open) a work item when an issue is opened in Loupe and close it when it’s resolved or suppressed in Loupe.
We’ve also added methods to the API to support changing issue states, adding notes, and adding links so you can add a link from the issue in Loupe to point to the external system.
What about taking changes from the external system and pushing them into Loupe? To support that you can create a background thread when your extension is initialized and poll the external system. Depending on feedback we may add an inbound web hook to Loupe to let an external system poke the Loupe Server that an extension should check for updates.
More than Just Issues
This same API is designed to let you respond to the same events that today trigger notifications. For example, if you want to push a message to HipChat every time an Application Event ends up on the review list you can do that - just register for the ApplicationEventReview event and reach out to your HipChat account to send the right message. The API provides fully formed permalink URLs for each entity so you can easily send a link that will bring the user back into Loupe to view more information.
The possibilities are really quite extensive - we can imagine people making a Slack or HipChat bot to respond to messages and open new issues without the user ever having to log into Loupe.
Some Breaking Changes
For the most part we’ve left the existing addin API’s alone but we have had to make a few adjustments to reuse types and re-orient the processing API from being desktop focused to server focused. This means most existing addins will need to be recompiled and have one or two API calls adjusted. We’ll publish specific guidance when we get closer to release and know exactly what the changes are.
Stay in the Loop with Loupe
Subscribe below to receive additional Loupe 4 updates, design artifacts, previews builds and special offers.