>

API Details and Examples

The following documentation provides api details for each request and working examples for your existing system if the api is enabled.

Fit Objects used by API calls
The filterStruct object is used to define a filter, when requesting a list of objects from the Fit system.
It replicates the filter form which is used within the web interface for ATS (parameters can be also be found from the source of that form).

filterStruct parameters consist of tag names which define the fields (default and custom) in the system and qualitative tags for comparing those fields.

field tag - default and custom fields have internal tags within the system. ( View )

qualitative tags - Additional qualitative tags exist, depending on the type of field that is being used in the filter :
Type Tag Name Description
ALL mSp-# Special tag (denoting field #) differing functionality, depending on values listed below.
    Null  - filter for objects where field is null or zero.
    NotNull  - filter for objects where field is NOT null or zero.
    FieldChanged - field changed in last update
    FieldUnchanged - field did not change last update
    
    Example:     filter on objects with empty/null subject field
    filterStruct : {
        msp-2=Null  
    }
        
numeric/date _Op the field tag preceded by the "_Op" suffix denotes an operator for the given field tag

Note: Default fields do not require the underscores.
    1: Less Than
    2: Less Than or Equal To
    3: Equals
    4: Greater Than or Equal To
    5: Greater Than
    6: Not Equal
    
    Example:   filter to search for objects where Date Entered is Jan 1, 2001 
    filterStruct : {
        mDateEntered: 2001/01/01,
        field18_Op: 3
    }
          
numeric/date _AndOr The field tag preceded by the "_AndOr" suffix denotes an operator for combining two field valuse. A second tag value with suffic "tag2" allows you to implement AND/OR comparisons and requires a second qualitative tag appended by "2" (custom fields) or "_2" (default fields)

Note: Default fields do not use underscores.
    1: And
    2: OR
    
    Example below
          
numeric/date _2Op The field tag preceded by the "_2Op" suffix denotes a second operator for the given tag and requires a second qualitative tag appended by "2" (custom fields) or "_2" (default fields) .
Note: Default fields do not require the underscores.
    numeric:                                          date:
    1: Less Than                                      1: is before
    2: Less Than or Equal To                          2: is or is before
    3: Equals                                         3: is
    4: Greater Than or Equal To                       4: is or is after
    5: Greater Than                                   5: is after
    6: Not Equal                                      6: isn't
    
    Example:   filter to search for objects where field18>90 AND field18<=99
    filterStruct : {
        field18: 90,
        field18_Op: 5,
        field18_AndOr: 1
        field18_2: 90,
        field18_Op: 5
     }
          

The bugStructin object is used to define field values for an object, when an update is made to the Fit system (ie: newBug/updateBug) .

bugstructIn parameters consist of internal tag names which define the fields (default and custom) in the system with associated field values for the change.
Field ids and internal tag names can be found ( here )

Example: bugStructIn defining a bug change where the AssignedTo user is changed to "Joe", the Requested Due Date is changed to Dec 31, 1977, and custom field with id 18 is set to "custom value".
bugStructIn: {
  mStatus: "Joe",
  mRequestedDueDate: "1977/12/31",
  field18: "custom value"
}
API Calls
GET/POST /restapi/fitapp/getId

Retrieves details for an object in desired system.

Property name Ordinality Type Description
mId required integer The id number of the desired object
CONTEXT optional integer The track/contextId for the desired object.
Default: 0
loginid optional string The user loginid used to make the request. This setting is mandatory if API "Restrict REST API by Login Id" is enabled.
password optional string The user password, matching login id, used to make the request. This setting is mandatory if API "Restrict REST API by Login Id" is enabled.
showAssignToOptions optional string This option with any value will return a list of users which are visible for the user making the request.
showHistory optional string This option with any value will return a full history object with all fields for each historical entry.
fullFieldDetails optional any value This option with any value returns a fullFieldDetails object with the following:
          id: field id within system
          type: numeric field type within system
          fieldTag: the html name used on form submits
          feildLabel: the field label used in the system
          value: current field value for this object        
          
Default is not to include.

