August 30, 2007

Simple Create Defect Button in Salesforce.com

Helix ALM

Works with TestTrack 2008 and later

This article includes the steps to add a simple Create Defect button to your Salesforce.com interface, which will automatically generate a defect in TestTrack.

[toc]

Overview

You'll need:
  • Your TestTrack Web server to be publicly accessible from the Internet.
  • The path to your TestTrack Web server installation. If you're familiar with how web servers work and your IT environment, you can probably guess this. If not, ask the TestTrack administrator or IT staff for help.
  • A valid TestTrack projed id. This can be obtained from the TestTrack Admin Utility, or by contacting your TestTrack administrator.
  • An existing Salesforce.com account and the necessary permissions to customize the account's global interface.
You'll get:
  • A Create Defect button on the Case Detail screen in Salesforce.com. When clicked, a new defect will be created in TestTrack, populated with information from the case in Salesforce.com.
What we'll do:
  • Create a custom button.
  • Associate the button with the Case Detail screen in Salesforce.com.
  • Hook the button into your TestTrack Web interface.

Create the Custom Button

The first order of business is to create a custom button, for your Salesforce.com account.
  1. Log into your Salesforce.com account.
  2. Click the Setup link in the top-right corner of the browser.
  3. Along the left sidebar, under the App Setup heading, expand the Customize menu, then expand the Cases menu and click the Buttons and Links link.
  4. Click the New button under the Custom Buttons and Links heading.

  • Enter a short, descriptive Label, such as Create Defect.
  • Set Display Type to Detail Page Button, since we're going to associate this with the Case Detail page.
  • Set Behavior to Display in new window. You can use any of the available values here, but this allows a pop-up confirmation screen instead of taking the user from their Salesforce.com view.
  • Set Content Source to URL, since you're going to be pointing directly to your TestTrack Web installation.
  • To keep things simple at first, and make sure we get the button working as expected, set the URL to http://www.seapine.com.
click Save to save your new custom button.

Associate Custom Button with Case Detail Page

Next up, we need to associate our new button with a Case Detail page.
  1. Log into your Salesforce.com account.
  2. Click the Setup link in the top-right corner of the browser.
  3. Along the left sidebar, under the App Setup heading, expand the Customize menu, then expand the Cases menu and click the Page Layouts link.
  4. Find the layout you want to modify, then click Edit. For this example, we're going to modify the generic Case Layout page.

Click the Detail Paage Buttons area, under the Button Section heading, then click Edit Properties.

Under the Custom Buttons heading, select the custom button then click Add then OK. Now let's test out our new button! Go to your Cases tab, click into a Case and you should see the Create Defect button.

Clicking the button should open a new browser window and take you to our site.

Hook into TestTrack

Creating the button was pretty easy, huh? Now comes the more difficult part. All our button does is take us to a website; not very useful. What we'd like it to do is create a defect in TestTrack, so let's get started. You don't need to understand HTTP to do anything outlined here, but some basic understanding of HTTP requests will probably speed up the process. I'll leave that as an exercise for the reader. What we're going to do is hook into your existing TestTrack Web installation, using the Solosubmit interface. Solosubmit is a very powerful yet simple HTML front-end form that allows anyone, anywhere to submit defects to your TestTrack project(s). Most clients already have it setup for external access, but if you don't then you'll need to work with your IT group to at least make ttcgi.exe public to the world. If you remember back when we created the button, we set the destination URL to http://www.seapine.com. We're now going to build a URL that you can use to replace that one. This new URL will automatically pull information from a Salesforce.com case, and send it to TestTrack as a new defect.

Basic URL Construction

Here's the core piece of the URL we're going to build. We'll then add data pieces to fill out the defect. http://yourserver/scripts/ttcgi.exe?command=ReportBug&ReturnPage=SoloSubmitScreen&databaseid=1
  • http://yourserver/scripts/ttcgi.exe - This is the public path to your TestTrack Web installation. An example (this link won't actually work) would be http://ttp.seapine.com/scripts/ttcgi.exe. If you're running on Apache, most likely you'll need to replace 'scripts' with 'cgi-bin'; http://ttp.seapine.com/cgi-bin/ttcgi.exe
  • ?command=ReportBug - We're giving a command to the cgi. In this case, we're using the same command that a Solosubmit form uses, but we're not going to make you fill out a form.
  • ReturnPage=SoloSubmitScreen - Setting the resulting page, after the cgi command executes. SoloSubmitScreen is code for 'Take the user back to the Solosubmit form'. A better option for this example is probably just a static html page on your web server. Something like ReturnPage=DefectCreated.htm.
  • databaseid=1 - We have to tell TestTrack which project the defect should be created in. To get this id, log into your TestTrack Admin Utility, click the Projects button and you'll see the id's in the left-most column.

