API Integration

The following provides information relevant to the integration of the Add API with NetResults Tracker.

• Each record to be added via the Add API must have the property WorkgroupURL set and use the methods BeginAddRecord and EndAddRecord to start and end the new record. The properties Project and Form should be set if the workgroup has more than one Project and/or Form. The Project and Form should be visible to the API User.
• All other properties are optional and can be set according to your workgroup setup.
• Only fields that are available to the Form can be set using the API.
• If the method SetHistoryComment is not set, the following text will be entered as the history comment for the new record: "Added via NetResults Tracker API".
• The Execute method should be called at least once to add record(s) to the workgroup.
• The Execute method returns 1 for success and 0 for failure. More information can be retrieved from the following properties: ReturnMessage (for success), FaultCode and FaultMessage (for failure).

Data Validation on API Records

The validity of the data submitted via the Add API is checked for the following requirements:

• The API User (set in General Preferences on the NetResults Tracker server workgroup or supplied using "IdentityUser" property from the API if "Set From API" option is selected in General Preferences) must be a member of an user group with the Add privilege.
• Field Visibility rules are applied when using the API, only if the "CheckFieldVisibilityOnAdd" property is set to "true" (the default value). Any fields on the Add page that are not visible to the API user cannot be set via the API.
• All fields that have the attribute Required for Add set to "Yes" are required to be set using the API Methods.
• If a Pulldown field has the attribute "Required for Add" set to "Yes", the Pulldown must have a value other than the default.
• A hidden field which is required in the Add page (for the API user) can be set. But the value set will be ignored and the default value for that field will be used.
• All fields are checked for their maximum allowable length and validated for correct format. Details on the correct format for each field type can be found in the "Data Types" section of Customizing the Data Record.
• Date fields must match the date and time formats configured in the API User's Preferences. Example: If the API User has date format set to "mm/dd/yyyy" and time format set to "12 Hour", the values provided for any date fields must be of the form "mm/dd/yyyy [HH:MM:SS] [AM|PM]" (e.g. "02/17/2003" or "02/17/2003 12:52:45 PM").
• All Date fields with the attribute Init for Add set to "Yes" will be initialized.
• Attachments can be added to a record if the user selected for the API User (General Preferences) is a member of an user group that is granted the Add Attachments via Add Page privilege.
• Group Visibility rules will also be applied when using the API.

Special handling is done for the following system fields that are required in all NetResults Tracker records:

• If a value for the Reporter field is not provided for the record via the API, the API User will be entered for this field.
• If a value for the State (Status) field is not provided, the default State for the Project and Form will be used.
• If an user is not specified for the Assignee field, the State Manager for the State will be used.
• If a value for the History Pulldown field is not provided for the record via the API, the option menu item which is the default for this field will be used for the record.
• The value of the Deleted field will always be set to "No".

Other related integration information:

• Notification emails will be sent (only if the property "SendEmailNotificationsOnAdd" is set to true) as per the email rules defined in the Workflow that is used by the Project and Form.
• Alert will be set as per the alert settings defined in the Workflow that is used by the Project and Form.
• Dependency relationship between the pulldown values will not be enforced when using the API.
• Discussions will not be initiated when using the API.
• AutoFill fields will not be set when using the API.

Review the NetResults Tracker Help for more information.