Example Request:
{
  "CONTEXT": "0",
  "mId": "1"
}
Example Response:
{
  "status": "OK",
  "bugStruct": {
    "mId": "1",
    "mUniqueProjectId": "1",
    "mContextId": "0",
    "mPriorityStringForm": "3 - Medium",
    "mSubject": "This is a Rest call",
    "mCurrentAssignedTo": "Leia",
    "mDateLastModified": "Mar 24 2017 (15:28)",
    "mCurrentStatus": "In Work",
    "mPriority": "3",
    "mDateEntered": "Mar 16 2017 (17:43)",
    "mEnteredBy": "admin",
    "mProject": "National",
    "mArea": "Core",
    "mVersion": "",
    "mEnvironment": "Development",
    "mRequestedDueDate": "",
    "mActualCompletionDate": "",
    "mEstimatedHours": "0.0",
    "mActualHours": "0.0",
    "mPercentComplete": "0.0",
    "mParent": "0",
    "mLastModifiedBy": "Luke",
    "mElapsedTime": "1392",
    "mNotifyList": "example@alceatech.com",
    "mRejectedCount": "0",
    "mRankCache": "0.0",
    "mNumAttachments": "0",
    "mAttachments": [],
    "field18": "-99.0",
    "field39": "$0.00"
  }
}
Return Subject for specified object :
Context:
Login:
Password:
Bug Id:
Show AssignTo Options:
Full Field Details:
Show History:
Returned Subject :

POST /restapi/fitapp/getBugList

Retrieves a list of objects (with desired fields) which match a given filter.

Property name Ordinality Type Description
mId required integer The id number of the desired object
CONTEXT optional integer The track/contextId for the desired object.
Default: 0
loginid optional string The user loginid used to make the request. This setting is mandatory if API "Restrict REST API by Login Id" is enabled.
password optional string The user password, matching login id, used to make the request. This setting is mandatory if API "Restrict REST API by Login Id" is enabled.
mColumn optional string This field consists of a list of numerical ids (separated by spaces) representing the field ids for which data will be included for each object.
If this field is not included, a full list of fields will be returned for each object.
All internal custom field ids are incremented by 100 to distinguish from default fields.
Example: "1 2 6 118" will return data for "Id Subject Priority and customField18"
showHistory optional string This option with any value will return a history object with historical values for each historical entry (fields are dictated by mColumn).
showDiscussion optional string This option with any value will return a discussion object (comment fields) with historical values for each historical entry (fields are dictated by mColumn).
filterStruct optional filterStruct This option defines the filter used to return the list of objects. If included, only objects which pass a filter defined by this object will be returned.

Example Request:
{
  "CONTEXT": "0",
  "showHistory": "false",
  "showDiscussion": "false",
  "offset": "",
  "groupSize": "10",
  "filterStruct": {
    "mPriority": "3",
    "mStatus": [
      "Assigned",
      "Acknowledged"
    ]
  }
}
Example Response:
{
  "status": "OK",
  "totalCount": "1",
  "offset": "0",
  "groupSize": "10",
  "filterDefinition": "Status = [Assigned, Acknowledged], Priority = 3",
  "bugStructList": [
    {
      "bugStruct": {
        "mId": "4829",
        "mUniqueProjectId": "P1:4829",
        "mContextId": "0",
        "mPriorityStringForm": "3 - Medium",
        "mSubject": "",
        "mCurrentAssignedTo": "123",
        "mDateLastModified": "Aug 02 2019 (10:57)",
        "mCurrentStatus": "Assigned",
        "mPriority": "3",
        "mDateEntered": "May 02 2019 (17:14)",
        "mEnteredBy": "admin",
        "mProject": "Project1",
        "mArea": "Core",
        "mVersion": "",
        "mEnvironment": "Development",
        "mRequestedDueDate": "",
        "mActualCompletionDate": "",
        "mEstimatedHours": "0.0",
        "mActualHours": "0.0",
        "mPercentComplete": "0.0",
        "mParent": "0",
        "mLastModifiedBy": "admin",
        "mElapsedTime": "615",
        "mNotifyList": "",
        "mRejectedCount": "0",
        "mRankCache": "0.0",
        "mNumAttachments": "0",
        "mAttachments": [],
        "field3": "1.0",
        "field18": "-99.0",
        "field6": "jerry",
        "field39": "$1.00"
      }
    }
  ]
}
Return List of bugs matching given Priority :
Context:
Login:
Password:
Priority: **space separated list of ids
Status: **comma separated list of Status
Column Restriction: **comma delimited id list (add 100 for custom fields)
Show History: **optional, overrides bugHistory Column
Show Discussion: **optional
offset: **optional (start list at given offset)
groupSize: ** defaults to groupSize from profile (<0 will return all items)
Returned Items :

POST /restapi/fitapp/newBug

Creates a new object in desired system.