Adding defect data

Right now, we have a URL that won't work! We're telling TestTrack to create a defect, but not giving it any information to actually populate the defect fields. To provide field data, we need to expand on our basic URL. The general syntax is &field_X=Y
  • X - An integer, representing the internal FieldId for the field we want to update. See the Appendix for details on figuring out FieldID values for your TestTrack project.
  • Y - Data we want to populate to the field.
Example: http://ttp.seapine.com/scripts/ttcgi.exe?command=ReportBug &ReturnPage=SoloSubmitScreen&databaseid=1&field_2=Case Subject This will populate the Summary field of the new Defect with the string 'Case Subject'.

Adding user data

Part of any defect is knowing who created it. So, while not required, we should probably send some user information about the case to TestTrack when we create the defect. Below is the list of supported parameters.
  • fnam - first name
  • lnam - last name
  • cmpy - company name
  • emal - email address
  • phon - primary phone number
If you send any or all of this information with your request, TestTrack will attempt to match it against existing users/customers by name and/or email. If not found, a Local Customer will be created in the project. This user is then marked as the Entered By and Found By user for the new defect. If you don't send this information, Entered By and Found By will be set to null. Example: http://ttp.seapine.com/scripts/ttcgi.exe?command=ReportBug &ReturnPage=SoloSubmitScreen&databaseid=1&fnam=Matt&lnam=Harp &cmpy=Seapine&emal=mattharp@somewhere&phon=123-456-7890

Pull it all together

All that's left to do now is to construct a complete URL for the Salesforce.com button. Going back to our button definition, notice the Insert Merge Field drop-down towad the middle of the page? That drop-down lets you merge case data into the URL on the fly, at the time the button is clicked. This allows us to essentially generate a URL specific to each case, as we click the Create Defect button. Just pull it down, select an entry and it populates the text box with the appropriate code. Using this, you can customize the button to pass along all kinds of information to TestTrack, when creating the defect. I've listed an example URL below, that you can try out on your own. Note that when sending data to TestTrack drop-down fields, the value must already exist in the drop-down, or TestTrack will ignore it and leave the field empty. http://ttp.seapine.com/scripts/ttcgi.exe?command=ReportBug &ReturnPage=SoloSubmitScreen&databaseid=1&field_2={!Case.Subject} &field_54={!Case.Description}&field_4={!Case.Type}&field_5={!Case.Priority} &field_25={!Case.CaseNumber}&fnam={!Case.OwnerFirstName} &lnam={!Case.OwnerLastName}&emal={!Case.OwnerEmail} &phon={!Case.OwnerPhone}

Appendix - Finding FieldIDs

Finding FieldID values is not difficult, but the method you use depends on what database platform you're running with TestTrack. Some common fields are listed below, and should be valid but no promises. The labels below come from a default project created on any platform. If you've changed field labels, be sure to take that into consideration. For example, if you renamed Product to Project, it's FieldID is still 3.
  • Summary - 2
  • Disposition - 43
  • Product - 3
  • Component - 24
  • Type - 4
  • Priority - 5
  • Severity - 33
  • Reference - 25
  • Found in Version - 24
  • Description - 54
  • Steps to reproduce - 58
  • Other HW/SW - 64
  • Custom fields - start at 301, don't count on the first custom field you create to be 301.

Native (Codebase)

You need a tool like FoxPro, to read the flat-file tables. Open the FLDDFNTN.TTT file, within your project database. On Windows, default path would be C:Program FilesSeapineTestTrackTTServDBTTDbs<project name>FLDDFNTN.TTT.

RDBMS

If you're using one of the RDBMS platforms we support, you can run the following SQL query to get a complete list of fields.
select Shortname, FieldID from FLDDFNTN where projectid = <get from the TTPROJECTS table> order by Shortname asc
Note: These instructions are provided as is; Seapine does not provide support for samples.