GetMetadata() Verify() Publish() Build a Custom Adapter Setup Create a service adapter GetMetadata()...

Transcription

1 Contents qtest explorer Integration API... 3 IPublisher... 4 IPublisher.Context... 4 IPublisher.GetMetadata()... 4 IPublisher.Verify()... 4 IPublisher.Publish()... 5 IServiceAdapter... 7 IServiceAdapter.IsUpdatingDefect... 7 IServiceAdapter.UpdateExistingDefectInformation... 7 IServiceAdapter.GetMetadata()... 7 IServiceAdapter.Verify()... 7 IServiceAdapter.Publish()... 8 IServiceAdapter.GetIndependentFields() and IServiceAdapter GetDependentFields()... 8 Class Descriptions... 8 PublisherInfo... 8 PublisherSettings... 9 PublishingRecord... 9 PublishingResult Field FieldType AcceptedValue Attachment Thread-Safety Deployment Sample Code Build a Custom Publisher Setup Create a custom publisher Context... 14

2 GetMetadata() Verify() Publish() Build a Custom Adapter Setup Create a service adapter GetMetadata() Verify() GetIndependentFields() and GetDependentFields() Submit()... 29

3 qtest explorer Integration API qtest explorer has built-in support for integrating with various defect trackers: JIRA, Rally, Bugzilla, HP Quality Center, Team Foundation Server 2008/2010/2012, FogBugz, VersionOne and QASymphony s qtest. It also supports integrating with cloud storage as Dropbox, Confluence or SharePoint to store qtest explorer s outputs. While QASymphony will continue enhancing qtest explorer to integrate with more defect trackers and storages, you can build your own custom integration to a particular defect tracker or cloud storage via qtest explorer s extensible integration mechanism. Note: this documentation details the integration API that works with qtest explorer version x or later. The contracts between qtest explorer and custom publishers are located in the assembly qtestexplorer.publishing.contracts.dll. This assembly includes the following public interfaces and classes:

4 IPublisher This interface is to communicate with a particular publisher. Developers using this interface need to write code to for a class implementing the IPublisher interface and overriding a few operations. IPublisher.Context All implementations of IPublisher are supplied with an IPublishingContext object. This object provides access to standard functionality of qtest explorer, e.g. show progress indicator, display message box, open save dialog, upload to Dropbox etc. IPublisher.GetMetadata() Retrieves the metadata about the publisher. The signature of GetMetadata() method is shown in Figure 1 PublisherInfo GetMetadata(); Figure 1. GetMetadata method GetMetadata() returns PublisherInfo object that describes the publisher. Refer to PublisherInfo section for detailed description about this class. IPublisher.Verify() When users click the Test Connection button in the Settings Screen (Figure 2), qtest explorer will invoke the Verify() method with supplied connection information to verify whether information provided by

5 user are valid. This method might be invoked from a non-ui thread. Therefore, you might need to marshal your operation to the UI thread should you need to do so. Figure 2. Test Connection The signature of Verify() is shown in Figure 3. VerificationResult Verify(PublisherSettings settings); Figure 3. IPublisher.Verify() Verify() accepts a parameter which is of type PublisherSettings containing the publisher settings and returns the VerificationResult object that describe the verification result. Refer to Class Description section for descriptions about PublisherSettings and VerificationResult classes. IPublisher.Publish() When user clicks Submit button from Editor toolbar, qtest explorer opens submission dialog in order for user to enter information about the defect as described in (Figure 4)

6 Figure 4. Submission dialog On the defect submission dialog, user can: Choose to Create new defect or Update an existing defect. Note: some defect tracker might not allow to update an existing defect, so a tracker integration implementation should turn off the option to update existing defect by setting PublisherInfo.SupportUpdatingDefect to false. For more detail on how to do this, refer to PublisherInfo class description for more detail Select screenshot options: attach all screens, selected screen, etc. to the defect. Note: attachment format and exporting image quality is obtained from Submission tab on Settings screen Title: the title of the defect Description: more detail about the defect After choosing either Create new defect or Update an existing defect, the submission screen will populate fields and values for user to enter more detail about the defect. Once user clicks Submit, the Publish() method is invoked. The signature of Publish method is shown in Figure 5 PublishingResult Publish(PublisherSettings settings, PublishingRecord record); Figure 5. IPublisher.Publish() Publish() method s parameters: settings: the publisher settings, refer to PublisherSettings for detailed description record: contains the information about the defect being submitted, refer to PublishingRecord for detailed description

