NetResults Tracker SDK
API Properties and Methods

API Properties

The following properties can be used to connect to the workgroup and to get the return status of the AddRecord operation. Most properties do not need to be set (they have appropriate default values for most environments). However, they are available for additional security and/or atypical network configurations (low bandwidth link requiring longer timeouts, etc.). The WorkgroupURL is the only property that must always be set. The Project and Form properties must be set if the workgroup has multiple Projects and/or Forms.

Property Type Actions Required Description Example or Possible Values
WorkgroupURL String Read, Write Yes The full URL of the workgroup with the web server name, port number if applicable, and the workgroup name. http://serverName:90/workgroupName/, https://serverName/workgroupName/
Project String Read, Write Yes Project name for the record to be added. If the 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. Project name. Example: "Maintenance Project"
Form String Read, Write Yes Form name for the record to be added. If the 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. Form name. Example: "Issue"
AddInterface String Read, Write No The interface used to add the record. For now, the only value allowed is "API", which is set by default.
APIVersion String Read N/A The NetResults Tracker SDK version installed on the client. Example: "6.0.0"
CheckCanBeAssigneeForAdd String Read, Write No This property determines whether the user set as Assignee for the record can really be the Assignee. By default this property is set to "true", which means the user set as Assignee should be a member of an user group that has Can Be Assignee For Add privilege. If not the user cannot be set as the Assignee for the record. Setting this property to "false" will allow any valid user in this workgroup to be set as Assignee for the record, even if the user does not have the "Can Be Assignee For Add" privilege. true, false
CheckFieldVisibilityOnAdd String Read, Write No If this property is set to "true" (the default value), then all fields supplied for this record should be visible for the API User. If the property is set to "false", then all fields available for the supplied Form can be set. true, false
SendEmailNotificationsOnAdd String Read, Write No If this property is set to "true" (the default value), then all email notifications for the Add operation (in the Workflow used by the supplied/selected Project and Form) will be triggered. If the property is set to "false", no email notifications on Add operation will be triggered. true, false
IdentityUser String Read, Write No If the API User is set as "Set From API" in the General Preferences section in the workgroup, then this property should be set with a valid user in this workgroup. The user set using this property becomes the API User (even when an API User is already configured in the General Preferences section). User ID. Example: "qa_mgr"
UseFieldNames Boolean Read, Write No By default, the field labels (e.g. Title, Description) will be used to set data in a new record. Setting this property to "true" will allow the field names (e.g. Text1, BigText2) to be used instead of the field labels. true, false
TestRun String Read, Write No Setting this property to "true" will validate all field values for the record, but will not create a new record. Setting this property to "false" (the default value) will create a new record. true, false
ReturnMessage String Read N/A The message string returned from the server after processing the API request to add record(s). String message. Example: "Successfully added 1 new record: (1234) via NetResults Tracker API by Admin".
FaultCode String Read N/A The error or fault code returned from the server if a problem was encountered. This is returned as a string type. An error code/number.
FaultMessage String Read N/A The error or fault message string returned from the server that corresponds to the fault code. An error message.
WindowsAuthenticationType Number Read, Write No The authentication type enforced during use of the API. If this is not specified, Anonymous access will be used. To use this, you must enable and properly configure the corresponding authentication type on the IIS web server. By default, your NetResults Tracker workgroup will be configured for Anonymous authentication only. If you are not very familiar with IIS authentication configuration, please do not set this property.
1 - Basic Authentication
2 - NTLM Authentication
8 - Digest Authentication
10 - Negotiate Authentication

A combination of these values may be used. Example: Setting this property to 3 will result in both Basic and NTLM authentication being used. Setting the property to 12 will use NTLM and Negotiate authentication.

WindowsUserName String Read, Write No The Windows username sent to IIS for authentication at the workgroup level based on the selection made for WindowsAuthenticationType. This is only used if WindowsAuthenticationType is set. Any username recognized by the IIS web server for the WindowsUserAuthentication type.
WindowsUserPassword String Read, Write No The Windows password sent to IIS for authentication at the workgroup level based on the selection made for WindowsAuthenticationType. This is only used if WindowsAuthenticationType is set. Appropriate password for WindowsUserName.
ProxyServer String Read, Write No The HTTP (or HTTPS) proxy server through which the messages are sent and received.
(blank)
<LOCAL_MACHINE>
<CURRENT_USER>
HOST [: PORT]
 