Property name Ordinality Type Description
CONTEXT optional integer The track/contextId for the desired object.
Default: 0
loginid optional string The user loginid used to make the request. This setting is mandatory if API "Restrict REST API by Login Id" is enabled.
password optional string The user password, matching login id, used to make the request. This setting is mandatory if API "Restrict REST API by Login Id" is enabled.
bugStructIn required bugStructIn This object defines the field changes being made to the system.

Example Request:
{
  "CONTEXT": "0",
  "bugStructIn": {
    "mSubject": "Test Issue",
    "mAssignedTo": "admin",
    "mProject": "Project A"
  }
}
Example Response:
{
  "status": "OK",
  "mId": "5671",
  "mUniqueProjectId": "5671",
  "bugStruct": {
    "mId": "5671",
    "mUniqueProjectId": "5671",
    "mContextId": "0",
    "mPriorityStringForm": "",
    "mNumAttachments": "0",
    "mAttachments": [],
    "fullFieldDetails": [
      {
        "id": "1",
        "type": "1",
        "fieldTag": "mId",
        "fieldLabel": "Issue ID",
        "value": "5671"
      },
      {
        "id": "2",
        "type": "1",
        "fieldTag": "mSubject",
        "fieldLabel": "Subject",
        "value": "Test Issue"
      },
      {
        "id": "3",
        "type": "2",
        "fieldTag": "mCurrentAssignedTo",
        "fieldLabel": "Assigned To",
        "value": "admin"
      },
      {
        "id": "4",
        "type": "5",
        "fieldTag": "mDateLastModified",
        "fieldLabel": "Date Last Modified",
        "value": "Jan 08 2021 (18:51)"
      },
      {
        "id": "5",
        "type": "2",
        "fieldTag": "mCurrentStatus",
        "fieldLabel": "Status",
        "value": "Open"
      },
      {
        "id": "6",
        "type": "2",
        "fieldTag": "mPriority",
        "fieldLabel": "Priority",
        "value": "0"
      },
      {
        "id": "7",
        "type": "5",
        "fieldTag": "mDateEntered",
        "fieldLabel": "Date Entered",
        "value": "Jan 08 2021 (18:51)"
      },
      {
        "id": "8",
        "type": "1",
        "fieldTag": "mEnteredBy",
        "fieldLabel": "Entered By",
        "value": "RestApi Request"
      },
      {
        "id": "9",
        "type": "2",
        "fieldTag": "mProject",
        "fieldLabel": "Project",
        "value": "Project A"
      },
      {
        "id": "10",
        "type": "2",
        "fieldTag": "mArea",
        "fieldLabel": "Area",
        "value": ""
      },
      {
        "id": "11",
        "type": "1",
        "fieldTag": "mVersion",
        "fieldLabel": "Version",
        "value": ""
      },
      {
        "id": "12",
        "type": "1",
        "fieldTag": "mEnvironment",
        "fieldLabel": "Environment",
        "value": ""
      },
      {
        "id": "13",
        "type": "5",
        "fieldTag": "mRequestedDueDate",
        "fieldLabel": "Requested Due Date",
        "value": ""
      },
      {
        "id": "14",
        "type": "5",
        "fieldTag": "mActualCompletionDate",
        "fieldLabel": "Actual Completion Date",
        "value": ""
      },
      {
        "id": "15",
        "type": "4",
        "fieldTag": "mEstimatedHours",
        "fieldLabel": "Estimated Hours",
        "value": "0.0"
      },
      {
        "id": "16",
        "type": "4",
        "fieldTag": "mActualHours",
        "fieldLabel": "Actual Hours",
        "value": "0.0"
      },
      {
        "id": "17",
        "type": "1",
        "fieldTag": "mPercentComplete",
        "fieldLabel": "Percent Complete",
        "value": "0.0"
      },
      {
        "id": "18",
        "type": "4",
        "fieldTag": "mParent",
        "fieldLabel": "Parent",
        "value": "0"
      },
      {
        "id": "19",
        "type": "1",
        "fieldTag": "mLastModifiedBy",
        "fieldLabel": "Last Modified By",
        "value": "RestApi Request"
      },
      {
        "id": "24",
        "type": "1",
        "fieldTag": "mElapsedTime",
        "fieldLabel": "Elapsed Time",
        "value": "0"
      },
      {
        "id": "25",
        "type": "1",
        "fieldTag": "mNotifyList",
        "fieldLabel": "Notify List",
        "value": ""
      },
      {
        "id": "27",
        "type": "1",
        "fieldTag": "mRejectedCount",
        "fieldLabel": "Rejected Count",
        "value": "0"
      },
      {
        "id": "28",
        "type": "1",
        "fieldTag": "mRankCache",
        "fieldLabel": "Rank",
        "value": "100.0"
      },
      {
        "id": "23",
        "type": "1",
        "fieldTag": "mAttachments",
        "fieldLabel": "Attachments",
        "value": ""
      },
      {
        "id": "103",
        "type": "4",
        "fieldTag": "field3",
        "fieldLabel": "Cost",
        "value": ""
      },
      {
        "id": "139",
        "type": "11",
        "fieldTag": "field39",
        "fieldLabel": "test sum",
        "value": "$0.00"
      }
    ]
  },
  "message": "5671 has been created."
}