7 IServiceAdapter While the Publisher API is very flexible and powerful, allowing you to do anything you want to integrate qtest explorer with another system, it requires much work to build something whose look & feel and functionality are similar to qtest explorer 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 qtest explorer 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 qtest explorer 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. IServiceAdapter.IsUpdatingDefect This property will be set by qtest explorer to let the adapter knows that it should be creating a new defect or update an existing one. If, on Submission screen, user selected on Create new Defect button, this property value is false, if Update existing defect button has been selected, this property value is true. IServiceAdapter.UpdateExistingDefectInformation After selecting Update existing defect on Submission screen, the user has another option whether they want to update existing defect information or not, e.g. they might want to update a value for Assignee field, or update Status to Not fixed, etc. If this option is not selected, only attachments are attached to that existing defect when they clicked Submit. If Update existing defect option is selected, the value for this field, UpdateExistingDefectInformation is set to true. An implementation of service adapter should consult this information to decide whether it only attaches files to the existing defect, when UpdateExistingDefectInformation is false, or also update the existing defect information, when UpdateExistingDefectInformation is true. IServiceAdapter.GetMetadata() Retrieves the metadata about the adapter, similar to IPublisher.GetMetadata() IServiceAdapter.Verify() Verify whether publisher information provided by user in Settings screen are valid, similar to IPublisher.Verify()

8 IServiceAdapter.Publish() The signature of Publish() method is shown in Figure 7 PublishingResult Publish(PublisherSettings settings, PublishingRecord record, IDictionary<string, string[]> fieldsvalues, List<Attachment> attachments); Figure 7. IServiceAdapter.Publish() Publish() method s parameters: settings: contains the publisher settings. Refer to PublisherSettings for more information about this class record: contains the information about the defect being submitted. Refer to PublishingRecord for more information about this class fieldsvalues: the map of field name and their value(s). Note that value is an array, values of single-valued fields are stored in the first position attachments:list of qtest explorer attachments. Note that as users might have selected to embed only link or Dropbox/SharePoint/Confluence link of some attachments (as opposed to attach their entire files), your code must take this into account when submitting the defect IServiceAdapter.GetIndependentFields() and IServiceAdapter 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 marshaling 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 marshaling etc. Class Descriptions PublisherInfo Contains information about publisher

9 Name Type Description DisplayName string Unique name, also used for displaying purpose. SmallIconUri string The URI of the small icon displayed in Settings screen. The returned URI will be bound directly to WPF s Image.Source object. E.g. /qtestexplorer.publishing.assembla;compone nt/icon.png" LargeIconUri string The URI of the large icon displayed in Submission screen. The returned URI will be bound directly to WPF s Image.Source object. E.g. /qtestexplorer.publishing.assembla;compone nt/logo.png" HelpUrl string The help URL associated with this publisher. If null, the help link is not shown. SupportUpdatingDefect boolean If true, qtest explorer shows the option Update existing defect on defect submission screen DisableDefaultSettingFiel ds boolean If true, qtest explorer will not show URL, User Name and Password fields on Settings screen. Default is false. DisableVerification boolean If true, Test Connection button is not displayed on Settings screen. Default is false. CustomSettingFields List<SettingField> List of custom setting fields that are to be displayed on Setting screens. PublisherSettings Models a publisher settings Name Type Description ConnectionName string Unique name, also used for displaying purpose. Url string Url used to connect to the publisher UserName string User name Password string Password TimeoutInMillis int Connection timeout in milliseconds CustomSettingsFieldsValue Dictionary<string, Values for PublisherInfo.CustomSettingFields s string> AdditionalSettingsValues Dictionary<string, string> Additional settings. Use this to store things that are specific to each publisher. PublishingRecord Represents defect information that is going to be published to the publisher. Name Type Description Title string Defect title obtained from Submit Options screen Summary string Defect summary which is a combination of defect description, trace steps and environment

