NetResults Tracker SDK
API Sample

The following is a sample program that calls the API object and adds a record to "pteval" workgroup. This sample code uses JavaScript language. You can use any language, such as JavaScript, VBScript, Visual Basic etc., to write the user application (the program calling the API). If you wish to try out this example, you can use the sample JavaScript file (PTSample.js) in the Samples directory.

// Error Handling. This sample has some simple error handling routine.
// Write your own detailed error handling routine(s) as needed.

// Return Status (an integer value) from calling the API.
var iReturnStatus = 0;

// Variable to hold the API (COM DLL) object.
var objAPI;

try {

       // NetResults Tracker SDK uses a COM DLL named ProblemTrackerAPI.dll.
       // It should be created/instantiated first using the CreateObject method before using the API.
       // Different languages use different ways to create an object. Call the appropriate method in your language.
       // PTClient is the only class available in the ProblemTrackerAPI DLL.
       objAPI = WScript.CreateObject("ProblemTrackerAPI.PTClient");

       // Set the API properties. Click here to review the full set of API Properties and Methods.

       // The full URL to the workgroup. It is similar to what you type in the web browser to access the workgroup.
       // Replace the "localhost" with your web server (with port number if any) and "pteval" with your workgroup.
       // You can also use "https://" instead of "http://" if your workgroup allows secured connection (SSL).
       objAPI.WorkgroupURL = "http://localhost/pteval/";

       // Use Field Names (true) or Field Labels (false).
       // If you don't set this property, Field Labels will be used.
       // Example: "Title" is a field label, while "Text1" is a field name in NetResults Tracker.
       objAPI.UseFieldNames = false;

       // Begin a Record. This method denotes the starting of a record to be added and
       // should be called always before adding a record and setting values for the record.
       objAPI.BeginAddRecord();

       // Set the Project name for the record.
       // If this workgroup has more than one Project, then this property should be set, otherwise it is optional.
       // If not supplied, the only Project available will be used. This Project should be visible to the API User.
       objAPI.Project = "Website Development";

       // Set the Form name for the record.
       // If this workgroup has more than one Form, then this property should be set, otherwise it is optional.
       // If not supplied, the only Form available will be used. This Form should be visible to the API User.
       objAPI.Form = "Issue";

       // We set values for different fields of a record that are defined for a Form.
       // All values passed to these methods are strings (no other data type is allowed).
       // To set values for different field types, you can either use SetField method
       // or use the appropriate method (per field type).

       // Set a Text field with label "Title".
       objAPI.SetTextField("Title", "This is a test record added by API.");

       // If UseFieldNames property is set to True, then instead of using "Title" as
       // the first parameter in SetTextField, use "Text1".
       // Example: objAPI.SetTextField("Text1", "This is a test record added by API.");
       // All other methods should also use the appropriate Field Names.

       // Set a Text Field with label "ShortDesc".
       objAPI.SetTextField("ShortDesc", "This is a short description for the record.");

       // Set the History Pulldown field with label "Product".
       objAPI.SetPulldownField("Product", "MyProduct");

       // Set the Status Field with label "Status".
       objAPI.SetStatusField("Status", "Reported");

       // Set the Assignee Field with label "Assigned To".
       objAPI.SetAssigneeField("Assigned To", "qa_mgr");

       // Set a Pulldown field with label "Platform".
       objAPI.SetPulldownField("Platform", "Windows NT");

       // Set a Pulldown field with label "Request Type".
       objAPI.SetPulldownField("Request Type", "Enhancement");

       // Set a Date field with label "Date Reported".
       objAPI.SetDateField("Date Reported", "10/16/2006 11:00:00 PM");

       // Set a TextArea (BigText) Field with label "Description".
       objAPI.SetTextAreaField("Description", "Setting description to test API...");

       // Set a RelNum field with label "Reported in Version".
       objAPI.SetRelNumField("Reported in Version", "6", "0", "0", "Beta 16");

       // Set a Float Field with label "Estimated Size".
       objAPI.SetFloatField("Estimated Size", "5.6");

       // Set an Integer Field with label "Duplicate Record #".
       objAPI.SetIntegerField("Duplicate Record #", "78");

       // Set a Pulldown field with label "Priority".
       objAPI.SetPulldownField("Priority", "3");

       // Now add attachments, if needed. Both File and URL attachments can be added.
       // Any number of attachments can be added, but be aware of the time it takes
       // to save the attachments and the size limit of each attachment.

       // File Attachment. Full path to the file being attached, plus comment describing file.
       // When running this, change these to reference real files or comment out the next two lines.
       objAPI.AttachFile("C:\\Attachments\\screenshot.jpg", "Screen shot of the error message");
       objAPI.AttachFile("C:\\Attachments\\error.doc", "Error document");

       // URL Attachment.
       objAPI.AttachURL("http://www.anyserver.com/anypage.htm", "Error occurred in this URL");

       // If the Alerts feature is purchased and enabled, you can set an alert for the record being added.
       // The alert settings specified below will override the default alert settings (for the Product
       // field value set above) which are configured in NetResults Tracker. If you simply want the record
       // created with the default alert settings, you do not need these calls.
       // Click here for more methods related to Alerts.

       // Begin to add an alert for this record.
       objAPI.BeginAddAlert();

              // Set a relative alert after 5 hours from Date Reported. Notify the default Users
              // as well as the Users and Admins User Groups.
              objAPI.SetRelativeAlert("5", "hour", "after", "Date Reported", "<default>", "Admins,Users");

              // Repeat the alert setting for every 3 hours and stop after 6 alerts.
              objAPI.SetRepeatAlert("3", "hour", "6");

              // Set additional information on alert.
              objAPI.SetAlertAdditionalInfo("This alert will stop after 6 notifications.");

       // End to add an alert for this record.
       objAPI.EndAddAlert();

       // End a Record. This method denotes that we are ending a record and should be
       // called before calling the Execute() method to add a record.
       objAPI.EndAddRecord();

       // Call Execute method with "AddRecord" parameter (only one allowed now) to add this record.
       // This method will return an integer (1 if successfully added this record, 0 if failed).
       iReturnStatus = objAPI.Execute("AddRecord");

       // Check the return status and do appropriate action(s).
       if (iReturnStatus == 0) {

              // If the return status is 0 (failure), then call "FaultCode" and "FaultMessage" to know more about the error.
              WScript.Echo("Fault Code: " + objAPI.FaultCode);
              WScript.Echo("Fault Message: " + objAPI.FaultMessage);

       } else {

              // If the return status is 1 (success), then call "ReturnMessage" to get the success message.
              WScript.Echo(objAPI.ReturnMessage);
       }

       // Destroy the API object.
       delete(objAPI);

} catch (e) {

       // Error handling routine.
       // Destroy the API object.
       if (typeof(objAPI) != "undefined") {
              delete(objAPI);
       }

       // Display the error message with the error number.
       WScript.Echo("Error occurred. Details: " + e.number + "; " + e.description);

}