restapi/fitapp/newBug Example

Assign a new issue to a specific person in a specific group, with subject :
Context:
Login:
Password:
Subject:
Project:
Assign To:
Added :

POST /restapi/fitapp/updateBug

Updates the specified object with values defined in the bugStructIn object.

Property name Ordinality Type Description
CONTEXT optional integer The track/contextId for the desired object.
Default: 0
mId required integer The object id being updated.
loginid optional string The user loginid used to make the request. This setting is mandatory if API "Restrict REST API by Login Id" is enabled.
password optional string The user password, matching login id, used to make the request. This setting is mandatory if API "Restrict REST API by Login Id" is enabled.
bugStructIn required bugStructIn This object defines the field changes being made to the system.

Example Request:
bugStructIn: {
  "CONTEXT": "0",
  "bugStructIn": {
    "mId": "5671",
    "mDescription": "Some new Comment",
    "mAssignedTo": "Joe",
    "mStatus": "Assigned"
  }
}
Example Response:
{
  "status": "OK",
  "mId": "5671",
  "mUniqueProjectId": "5671",
  "bugStruct": {
    "mId": "5671",
    "mUniqueProjectId": "5671",
    "mContextId": "0",
    "mPriorityStringForm": "",
    "mNumAttachments": "0",
    "mAttachments": [],
    "fullFieldDetails": [
      {
        "id": "1",
        "type": "1",
        "fieldTag": "mId",
        "fieldLabel": "Issue ID",
        "value": "5671"
      },
      {
        "id": "2",
        "type": "1",
        "fieldTag": "mSubject",
        "fieldLabel": "Subject",
        "value": "Test Issue"
      },
      {
        "id": "3",
        "type": "2",
        "fieldTag": "mCurrentAssignedTo",
        "fieldLabel": "Assigned To",
        "value": "admin"
      },
      {
        "id": "4",
        "type": "5",
        "fieldTag": "mDateLastModified",
        "fieldLabel": "Date Last Modified",
        "value": "Jan 08 2021 (18:51)"
      },
      {
        "id": "5",
        "type": "2",
        "fieldTag": "mCurrentStatus",
        "fieldLabel": "Status",
        "value": "Open"
      },
      {
        "id": "6",
        "type": "2",
        "fieldTag": "mPriority",
        "fieldLabel": "Priority",
        "value": "0"
      },
      {
        "id": "7",
        "type": "5",
        "fieldTag": "mDateEntered",
        "fieldLabel": "Date Entered",
        "value": "Jan 08 2021 (18:51)"
      },
      {
        "id": "8",
        "type": "1",
        "fieldTag": "mEnteredBy",
        "fieldLabel": "Entered By",
        "value": "RestApi Request"
      },
      {
        "id": "9",
        "type": "2",
        "fieldTag": "mProject",
        "fieldLabel": "Project",
        "value": "Project A"
      },
      {
        "id": "10",
        "type": "2",
        "fieldTag": "mArea",
        "fieldLabel": "Area",
        "value": ""
      },
      {
        "id": "11",
        "type": "1",
        "fieldTag": "mVersion",
        "fieldLabel": "Version",
        "value": ""
      },
      {
        "id": "12",
        "type": "1",
        "fieldTag": "mEnvironment",
        "fieldLabel": "Environment",
        "value": ""
      },
      {
        "id": "13",
        "type": "5",
        "fieldTag": "mRequestedDueDate",
        "fieldLabel": "Requested Due Date",
        "value": ""
      },
      {
        "id": "14",
        "type": "5",
        "fieldTag": "mActualCompletionDate",
        "fieldLabel": "Actual Completion Date",
        "value": ""
      },
      {
        "id": "15",
        "type": "4",
        "fieldTag": "mEstimatedHours",
        "fieldLabel": "Estimated Hours",
        "value": "0.0"
      },
      {
        "id": "16",
        "type": "4",
        "fieldTag": "mActualHours",
        "fieldLabel": "Actual Hours",
        "value": "0.0"
      },
      {
        "id": "17",
        "type": "1",
        "fieldTag": "mPercentComplete",
        "fieldLabel": "Percent Complete",
        "value": "0.0"
      },
      {
        "id": "18",
        "type": "4",
        "fieldTag": "mParent",
        "fieldLabel": "Parent",
        "value": "0"
      },
      {
        "id": "19",
        "type": "1",
        "fieldTag": "mLastModifiedBy",
        "fieldLabel": "Last Modified By",
        "value": "RestApi Request"
      },
      {
        "id": "24",
        "type": "1",
        "fieldTag": "mElapsedTime",
        "fieldLabel": "Elapsed Time",
        "value": "2"
      },
      {
        "id": "25",
        "type": "1",
        "fieldTag": "mNotifyList",
        "fieldLabel": "Notify List",
        "value": ""
      },
      {
        "id": "27",
        "type": "1",
        "fieldTag": "mRejectedCount",
        "fieldLabel": "Rejected Count",
        "value": "0"
      },
      {
        "id": "28",
        "type": "1",
        "fieldTag": "mRankCache",
        "fieldLabel": "Rank",
        "value": "0.0"
      },
      {
        "id": "23",
        "type": "1",
        "fieldTag": "mAttachments",
        "fieldLabel": "Attachments",
        "value": ""
      },
      {
        "id": "103",
        "type": "4",
        "fieldTag": "field3",
        "fieldLabel": "Cost",
        "value": ""
      }
    ]
  },
  "message": "5671 has been updated."
}
Update Comment/Status/AssignedTo for an existing issue :
Context:
Login:
Password:
Id:
Comment:
Status:
AssignedTo:
Added :