10 information Description string Defect description obtained from Submit Options screen TraceSteps string The trace steps EnvironmentInformation string System information and application information. PublishingResult Models the result of the publishing process Name Type Description RecordId string The optional record ID. If available, will be shown to user. RecordUrl string The optional record URL. If available, will be shown to users. Message string The optional success message. If available, will be shown to users. DisplayText string The display text of the submitted defect. If this value is not null. It will be shown in the successful dialog, otherwise, RecordId will be shown. AdditionalFieldValues SubmissionOptions Dictionary<string, string> SubmissionOption s enum If the publisher wants to save the last selected fields and values so that in the next submission, those values are automatically selected, it should add those fields and values to this dictionary. The selected submission option when submitting a defect, value is either CreateDefect or UpdateDefact Field Name Type Description Name string Unique Name being used to identify the field. FieldType FieldType enum The field type. See description of FieldType enum for reference DisplayName string Display name of the field ParentFieldName string If this is a dependent field, this identifies the parent field. ParentFieldValue string If this is a dependent field, this identifies the value of parent field. DisplayOrder Int The display order of this field IsFoundationField boolean If true: Foundation fields always appear before nonfoundation fields, regardless of their DisplayOrder It must always be shown in the submission screen and cannot be hidden by users Its default value cannot be modified by users; instead its value is persisted across multiple

11 submissions ShowInSubmissionScreen boolean If this is true, the field is displayed in Submission screen. User can change this value by using the Fields Settings screen. IsRequired boolean If this is true, the field is always displayed on submission screen. IsEditable boolean If true, user can change field value. IsDefaultValueEditable boolean If true, user can change default value. Value string The actual value of this field when publishing DefaultValue string The default value of this field HasDependentFields boolean If true, indicate that this field has dependent fields and qtest explorer will attach change event on this field so that when Value property is changed, call IServiceAdapter.GetDependentFields method is called to load the dependent fields. AcceptedValues List<AcceptedValu e> List of accepted values. FieldType Enumeration. Possible values: Unclassified, Dropdown, List, Text, MultiLineText, Integer, Double, Html, Date, Time AcceptedValue Models accepted value for field which is of type Dropdown or List Name Type Description Id string Underlying id value Value string The value to be displayed to user to select Selected boolean Indicate whether this value is selected by user or not Attachment Represents for an attachment object Name Type Description Location string Location of the attachment as it is published. Its value is determined by the rules below. If user selects to attach qtest explorer output, this is the full path to the file If user selects to embed link only, this is the full path to the file after being converted to UNC path If user selects either Dropbox/SharePoint/Confluence storage, this

12 is the URL of the file being uploaded to that storage AttachAsLink boolean If true, indicates that user chose to embed only link or Dropbox/SharePoint/Confluence link of this file to defect description as specified in PublishingRecord.Description. Publishers should consult this property to decide whether it should upload the file specified in Location property to the destination or simply embed the path specified at Location property to the defect description. Default value is false. Size long Specify size of the file. FormattedSize string Formatted file size, for displaying purpose. Content byte[] Content of the file Thread-Safety Your publisher/adapter class must be thread-safe. In addition, you must not assume anything about the number of instances of the publisher/adapter class that qtest explorer might create. In order words, you should not rely on instance variables of your publisher/adapter class. If you need to store states, use the settings passed into the methods of IPubisher or IServiceAdapter. Deployment Each publisher/adapter must be placed in an assembly deployed in the Publishers folder underneath qtest explorer s installation folder. At runtime, qtest explorer automatically discovers publishers/adapters in that folder and uses them to perform defect tracking operations. If qtest explorer is running when you deploy the adapter, you must restart qtest explorer for the publisher/adapter to be picked up. Sample Code Build a Custom Publisher Setup Start Visual Studio.NET and create a new library project, name it Ftp.

13 Add references to the following assemblies (the first is shipped with qtest explorer, the rest are.net assemblies): qtestexplorer.publishing.contracts PresentationCore PresentationFramework WindowBase System.XamlSystem.Xaml System.ComponentModel.Composition Create a custom publisher Create a class named Ftp and implements the IPublisher interface. Make sure you include the ExportAttribute for the class. namespace Ftp using System; using System.Collections.Generic; using System.ComponentModel.Composition;