"" (empty string) is the default, which indicates that no proxy server is to be used.
"<LOCAL_MACHINE>" indicates that the proxy configuration specified using the proxycfg utility is to be used.
"<CURRENT_USER>" indicates that the Microsoft Internet Explorer proxy settings for the current user should be used.
"HOST [: PORT]" indicates that the specified host and port should be used (e.g. "myserver:8000").
ProxyUser String Read, Write No The username used for authentication on the proxy server. This is only used if ProxyServer is set. Any username recognized by the ProxyServer.
ProxyUserPassword String Read, Write No The password used for authentication on the proxy server. This is only used if ProxyServer is set. Appropriate password for ProxyUser.
SSLClientCertificateName String Read, Write No A string used to identify a client certificate for use with the SSL protocol. Syntax is "[CURRENT_USER | LOCAL_MACHINE\[store-name\]]cert-name" with the defaults being CURRENT_USER\MY (the same store that Microsoft Internet Explorer uses). The default is an empty string. Any valid SSL client certificate string.
HTTPTimeout Number Read, Write No The timeout in milliseconds used by the HTTP Connector object. By default, this is set to 30000 milliseconds (30 seconds). Any positive integer.
HTTPConnectTimeout Number Read, Write No The time limit in milliseconds to make a connection to the server. It applies only to clients running on Windows XP, Windows 2000, or Windows NT 4.0. Note that the HTTPTimeout property applies after the server is connected. Any positive integer.
TempDirectoryForAttachments String Read, Write No Temporary directory on the NetResults Tracker server for uploading attachments. This directory must exist and should have read and write permissions (even if you have no attachments). We strongly recommend not setting this unless you absolutely must override the default setting. Fully qualified path to a directory (on the server). If not supplied, Windows temp directory will be used.

API Methods

The following methods can be used to set the values of the fields, include attachments, and set alerts for the new record.

Notes:

  1. All values passed in these methods are strings.
  2. Users are identified by the User IDs (e.g. bld_mgr) and not by their first name, last name or full name (e.g. Build Manager).
  3. The date value supplied should match the user preference date format of the API user.
  4. Although most fields are listed as not required, they could be required if the field is required by the NetResults Tracker server (the field has 'Required for Add' set to Yes and is visible for the API User).

Method Parameters Required Description
BeginAddRecord ( ) Yes Start/open a record to add.
EndAddRecord ( ) Yes End the record.
SetField (Name, Value) No Set the value for any field.
SetAssigneeField (Name, Value) No Set the value for the Assignee field.
SetDateField (Name, Value) No Set the value for a Date field.
SetFloatField (Name, Value) No Set the value of a Floating Number field.
SetIntegerField (Name, Value) No Set the value of an Integer field.
SetPulldownField (Name, Value) No Set the value of a Pulldown field.
SetRelNumField (Name, Value1, Value2, Value3, Value4) No Set the value of a Release Number field.
SetReporterField (Name, Value) No Set the value of the Reporter field.
SetStatusField (Name, Value) No Set the value of the Status field.
SetTextField (Name, Value) No Set the value of a Text field.
SetTextAreaField (Name, Value) No Set the value of a TextArea/BigText field.
SetUrlField (Name, Value) No Set the value of a URL field.
SetYesNoField (Name, Value) No Set the value of a Yes/No field.
SetHistoryComment (Value) No Set the history comment of the record. If this method is not used, the text "Added via NetResults Tracker API" will be used.
MakeVisibleToGroups (Group List) No A list of groups separated by commas to which the record will be made visible. E.g. Users,Managers,Admins
AttachFile (FileName, Description) No Attach a file to the record. The path to the file should be fully qualified.
AttachURL (URL, Description) No Attach a URL to the record.
BeginAddAlert ( ) No Start/open an alert for the record. This must be followed by a call to SetNoAlert, SetRelativeAlert, or SetAbsoluteAlert; then, optionally, by call(s) to SetRepeatAlert and/or SetAlertAdditionalInfo; and, finally, by a call to EndAddAlert. See sample code for an example. Only one alert may be set per record.
EndAddAlert ( ) No End the alert.
SetNoAlert ( ) No Call this function to not set an alert for this record. If the default settings on the server are to set an alert, you can use this to override the defaults.
SetRelativeAlert (TimePeriod, TimeDelta, TimeDirection, DateFieldName, UserList, UserGroupList) No Set an alert for the record based on a date field. Possible values are:
TimePeriod: (1 to 99)
TimeDelta: (hour | day | week | month)
TimeDirection: (before | after)
DateFieldName: Any date field
UserList: (<default> | <none> | User list separated by commas. If no users are to be notified, must use <none>)
UserGroupList: (<default> | <none> | User Group list separated by commas. If no user groups are to be notified, must use <none>)
SetAbsoluteAlert (Date-Time, UserList, UserGroupList) No Set an alert at a specific date-time for the record. Possible values are:
Date-Time: Any date with correct format
UserList: (<default> | <none> | User list separated by commas. If no users are to be notified, must use <none>)
UserGroupList: (<default> | <none> | User Group list separated by commas. If no user groups are to be notified, must use <none>)
SetRepeatAlert (RepeatPeriod, RepeatDelta, StopRepeat) No Set repeat and stop options for the alert. This is optional. If not called, the alert will not repeat. Possible value are:
RepeatPeriod: (1 to 99)
RepeatDelta: (hour | day | week | month)
StopRepeat: Any value from 0 to 10 or a date value.
SetAlertAdditionalInfo (Value) No Set the additional info field for the alert. This is optional. If not called, the alert additional info will be blank.
Execute (Command Name) Yes This method sends the request from the API to the server for processing and adds the record into NetResults Tracker. It also receives the response back from the server and passes it to the user application. This method returns an integer (1 - success, 0 - failure). The Command Name parameter value can only be "AddRecord".