POST /restapi/fitapp/getAttachmentList

Returns a list of attachments for a given object id.

Property name Ordinality Type Description
CONTEXT optional integer The track/contextId for the desired object.
Default: 0
loginid optional string The user loginid used to make the request. This setting is mandatory if API "Restrict REST API by Login Id" is enabled.
password optional string The user password, matching login id, used to make the request. This setting is mandatory if API "Restrict REST API by Login Id" is enabled.
mId required number Defines the id number of the object for which we are listing attachments.

Example Request:
{
  "CONTEXT": "0",
  "mId": "4880"
}
Example Response:
{
  "status": "OK",
  "count": "1",
  "attachments": [
    {
      "Id": "42",
      "Filename": "cat.jpeg",
      "Attachment Date": "Mar 25 2020"
    }
  ]
}
get a list of attachment ids for a given object id :
Context:
Login:
Password:
Id:

POST /restapi/fitapp/getAttachment

Get attachment data for a given attachment id.

Property name Ordinality Type Description
CONTEXT optional integer The track/contextId for the desired object.
Default: 0
loginid optional string The user loginid used to make the request. This setting is mandatory if API "Restrict REST API by Login Id" is enabled.
password optional number the desired attachment id
mid required bugStructIn This object defines the field changes being made to the system.

Example Request:
{
  "CONTEXT": "0",
  "mId": "42"
}
Example Response:
{
  "status": "OK",
  "Id": "42",
  "BugId": "4880",
  "CreatedBy": "admin",
  "Filename": "cat.jpeg",
  "ContentType": "image/jpeg",
  "Comment": "",
  "AttachmentDate": "Mar 25 2020",
  "Version": "1.0",
  "Folder": "-1",
  "FileSize": "46123",
  "base64Content": "REMOVED FOR READABILITY (show Base64Content option)"
}
Get attachment infor for a given attachment id :
Context:
Login:
Password:
Attachment Id:
Show Base64Content (poor readability in browser):
Show as Image (on bottom):
Returned Filename :

restapi/fitapp/updateHierarchy Example

Upload Hierarchy Example :

Instructions: This automates the Field Hierarchy Import utility found inide the hierarchy menus. Please see Admin->Field Hierarchy Import for more documentation about the import file structure.

Context:
Login:
Password:
Parent: (add 100 for custom fields)
Child: (add 100 for custom fields)
CSV Import File:
Single Relationship Rows    Full Relationship Rows
Add any new values to parent/child fields
Clear current parent/child field values before import
Trim whitespace characters from imported values (e.g., " TEST " -> "TEST")