14 using qtrace.publishing.contracts; using System.Net; using System.Threading.Tasks; [Export(typeof(IPublisher))] [PartCreationPolicy(System.ComponentModel.Composition.CreationPolicy.NonShared)] public class Ftp : IPublisher public IPublishingContext Context set; private get; public PublisherInfo GetMetadata() throw new NotImplementedException(); public VerificationResult Verify(PublisherSettings settings) throw new NotImplementedException(); record) public PublishingResult Publish(PublisherSettings settings, PublishingRecord throw new NotImplementedException(); Note the PartCreationPolicy attribute, which is set to CreationPolicy.NonShared. This tells qtest explorer to create a new instance of this publisher every time it needs to verify publisher connection or to publish the defect. If this attribute is omitted, only one instance of this publisher is created and remains in the memory during the life time of qtest explorer application. Context Context provides access to common functionality of qtest explorer such as showing progress indicator, interacting with Dropbox storage etc. Because FTP operations usually take some time, so we will want to show the progress indicator. Also note that this property, as any other method of the publisher, must be thread-safe. We ll simply use a monitor here. private IPublishingContext _context; private readonly object _contextlock = new object();

15 public IPublishingContext Context get lock (_contextlock) return _context; set lock (_contextlock) _context = value; GetMetadata() Now, let s implement GetMetadata(). This method returns information that qtest explorer needs to know about the publisher in order to properly display it in the Settings screen. Because qtest explorer Integration API 2.0 supports custom setting fields, now we can enhance our FTP publisher to support Transfer Mode and SSL. public PublisherInfo GetMetadata() return new PublisherInfo SmallIconUri = "/Ftp;component/ftp.png", DisplayName = "FTP Publisher", HelpUrl = " CustomSettingFields = new List<SettingField> new SettingField DisplayName = "Transfer Mode", Name = "Mode", FieldType = SettingFieldType.Dropdown, AcceptedValues = new List<SettingAcceptedValue> new SettingAcceptedValue Id = "Active", Value = "Active", new SettingAcceptedValue Id = "Passive", Value = "Passive", new SettingField DisplayName = "Enable SSL", Name = "Ssl", FieldType = SettingFieldType.Checkbox ; Some notes about the above implementation: SmallIconUri specifies the path to an icon which will be bound to Source property of WFP Image element. In this example, we have an image with Built-Action set to Resource and located at the root of the Ftp project. HelpUrl is an optional property indicating the URL where user will navigate to when clicking the Setup Help link in the Connection screen. Our publisher adds two custom fields while retaining the standard Url, User Name and Password fields. The API allows developers to customize there as well. In addition, it also allows

16 developers to indicate which fields are required and must be entered by users before the connection can be saved. Build the project and run qtest explorer, then copy the output assembly Ftp.dll to the Publishers folder within qtest explorer installation folder. Run qtest explorer, open the Settings screen. Click New Connection and you ll see the FTP Publisher in the list of publishers. Select it will show the screen with 2 custom setting fields. Since we haven t implemented Verify(), we can t do anything with this screen yet. Verify() Let s implement Verify(). This method attempts to connect to the server using the provided credentials and connection settings. public VerificationResult Verify(PublisherSettings settings) Context.ShowProgressIndicator(message: "Connecting to FTP..."); try var ftprequest = CreateRequest(settings.Url, WebRequestMethods.Ftp.ListDirectory, settings); using (ftprequest.getresponse()) return new VerificationResult(); finally Context.HideProgressIndicator(); private static FtpWebRequest CreateRequest( string uri, string method, PublisherSettings settings)

17 var ftprequest = (FtpWebRequest) WebRequest.Create(uri); ftprequest.credentials = new NetworkCredential(settings.UserName, settings.password); ftprequest.usepassive = settings.customsettingsfieldsvalues["mode"] == "Passive"; ftprequest.enablessl = bool.parse(settings.customsettingsfieldsvalues["ssl"]); ftprequest.timeout = settings.timeoutinmillis; ftprequest.method = method; return ftprequest; Note that we use Context to display and hide the progress indicator. We also need not to perform the action in a background thread (to make sure the progress indicator, which is executing on the UI thread, keeps showing progress) because qtest explorer invokes this method from a threadpool thread. Custom setting fields are accessed via PublisherSettings.CustomSettingsFieldsValues. All values are serialized asstring, so we must make necessary conversion before using. qtest explorer uses returned value from this method to determine what to display to users. If it returns a VerificationResult, qtest explorer will show a success message (which can be overriden by setting VerificationResult.Message). Otherwise, if it returns null or there is an exception, qtest explorer will show an error message. Build, copy output assembly Ftp.dll to Publishers folder within qtest explorer installation folder and run qtest explorer again. This time, input valid credentials and connection settings, you should have something like this: Publish() Now, if users capture a defect, click on the Submit button, enter title, description on Submit Options screen, select FTP as connection and click Next, there will be an exception. We need to implement the Publish() method

18 public PublishingResult Publish(PublisherSettings settings, PublishingRecord record) Context.ShowProgressIndicator(message: "Publishing to FTP..."); try if string title = "Test"; string desc = "Test Ftp publishing"; string path var tasks = from attachment in Context.CreateAttachmentsFunc(title, desc, path) select Task.Factory.StartNew(() => Upload(settings, attachment)); Task.WaitAll(tasks.ToArray()); return new PublishingResult(); catch (AggregateException e) throw new PublishingException(e.InnerExceptions[0].Message, e.innerexceptions[0]); finally Context.HideProgressIndicator(); private void Upload(PublisherSettings settings, string filepath) var uri = settings.url + (settings.url.endswith("/")? string.empty : "/") + Path.GetFileName(filePath); var ftprequest = CreateRequest(uri, WebRequestMethods.Ftp.UploadFile, settings); using (Stream writer = ftprequest.getrequeststream()) var filecontent = File.ReadAllBytes(filePath); writer.write(filecontent, 0, filecontent.length); First, we invoke the Context.CreateAttachmentsFunc delegate to generate qtest explorer output file(s). Then for each output file, we start a task to upload the file. We could do all the uploads in the calling thread (which is background thread as seen in Verify()), but concurrent uploads should be more efficient than serially performing network-bound operation with mostly idle CPU(s). Besides, to make sure we cascade the appropriate status message to users, we wait for the task(s) to complete and throw an exception if there s any error in any task. If everything s fine, we return a PublishingResult to tell qtest explorer the operation was successful. We can override qtest explorer s success and error message by setting the Message property of the returned PublishingResult or thrown exception. If we return null, qtest explorer will not show any message, assuming that the publisher already takes care of informing users about their action. Build, copy the output assembly Ftp.dll to Publishers folder within qtest explorer installation folder and run qtest explorer again, capture a defect and click Submit. On Submit Options screen, enter required information and click Next, we should see a success message from qtest explorer.

19 That s everything. Below is the full code example for our FTP Publisher. namespace Ftp using System; using System.Collections.Generic; using System.ComponentModel.Composition; using System.IO; using System.Linq; using System.Net; using System.Threading.Tasks; using qtestexplorer.publishing.contracts; [Export(typeof(IPublisher))] [PartCreationPolicy(System.ComponentModel.Composition.CreationPolicy.NonShared)] public class Ftp : IPublisher private IPublishingContext _context; private readonly object _contextlock = new object(); public IPublishingContext Context get lock (_contextlock) return _context; set lock (_contextlock) _context = value; public PublisherInfo GetMetadata() return new PublisherInfo SmallIconUri = "/Ftp;component/ftp.png", DisplayName = "FTP Publisher", HelpUrl = " CustomSettingFields = new List<SettingField> new SettingField DisplayName = "Transfer Mode", Name = "Mode", FieldType = SettingFieldType.Dropdown, AcceptedValues = new List<SettingAcceptedValue> new SettingAcceptedValue Id = "Active", Value = "Active", new SettingAcceptedValue Id = "Passive", Value = "Passive", new SettingField DisplayName = "Enable SSL", Name = "Ssl", FieldType = SettingFieldType.Checkbox ; public VerificationResult Verify(PublisherSettings settings) Context.ShowProgressIndicator(message: "Connecting to FTP...");

20 try var ftprequest = CreateRequest(settings.Url, WebRequestMethods.Ftp.ListDirectoryDetails, settings); using (ftprequest.getresponse()) return new VerificationResult(); finally Context.HideProgressIndicator(); path) public PublishingResult Publish(PublisherSettings settings, PublishingRecord record) Context.ShowProgressIndicator(message: "Publishing to FTP..."); try if (!Directory.Exists(@"C:\temp")) Directory.CreateDirectory(@"C:\temp"); string title = "Test"; string desc = "Test Ftp publishing"; string path var tasks = from attachment in Context.CreateAttachmentsFunc(title, desc, select Task.Factory.StartNew(() => Upload(settings, attachment)); Task.WaitAll(tasks.ToArray()); return new PublishingResult(); catch (AggregateException e) throw new PublishingException(e.InnerExceptions[0].Message, e.innerexceptions[0]); finally Context.HideProgressIndicator(); private void Upload(PublisherSettings settings, string filepath) var uri = settings.url + (settings.url.endswith("/")? string.empty : "/") + Path.GetFileName(filePath); var ftprequest = CreateRequest(uri, WebRequestMethods.Ftp.UploadFile, settings); using (Stream writer = ftprequest.getrequeststream()) var filecontent = File.ReadAllBytes(filePath); writer.write(filecontent, 0, filecontent.length); private static FtpWebRequest CreateRequest( string uri, string method, PublisherSettings settings) var ftprequest = (FtpWebRequest) WebRequest.Create(uri); ftprequest.credentials = new NetworkCredential(settings.UserName, settings.password); ftprequest.usepassive = settings.customsettingsfieldsvalues["mode"] == "Passive"; ftprequest.enablessl =

21 bool.parse(settings.customsettingsfieldsvalues["ssl"]); ftprequest.timeout = settings.timeoutinmillis; ftprequest.method = method; return ftprequest; Build a Custom Adapter Setup Start Visual Studio.NET and create a new library project, name it SampleAdapter. Add references to the following assemblies (the first is shipped with qtest explorer, the second is from.net framework) qtestexplorer.publishing.contracts System.ComponentModel.Composition

22 Create a service adapter Create a class named ServiceAdapter and implements the IServiceAdapter interface. Make sure you include the ExportAttribute for the class. using System; using System.Collections.Generic; using System.ComponentModel.Composition; using qtrace.publishing.contracts; using qtrace.publishing.contracts.adapter; [Export(typeof(IPublisher))] [PartCreationPolicy(CreationPolicy.NonShared)] class ServiceAdapter : IServiceAdapter public PublisherInfo GetMetadata() throw new NotImplementedException(); public List<Field> GetIndependentFields(PublisherSettings settings) throw new NotImplementedException(); public List<Field> GetDependentFields(PublisherSettings settings, string parentfieldname, string parentfieldvalue) throw new NotImplementedException(); public VerificationResult Verify(PublisherSettings settings) throw new NotImplementedException(); public PublishingResult Publish(PublisherSettings settings, PublishingRecord record, IDictionary<string, string[]> fieldsvalues) throw new NotImplementedException(); public bool IsUpdatingDefect get; set; public bool UpdateExistingDefectInformation get; set; GetMetadata() Similar to IPublisher, this method is used by a service adapter to give qtest explorer information about itself. We simply specify the name and 2 icons. Note that we use 2 icons here, the small one is displayed in Settings screen and Submit button while the large one is used in the Submission screen s

23 banner area. If the large icon isn t specified, the small icon is used. Make sure the icons Built Action is set to Resource. public PublisherInfo GetMetadata() return new PublisherInfo SmallIconUri = "/SampleAdapter;component/small.png", LargeIconUri = "/SampleAdapter;component/large.png", DisplayName = "Sample Adapter", SupportUpdatingDefect = true ; Verify() qtest explorer invokes this method to verify the information user provides in the Settings screen. Unlike when implementing IPublisher, you don t have to care about showing/hiding progress indicator (you can t do that anyway because you don t have access to an IPublishingContext like IPublisher does). In an actual adapter, you will attempt to connect to the backend system with the supplied credentials. For our purpose, we will simulate this authentication progress. public VerificationResult Verify(PublisherSettings settings) // Simulate connecting... Thread.Sleep(1000); if (settings.username == "qtrace" && settings.password == "qtrace") return new VerificationResult(); throw new Exception("Not authenticated!"); Go building your adapter and copy its output assembly SampleAdapter.dll to Publishers folder within qtest explorer installation folder. Launch qtest explorer and go to Settings screen. Create a new connection for our adapter. Try input both valid and invalid credentials, you should see qtest explorer provides the correct status to users. In addition, progress indicator is automatically shown and hidden by qtest explorer.

24 GetIndependentFields() and GetDependentFields() This pair of methods is really key for a service adapter. qtest explorer uses these methods to know what fields the service adapter support, the dependencies among them, their type and values and so on. With that knowledge, qtest explorer will then render appropriate screens and controls as well as allow users to customize settings such as default value, show/hide status etc. Normally, your service adapter will go out talking to some backend service in order to populate the returned data expected by qtest explorer. For our sample adapter, we will simulate this communication and return some fake data instead. First, what should GetIndependentFields() return? It returns the metadata for those fields whose values don t depend on the value of any other field. Let s consider a typical defect tracker. Fields like Project, Description, Due Date don t depend on any other field. GetIndependentFields() should therefore return the metadata for these fields. On the other hand, fields like Priority, Component, Version etc. are depedent on the selected Project. The metadata of these fields are to be returned by GetDependentFields(). Besides, among the independent fields, some of them drive the values of dependent fields and some don t. You can specify that in the returned metadata so that whenever the

25 value of such fields is changed, qtest explorer will attempt to invoke GetDependentFields() to reload the values of dependent fields. Specifying field dependency is among the things that can be controlled with metadata returned by these two methods. You can also specify the data type of the field (so that qtest explorer can render it properly), change its display order, force a field to always appear in Submission screen or specify whether a field can have its default value changed. Below are key types and properties of this field metadata model. With that knowledge in mind, let s implement the methods based on the following field description (note that some configurations are left in for demonstration purpose instead of being under practical demand): Project: independent, required and must always be shown in Submission screen Due Date: indepedent, shown in Submission screen by default Priority: dependent on Project, shown in Submission screen by default

26 The implementation for this model is as follows. public List<Field> GetIndependentFields(PublisherSettings settings) // Simulate connecting... Thread.Sleep(1000); return new List<Field> new Field Name = "project", DisplayName = "Project", DisplayOrder = 1, IsFoundationField = true, HasDependentFields = true, FieldType = FieldType.Dropdown, AcceptedValues = new List<AcceptedValue> new AcceptedValue Id = "1", Value = "qtest explorer", new AcceptedValue Id = "2", Value = "qtest",, new Field Name = "date", DisplayName = "Due Date", DisplayOrder = 2, ShowInSubmissionScreen = true, FieldType = FieldType.Date, IsDefaultValueEditable = false ; public List<Field> GetDependentFields(PublisherSettings settings, string parentfieldname, string parentfieldvalue) // Simulate connecting... Thread.Sleep(1000); if (parentfieldname!= "project") return new List<Field>(); return new List<Field> new Field Name = "priority", DisplayName = "Priority", DisplayOrder = 3, FieldType = FieldType.Dropdown, ShowInSubmissionScreen = true, AcceptedValues = new List<AcceptedValue> new AcceptedValue Id = "1", Value = parentfieldvalue == "1"? "Major" : "High",

27 ; new AcceptedValue Id = "2", Value = "Medium", new AcceptedValue Id = "3", Value = parentfieldvalue == "1"? "Minor" : "Low", Note the followings: Project field: IsFoundationField value is true, meaning this field is always shown and won t appear in the Fields Settings screen (can t modify its default value, can t hide it); HasDependentFields value is true, meaning whenever the value of this field is changed by users, qtest explorer will invoke GetIndependentFields() with the name and selected value of it Priority field: the AcceptedValues varies depending on the currently selected project. DisplayOrder of fields should be specified to explicitly control their relative orders; not specifying DisplayOrder will have unspecified behavior due to the complicated interweaving logic among field dependencies, show/hide status, explicit order etc ShowInSubmissionScreen is true for Due Date and Priority, meaning they will appear in the Submission screen by default (although users can hide them in the Fields Settings screen) IsDefaultValueEditable is true for Due Date, meaning users can t change the default value for this field. Instead, qtest explorer will persist the last selected value and use it in subsequent submissions Build the adapter, copy its output SampleAdapter.dll to Publishers folder within qtest explorer installation folder and launch qtest explorer. Capture a defect and click Submit on editor toolbar. On submission screen, choose Create new defect option. qtest explorer will render the adapter based on the returned field metadata. Enter title, description. Select another project and you ll see qtest explorer reload and update the priority list. Best of all, we have access to many goodies like Dropbox integration, additional file attachment, fields settings etc.

28

29 Submit() Now that we have allowed users to manage fields, attachments and select values for submission, we re ready to implement the Submit() method. This method receives selected field values, qtest explorer attachments and attachment options and submits everything to a backend system. Normally, this means posting to a REST endpoint or invoking some XML web service. Below is a brief description of the parameters for this method: settings: information provided by users in the Settings screen (or any additional info stored by any method of this service adapter) record: include title, description, trace steps, environment information, whether all screens are included, export format and image quality (some of them are obtained from Submit Options screen) fieldsvalues: the map of field name and their value(s). Note that value is an array, values of singlevalued fields are stored in the first position. attachments: list of qtest explorer attachments. Note that as users might have selected to embed only link or Dropbox link of some attachments (as opposed to attach their entire files), your code must take this into account when submitting the defect. For our purpose, we simply return the success status with a generated defect ID which is shown to users. public PublishingResult Publish( PublisherSettings settings, PublishingRecord record, IDictionary<string, string[]> fieldsvalues, List<Attachment> attachments) // Simulate connecting... Thread.Sleep(1000); return new PublishingResult RecordId = new Random().Next(1, 100).ToString(), Message = "Published successfully!" ; Build the library, copy the output SampleAdapter.dll to Publishers folder within qtest explorer installation folder and launch qtest explorer. Capture and submit a defect, you should see the following screen.

30 That s everything. Below is the full code example for our sample service adapter. namespace SampleAdapter using System; using System.Collections.Generic; using System.ComponentModel.Composition; using System.Threading; using qtestexplorer.publishing.contracts; using qtestexplorer.publishing.contracts.adapter; [Export(typeof(IServiceAdapter))] [PartCreationPolicy(CreationPolicy.NonShared)] public class ServiceAdapter : IServiceAdapter public PublisherInfo GetMetadata() return new PublisherInfo SmallIconUri = "/SampleAdapter;component/small.png", LargeIconUri = "/SampleAdapter;component/large.png", DisplayName = "Sample Adapter", SupportUpdatingDefect = true ; public VerificationResult Verify(PublisherSettings settings) // Simulate connecting... Thread.Sleep(1000); if (settings.username == "qtrace" && settings.password == "qtrace") return new VerificationResult(); throw new Exception("Not authenticated!"); public List<Field> GetIndependentFields(PublisherSettings settings) // Simulate connecting... Thread.Sleep(1000); return new List<Field> new Field Name = "project", DisplayName = "Project", DisplayOrder = 1, IsFoundationField = true, HasDependentFields = true, FieldType = FieldType.Dropdown, AcceptedValues = new List<AcceptedValue> new AcceptedValue Id = "1", Value = "qtest explorer", new AcceptedValue Id = "2", Value = "qtest"

31 ;,, new Field Name = "date", DisplayName = "Due Date", DisplayOrder = 2, ShowInSubmissionScreen = true, FieldType = FieldType.Date, IsDefaultValueEditable = false public List<Field> GetDependentFields(PublisherSettings settings, string parentfieldname, string parentfieldvalue) // Simulate connecting... Thread.Sleep(1000); if (parentfieldname!= "project") return new List<Field>(); return new List<Field> new Field Name = "priority", DisplayName = "Priority", DisplayOrder = 3, FieldType = FieldType.Dropdown, ShowInSubmissionScreen = true, AcceptedValues = new List<AcceptedValue> new AcceptedValue Id = "1", Value = parentfieldvalue == "1"? "Major" : "High", new AcceptedValue Id = "2", Value = "Medium", new AcceptedValue Id = "3", Value = parentfieldvalue == "1"? "Minor" : "Low", ; public PublishingResult Publish( PublisherSettings settings, PublishingRecord record, IDictionary<string, string[]> fieldsvalues, List<Attachment> attachments) // Simulate connecting... Thread.Sleep(1000); return new PublishingResult RecordId = new Random().Next(1, 100).ToString(),

32 ; Message = "Published successfully!" public bool IsUpdatingDefect get; set; public bool UpdateExistingDefectInformation get; set;