Preview of qTrace Integration API 2.0

Overview

The qTrace Integration API has always been a critical component of the qTrace product. It serves two important purposes:

  • Allow our customers to interface qTrace with any defect tracker
  • Allow our team to quickly roll out support for new defect trackers

While the first release of the Integration API does its trick, i.e. it’s being used by our team, some of our customers and our partner devZing, it is not without limitations. During the past 2 months, as we have worked to add more features to qTrace, and also spent time working on a new version of the Integration API, one that is easier to develop with as well as being much more robust and powerful.

This post highlights the key features of the Integration API 2.0, which, as we shall see shortly, actually includes 2 different APIs. Subsequent posts in the series show you how to develop custom trackers using these APIs.

But before I go into the detail, let’s clarify one thing. So far I have used the term “trackers” to describe the interfaces between qTrace and defect trackers. But we have realized this is a pretty limited term because people might really want to publish qTrace bug reports or outputs to other destinations as well, such as FTP, cloud storage or any web API. We changed the terminology from “trackers” to “publishers”. The Integration API 2.0 therefore deals with implementations of publishers. Now, let’s get started.

Publisher API

The Publisher API offers maximum flexibility and compatibility with v1.0. At the same time, it is much more robust and powerful than v1.0. Developers using this API need to write code for a class implementing the IPublisher interface and overriding a few operations.

Publishing Context

All implementations of IPublisher are supplied with an IPublishingContext object. This object provides access to standard functionality of qTrace, e.g. show progress indicator, display message box, open save dialog, upload to Dropbox etc. For the first time, integrators are able to build a custom integration that looks and functions very closely to what built-in publishers do if they want to.

Threading Model

The threading model of the API has been changed:

  • qTrace might choose to invoke methods of a publisher from any thread.
  • As a corollary of the above rule, publisher classes must be thread-safe.

“Wait a minute,” you ask, “if my code needs to do UI related tasks, how can this possibly work if my code isn’t invoked by the UI thread?” Well, you have to marshall such tasks to the UI thread yourself. The good news is we have include all sorts of thread marshalling functionality into IPublishingContext, so it’s really easy to marshall code back and forth between UI and background threads. Best of all, all methods of IPublishingContext, including UI-related methods such as displaying progress indicator, can be invoked from any thread without the need to explicitly marshall code.

While the threading model is more strict than v1.0, we believe that this change makes qTrace more robustly interface with custom publishers while eliminating surprises (like “why does this method block the UI but not the other method?”) as well as enabling these publishers to easily utilize parallelism via thread marshalling methods provided by IPublishingContext.

Publisher Settings

The new API allows custom publishers to define custom setting fields instead of being stuck with URL, user name and password like the previous version. Granted, most publishers only need these 3 fields, but that certainly doesn’t work for all. For example, a FTP publisher might need to allow users to configure transferring mode, enable secure FTP and so on. Now, you can do that simply by returning the necessary publisher metadata from IPublisher.GetMetadata() method. For example, this is the code for a FTP publisher that adds 2 additional setting fields.

public PublisherInfo GetMetadata()
{
    return new PublisherInfo {
            SmallIconUri = "/Ftp;component/ftp.png",
            DisplayName = "FTP Publisher",
            HelpUrl = "https://live-qasymphony.pantheon.io//building-a-custom-defect-submitter-for-qtrace.html",
            CustomSettingFields = new List {
                    new SettingField {
                            DisplayName = "Transfer Mode",
                            Name = "Mode",
                            FieldType = SettingFieldType.Dropdown,
                            AcceptedValues = new List {
                                new SettingAcceptedValue {Id = "Active", Value = "Active"},
                                new SettingAcceptedValue {Id = "Passive", Value = "Passive"}
                            }
                    },
                    new SettingField {
                            DisplayName = "Enable SSL",
                            Name = "Ssl",
                            FieldType = SettingFieldType.Checkbox
                    }
            }
    };
}

And this is what the qTrace Settings screen ends up looking:

Service Adapter API

While the Publisher API is very flexible and powerful, allowing you to do anything you want to integrate qTrace and another system, it requires much work to build something whose look & feel and functionality are similar to qTrace’s built-in publishers. For example, it is not trivial to implement Dropbox support, ability to show/hide fields, allow additional attachments and link-only embedding etc. Therefore, we have built on top of the Publisher API a generic API called Service Adapter.

This API provides an out of the box implementation of a qTrace publisher with many screens and associated logic. Developers only need to supply the networking and business logic associated with a specific publisher and plug it into the API and everything will just work. Most of the qTrace built-in publishers are built using this API except for the very tough ones which require much customization and therefore need the flexibility of the Publisher API. (As we improve the Service Adapter API, however, we’ll expect to be able to migrate more publishers to use this API instead because it’s just so productive.)

In order to use this API, you need to implement the IServiceAdapter interface whose definition is as follows.

The 3 methods GetMetadata(), Verify() and Publish() serve similar purpose to those of IPublisher, except they never have to show screens or anything, only need to include code integrating with the destination system. Besides, GetMetadata() can also return metadata indicating the need for custom setting fields, exactly as described earlier.

What notable are the 2 methods GetIndependentFields() and GetDependentFields(). The API uses these methods to discover the fields you want to display in the submission screen, their dependencies, default values, require status and many more. It also supports many different field types. By populating a list of field definitions, you can control exactly how the publisher should look and behaves.

GetIndependentFields() returns a list of fields whose values don’t depend on other fields while GetDependentFields() returns those fields whose values do. The former method is invoked as the generic publisher shows the submission screen. As the value of certain field is changed (i.e. first time it is loaded or when user makes change), the publisher will invoke the latter with appropriate arguments to retrieve the corresponding values of those dependent fields.

Similar to IPublisher, all methods of IServiceAdapter must be thread-safe and may be invoked from any thread. In general, if you choose to use this API, you shouldn’t need to display screens so you should not need to deal with thread marshalling and so on. Simply have your code execute on the calling thread and the generic publisher takes care of the rest, including progress indicator, error displaying, thread marshalling etc. That’s the reason why we decided not to expose IPublishingContext in IServiceAdapter although that might change in the future.

Conclusion

This post examines the key features of qTrace Integration API 2.0. Specifically, we have explored 2 separate APIs, each with specific strengths. You should always start with our easy to use high-level Service Adapter API and only switch to the low-level Publisher if the former doesn’t provide the flexibility you need. Subsequent posts will show you how to build custom publishers using these 2 APIs.

While the API is mostly completed now, we might still refine it a bit until its official release with qTrace 2.6. If you want to have early access to the API or have any question/suggestion, please leave a comment or email us.

Leave a Reply

Your email address will not be published. Required fields are marked *

More Great Content

Get Started with QASymphony