API Operations for Issues

Summary

Operation Name: Retrieve an Issue by Issue Number
Relative API Request Path: ~/api/v1/issues/{includeNotes}/{issueNumber}
HTTP Verb: GET
Description: Retrieve a single Issue by Issue Number.

Operation Name: Retrieve a Collection of Issues for a List of Issue Numbers
Relative API Request Path: ~/api /v1/issues/{includeNotes}/list
HTTP Verb: GET
Description: Retrieve a collection of issues for a delimited list of issue numbers.

Operation Name: Create an Issue
Relative API Request Path: ~/api/v1/issues
HTTP Verb: POST
Description: Create a new Issue.

Operation Name: Update an Issue
Relative API Request Path: ~/api/v1/issues
HTTP Verb: PUT
Description: Update an existing Issue.

Operation Name: Search Issues
Relative API Request Path: ~/api/v1/issues/search
HTTP Verb: POST
Description: Search issues for specified search filters, ordering instructions, and paging boundaries.

Retrieve an Issue by Issue Number

Description: This API method retrieves an Issue from the Issuetrak data store for a specified Issue Number value. The “IssueNumber” parameter must correspond to an existing Issue. If there is no such Issue Number, an error message will be returned with an HTTP response status code of 400.

A successful response will include an HTTP status code of 200 (OK) and a response body containing a serialized ReadIssueDTO instance.

The ReadIssueDTO response instance will contain a collection of ReadNoteDTO instances if the {includeNotes} parameter was specified as true; otherwise, the “Notes” array will be null.

The ReadIssueDTO response instance will contain a collection of ReadIssueUserDefinedFieldDTO representing the user-defined fields defined for the Issue if any user-defined fields are defined.

When retrieving an Issue using the API, no special character decoding (e.g., HTML decoding < as < or > as >) is performed. Therefore, please note that the Subject, Description, and NoteText returned via the API method represents the text as stored within the Issuetrak database. Thus, when retrieving an Issue created through the Issuetrak web interface where HTML encoding of the Subject, Description, and NoteText are performed, the API consumer may desire to perform additional client-side decoding.

Response DTO Schema:

ReadIssueDTO
{
     IssueNumber (integer),
     IssueSolution (string),
     Status (string),
     ClosedBy (string),
     ClosedDate (ISO 8601 string),
     SubmittedDate (ISO 8601 string),
     CauseID (integer),
     SeverityID (integer),
     SLAID (integer),
     ResponseTime (ISO 8601 string),
     SLAComplianceStatus (string),
     IsFirstCallResolution (boolean),
     Notes (array[ReadNoteDTO]),
     UserDefinedFields (array[ReadIssueUserDefinedFieldDTO]),
     ExtensionData (array[CustomKeyValuePairDataElement]),
     Metadata (array[CustomKeyValuePairDataElement]),
     Subject (string),
     Description (string),
     IsDescriptionRichText (boolean),
     IssueTypeID (integer),
     IssueSubTypeID (integer),
     IssueSubType2ID (integer),
     IssueSubType3ID (integer),
     IssueSubType4ID (integer),
     Priority (string),
     AssetNumber (integer),
     LocationID (string),
     SubmittedBy (string),
     AssignedTo (string),
     TargetDate (ISO 8601 string),
     RequiredByDate (ISO 8601 string),
     NextActionTo (string),
     SubStatusID (integer),
     ProjectID (integer),
     OrganizationID (integer),
     ShouldNeverSendEmailForIssue (boolean),
     ClassID (integer),
     DepartmentID (integer),
     SpecialFunction1 (string),
     SpecialFunction2 (string),
     SpecialFunction3 (string),
     SpecialFunction4 (string),
     SpecialFunction5 (string)
}
ReadNoteDTO
{ 
     ExtensionData (array[KeyValuePair[String,Object]]), 
     Metadata (array[KeyValuePair[String,Object]]), 
     NoteID (integer), 
     IssueNumber (integer), 
     CreatedDate (ISO 8601 string), 
     CreatedBy (string), 
     ModifiedBy (string), 
     ModifiedDate (ISO 8601 string), 
     NoteText (string), 
     IsPrivate (boolean), 
     IsRichText (boolean) 
}
ReadIssueUserDefinedFieldDTO
{ 
     ExtensionData (array[KeyValuePair[String,Object]]),
     Metadata (array[KeyValuePair[String,Object]]),
     IssueNumber (integer),
     DisplayName (string),
     UserDefinedFieldID (integer),
     Value (string)
} 
CustomKeyValuePairDataElement
{
     Key (string),
     Value (object)
}

Request HTTP Verb: GET

Response Status Codes:

Success: 200
Invalid Issue Number: 400 (Bad Request, e.g., a negative integer is supplied)
Non-existent Issue: 404
Invalid Issue Number: 422 (Unprocessable Entity, e.g., a non-numeric value is supplied)

Response Properties:

The Notes property represents the collection of ReadNoteDTO instances for the Issue.
The UserDefinedFields property represents the collection of ReadIssueUserDefinedFieldDTO instances for the Issue.
The Metadata property provides a key / value collection of additional data about the API operation and / or the response body.

Sample Request URL: ~/api/v1/issues/101502/false

Sample Response:

{
 “IssueNumber”: 101502,
 “IssueSolution”: null,
 “Status”: “Open”,
 “ClosedBy”: “APIUser”,
 “ClosedDate”: “2015-02-12T11:23:42.193”,
 “SubmittedDate”: “2014-07-30T13:38:10.12”,
 “CauseID”: null,
 “SeverityID”: 3,
 “SLAID”: 1,
 “ResponseTime”: null,
 “SLAComplianceStatus”: “InCompliance”,
 “Notes”: [],
 “UserDefinedFields”: [
  {
   “ExtensionData”: [],
   “Metadata”: [],
   “IssueNumber”: 101502,
   “DisplayName”: “Large Text 1”,
   “UserDefinedFieldID”: 4,
   “Value”: “Large Text 1 User-defined Field Property Updated on: 02/12/2015 11:23:42”
  },
  {
   “ExtensionData”: [],
   “Metadata”: [],
   “IssueNumber”: 101502,
   “DisplayName”: “Large Text 2”,
   “UserDefinedFieldID”: 5,
   “Value”: “Large Text 2 User-defined Field Property Updated on: 02/12/2015 11:23:42”
  }
 ],
 “ExtensionData”: [],
 “Metadata”: [
  {
   “Key”: “APIVersion”,
   “Value”: “12.5”
  },
  {
   “Key”: “QueryDate”,
   “Value”: “2015-02-12T18:54:10.1544752Z”
  }
 ],
 “Subject”: “This Issue's Subject (DB: IssueDescription) was updated on 02/12/2015 11:23:42.ZAOUPDNCAJRDRYKOLTRNPWIMMFASXCJWOIKYYBZWCSAWUGUITWMAZBYDSCHJCUEYAVPIOMPJTUKXWLSFKSZBPIWMJGGWTPUHNBWYRLTGGC”,
 “Description”: “This description was created on 2/12/2015 12:32:30 PM. Random text follows: GTQAPNDPVYYODEJGSOUAABSTFQZDTMUMIQEDEMZUDICNKQXQDAMWPBLFAWVY”,
 “IsDescriptionRichText”: false,
 “IssueTypeID”: 5,
 “IssueSubTypeID”: null,
 “IssueSubType2ID”: null,
 “IssueSubType3ID”: null,
 “IssueSubType4ID”: null,
 “PriorityID”: 1,
 “AssetNumber”: null,
 “LocationID”: "",
 “SubmittedBy”: “Issuetrak”,
 “AssignedTo”: “Issuetrak”,
 “TargetDate”: null,
 “RequiredByDate”: null,
 “NextActionTo”: null,
 “SubStatusID”: 12,
 “ProjectID”: null,
 “OrganizationID”: 1,
 “ShouldNeverSendEmailForIssue”: false,
 “ClassID”: 1,
 “DepartmentID”: 1,
 “SpecialFunction1”: null,
 “SpecialFunction2”: null,
 “SpecialFunction3”: null,
 “SpecialFunction4”: null,
 “SpecialFunction5”: null
}

Retrieve a Collection of Issues for a List of Issue Numbers

Description: This method retrieves a collection of Issues from the Issuetrak data store for a list of specified Issue Numbers. The list is passed to the method via a custom query string parameter of comma-delimited Issue Number values.

The Issue Number values must correspond to existing Issues. If there is no such IssueNumber, an error message will be returned with an HTTP response status code of 400.

A successful response will include an HTTP status code of 200 (OK) and a response body containing a serialized collection of ReadIssueDTO instances.

Each ReadIssueDTO response instance will contain a collection of ReadNoteDTO instances if the {includeNotes} parameter was specified as true; otherwise, the “Notes” array will be null.

Each ReadIssueDTO response instance will contain a collection of ReadIssueUserDefinedFieldDTO representing the user-defined fields defined for the Issue if any user-defined fields are defined.

When retrieving an Issue using the API, no special character decoding (e.g., HTML decoding < as < or > as >) is performed. Therefore, please note that the Subject, Description, and NoteText returned via the API method represents the text as stored within the Issuetrak database. Thus, when retrieving an Issue created through the Issuetrak web interface where HTML encoding of the Subject, Description, and NoteText are performed, the API consumer may desire to perform additional client-side decoding.

Response DTO Schema:

QueryResultsContainer<ReadIssueDTO>
{
     IsPageIndexZeroBased (boolean),
     PageIndex (integer),
     CountForPage (integer),
     PageSize (integer),
     TotalCount (integer),
     Collection (array[ReadIssueDTO])
}
ReadIssueDTO
{
     IssueNumber (integer),
     IssueSolution (string),
     Status (string),
     ClosedBy (string),
     ClosedDate (ISO 8601 string),
     SubmittedDate (ISO 8601 string),
     CauseID (integer),
     SeverityID (integer),
     SLAID (integer),
     ResponseTime (ISO 8601 string),
     SLAComplianceStatus (string),

     Notes (array[ReadNoteDTO]),
     UserDefinedFields (array[ReadIssueUserDefinedFieldDTO]),
     ExtensionData (array[CustomKeyValuePairDataElement]),
     Metadata (array[CustomKeyValuePairDataElement]),
     Subject (string),
     Description (string),
     IsDescriptionRichText (boolean),
     IssueTypeID (integer),
     IssueSubTypeID (integer),
     IssueSubType2ID (integer),
     IssueSubType3ID (integer),
     IssueSubType4ID (integer),
     Priority (string),
     AssetNumber (integer),
     LocationID (string),
     SubmittedBy (string),
     AssignedTo (string),
     TargetDate (ISO 8601 string),
     RequiredByDate (ISO 8601 string),
     NextActionTo (string),
     SubStatusID (integer),
     ProjectID (integer),
     OrganizationID (integer),
     ShouldNeverSendEmailForIssue (boolean),
     ClassID (integer),
     DepartmentID (integer),
     SpecialFunction1 (string),
     SpecialFunction2 (string),
     SpecialFunction3 (string),
     SpecialFunction4 (string),
     SpecialFunction5 (string)
}
ReadNoteDTO
{
     ExtensionData (array[KeyValuePair[String,Object]]),
     Metadata (array[KeyValuePair[String,Object]]),
     NoteID (integer),
     IssueNumber (integer),
     CreatedDate (ISO 8601 string),
     CreatedBy (string),
     ModifiedBy (string),
     ModifiedDate (ISO 8601 string),
     NoteText (string),
     IsPrivate (boolean),
     IsRichText (boolean)
}
ReadIssueUserDefinedFieldDTO
{
     ExtensionData (array[KeyValuePair[String,Object]]),
     Metadata (array[KeyValuePair[String,Object]]),
     IssueNumber (integer),
     DisplayName (string),
     UserDefinedFieldID (integer),
     Value (string)
}
CustomKeyValueDataElement
{
     Key (string),
     Value (object)
}

Request HTTP Verb: GET

Response Status Codes:

Success: 200
Non-existent Issue: 400
Invalid Issue Number List: 422 (Unprocessable Entity, e.g., negative or non-numeric values are supplied)

Response Properties:

The IsPageIndexZeroBased property value is always true. This property is included for use in future API versions.
The PageIndex property value is always 0. This property is included for use in future API versions.
The CountForPage property value is always the same as TotalCount. This property is included for use in future API versions.
The PageSize property value is always the maximum value for a signed, 32-bit integer. This property is included for use in future API versions.
The TotalCount property value is the number of records returned in the collection.
The Collection property is an array containing the ReadIssueDTO instances.
The Notes property represents the collection of ReadNoteDTO instances for the Issue.
The UserDefinedFields property represents the collection of ReadIssueUserDefinedFieldDTO instances for the Issue.
The Metadata property provides a key/value collection of additional data about the API operation and/or the response body.

Sample Request URL: ~/api/v1/issues/true/list/?issueNumbers=104413,104414

Sample Response:

{
 “IsPageIndexZeroBased”: true,
 “PageIndex”: 0,
 “CountForPage”: 2,
 “PageSize”: 2147483647,
 “TotalCount”: 2,
 “Collection”: [
 {
  “IssueNumber”: 104413,
  “IssueSolution”: null,
  “Status”: “Open”,
  “ClosedBy”: null,
  “ClosedDate”: null,
  “SubmittedDate”: “2014-10-07T14:34:48.73”,
  “CauseID”: null,
  “SeverityID”: null,
  “SLAID”: null,
  “ResponseTime”: null,
  “SLAComplianceStatus”: “NotAnSLAIssue”,
  “IsFirstCallResolution”: false,
  “Notes”: [
  {
   “ExtensionData”: [],
   “Metadata”: [],
   “NoteID”: 123093,
   “IssueNumber”: 104413,
   “CreatedDate”: “2014-10-07T14:34:46.923”,
   “CreatedBy”: “Admin”,
   “ModifiedBy”: null,
   “ModifiedDate”: null,
   “NoteText”: “This note was created on 10/7/2014 2:34:47 PM. Random text follows: KUBASVVKXDGSNAJXIKSSEFDPBFRWHNYVEMYTTQDHLNVPGSQMQLGLRYVFRLYNDZCKFKNBCQERGKGRJOIJPFGW”,
   “IsPrivate”: false,
   “IsRichText”: false
  },
  {
   “ExtensionData”: [],
   “Metadata”: [],
   “NoteID”: 123094,
   “IssueNumber”: 104413,
   “CreatedDate”: “2014-10-07T14:34:46.923”,
   “CreatedBy”: “Admin”,
   “ModifiedBy”: null,
   “ModifiedDate”: null,
   “NoteText”: “This note was created on 10/7/2014 2:34:47 PM. Random text follows: YFKSWUMCBCINMPOXSRGWOZILPSZMXJQELINKCYOOYMBRZEYLVNUDFLRYXZCEUAERMDBDCDVTDSYCXQMLTORJPMZZRONCVKTXHKFWCVJRSAAMNOBHNRKGJVCADBLNPSYTZBVMLPIYFZROLMMCNGPDZMNLIESAJVBACGNMT”,
   “IsPrivate”: false,
   “IsRichText”: false
  },
  {
   “ExtensionData”: [],
   “Metadata”: [],
   “NoteID”: 123095,
   “IssueNumber”: 104413,
   “CreatedDate”: “2014-10-07T14:34:46.923”,
   “CreatedBy”: “Admin”,
   “ModifiedBy”: null,
   “ModifiedDate”: null,
   “NoteText”: “This note was created on 10/7/2014 2:34:47 PM. Random text follows: YFKSWUMCBCINMPOXSRGWOZILPSZMXJQELINKCYOOYMBRZEYLVNUDFLRYXZCEUAERMDBDCDVTDSYCXQMLTORJPMZZRONCVKTXHKFWCVJRSAAMNOBHNRKGJVCADBLNPSYTZBVMLPIYFZROLMMCNGPDZMNLIESAJVBACGNMT”,
   “IsPrivate”: false,
   “IsRichText”: false
  },
  {
   “ExtensionData”: [],
   “Metadata”: [],
   “NoteID”: 123096,
   “IssueNumber”: 104413,
   “CreatedDate”: “2014-10-07T14:34:46.923”,
   “CreatedBy”: “Admin”,
   “ModifiedBy”: null,
   “ModifiedDate”: null,
   “NoteText”: “This note was created on 10/7/2014 2:34:47 PM. Random text follows: LQTKAUDUEBKIKESWCYVAYTNHDFHBNGHOSFCCKGYVKLIUSPHKZQJVTZNSDMHVMCHYUVPECPMVAAQNLSPNYXB”,
   “IsPrivate”: false,
   “IsRichText”: false
  },
  {
   “ExtensionData”: [],
   “Metadata”: [],
   “NoteID”: 123097,
   “IssueNumber”: 104413,
   “CreatedDate”: “2014-10-07T14:34:46.923”,
   “CreatedBy”: “Admin”,
   “ModifiedBy”: null,
   “ModifiedDate”: null,
   “NoteText”: “This note was created on 10/7/2014 2:34:47 PM. Random text follows: LQTKAUDUEBKIKESWCYVAYTNHDFHBNGHOSFCCKGYVKLIUSPHKZQJVTZNSDMHVMCHYUVPECPMVAAQNLSPNYXBWXLVTSKZYZDIIDKAWACIJDNVSJZGLXTXPAKBIAVMSQOWWRHKARSNVPSTJPCKSDNBFGTHSJRVEPQSPQZBBPFTE”,
   “IsPrivate”: false,
   “IsRichText”: false
  }
 ],
 “UserDefinedFields”: [
  {
   “ExtensionData”: [],
   “Metadata”: [],
   “IssueNumber”: 104413,
   “DisplayName”: “Large Text 1”,
   “UserDefinedFieldID”: 4,
   “Value”: “Large Text 1 User-defined Field Property Created on: 10/07/2014 02:34:46”
  },
  {
   “ExtensionData”: [],
   “Metadata”: [],
   “IssueNumber”: 104413,
   “DisplayName”: “Large Text 2”,
   “UserDefinedFieldID”: 5,
   “Value”: “Large Text 2 User-defined Field Property Created on: 10/07/2014 02:34:46”
  }
 ],
 “ExtensionData”: [],
 “Metadata”: [
  {
   “Key”: “APIVersion”,
   “Value”: “12.5”
  },
  {
   “Key”: “QueryDate”,
   “Value”: “2015-02-12T19:00:36.0140573Z”
  }
 ],
 “Subject”: “This subject was created on 10/7/2014 2:34:47 PM. Random text follows: JZIQKVNZRGCCRWBYOWOJKQTXAGCRCVPDQTUKCAITMPIJVVZOHGEBQYETFLQETWWWQZMYBRVNNVXVHKCFGOKWQOMRPBERKEZQSMTWJAMQKQNUBILVIL”,
 “Description”: “This description was created on 10/7/2014 2:34:47 PM. Random text follows: JZIQKVNZRGCCRWBYOWOJKQTXAGCRCVPDQTUKCAITMPIJVVZOHGEBQYETFLQETWWWQZMYBRVNNVXVHKCF”,
 “IsDescriptionRichText”: false,
 “IssueTypeID”: 0,
 “IssueSubTypeID”: 0,
 “IssueSubType2ID”: null,
 “IssueSubType3ID”: null,
 “IssueSubType4ID”: null,
 “Priority”: “High”,
 “AssetNumber”: 0,
 “LocationID”: "",
 “SubmittedBy”: “Admin”,
 “AssignedTo”: null,
 “TargetDate”: null,
 “RequiredByDate”: null,
 “NextActionTo”: null, 
 “SubStatusID”: 0,
 “ProjectID”: 0,
 “OrganizationID”: 1,
 “ShouldNeverSendEmailForIssue”: false,
 “ClassID”: 1,
 “DepartmentID”: 1,
 “SpecialFunction1”: null,
 “SpecialFunction2”: null,
 “SpecialFunction3”: null,
 “SpecialFunction4”: null,
 “SpecialFunction5”: null
 },
 {
  “IssueNumber”: 104414,
  “IssueSolution”: null,
  “Status”: “Open”,
  “ClosedBy”: null,
  “ClosedDate”: null,
  “SubmittedDate”: “2014-10-07T14:34:49.383”,
  “CauseID”: null,
  “SeverityID”: null,
  “SLAID”: null,
  “ResponseTime”: null,
  “SLAComplianceStatus”: “NotAnSLAIssue”,
  “Notes”: [],
  “UserDefinedFields”: [
  {
    “ExtensionData”: [],
    “Metadata”: [],
    “IssueNumber”: 104414,
    “DisplayName”: “Large Text 1”,
    “UserDefinedFieldID”: 4,
    “Value”: “Large Text 1 User-defined Field Property Created on: 10/07/2014 02:34:49”
  },
  {
   “ExtensionData”: [],
   “Metadata”: [],
   “IssueNumber”: 104414,
   “DisplayName”: “Large Text 2”,
   “UserDefinedFieldID”: 5,
   “Value”: “Large Text 2 User-defined Field Property Created on: 10/07/2014 02:34:49”
  }
 ],
 “ExtensionData”: [],
 “Metadata”: [
  {
   “Key”: “APIVersion”,
   “Value”: “12.5”
  },
  {
   “Key”: “QueryDate”,
   “Value”: “2015-02-12T19:00:36.0140573Z”
  }
 ],
   “Subject”: “This subject was created on 10/7/2014 2:34:49 PM. Random text follows: KJGKITXBHEXUAPUMPRHEBETDOOVEUHLPVWJHBNXVLIBVUMSNSQVGXEWGPCVUYSGZSHYDFNKCULSTDYJCVHMEMFSQADRZRCXTBBCMNPIFFTMMMCDQTTYRGCNMPICBWLKROZSBVWPGZHYTTFEYAAFYDGNZOQWFMGIUIUYNKBVWE”,
   “Description”: “This description was created on 10/7/2014 2:34:49 PM. Random text follows: KJGKITXBHEXUAPUMPRHEBETDOOVEUHLPVWJHBNXVLIBVUMSNSQVGXEWGPCVUYSGZSHYDFNKCULSTDYJCVHM”,
   “IsDescriptionRichText”: false,
   “IssueTypeID”: 0,
   “IssueSubTypeID”: 0,
   “IssueSubType2ID”: null,
   “IssueSubType3ID”: null,
   “IssueSubType4ID”: null,
   “Priority”: “High”,
   “AssetNumber”: 0,
   “LocationID”: "",
   “SubmittedBy”: “Admin”,
   “AssignedTo”: null,
   “TargetDate”: null,
   “RequiredByDate”: null,
   “NextActionTo”: null,
   “SubStatusID”: 0,
   “ProjectID”: 0,
   “OrganizationID”: 1,
   “ShouldNeverSendEmailForIssue”: false,
   “ClassID”: 1,
   “DepartmentID”: null,
   “SpecialFunction1”: null,
   “SpecialFunction2”: null,
   “SpecialFunction3”: null,
   “SpecialFunction4”: null,
   “SpecialFunction5”: null
  }
 ]
}

Create an Issue

Description: This API method creates a new Issue within the Issuetrak data store. The CreateIssueDTO object conveys the properties of the new Issue along with any Note instances or User-defined Field instances to be associated with the new Issue. If invalid data are supplied, an error message will be returned with a 400 HTTP status code.

Depending on the activation of Issuetrak application features, the only acceptable value for a property associated with an application feature that is not activated is null. For example, for the “Use Issue Classes” feature, if the feature is disabled, the “ClassID” property for the CreateIssueDTO instance must be set to null.

For example, if a non-null value is provided for the “ClassID” property and the “Use Issue Classes” feature is not activated, an error of the following form will be returned:

The specified value for the ‘ClassID' property is invalid because the 'Issue Classes’ feature is not activated.

CreateIssueDTO properties that depend on specific Issuetrak feature activation:

AssetNumber (depends on the “Activate Asset Management” setting)
CauseID (depends on the “Causes” feature in Optional Fields)
ClassID (depends on the “Activate Issue Classes” feature)
DepartmentID (depends on “Use Departments” and “Use Resp Dept” features)
IssueSubTypeID (depends on the “Issue Subtype 1” feature)
IssueSubType2ID (depends on the “Issue Subtype 2” feature)
IssueSubType3ID (depends on the “Issue Subtype 3” feature)
IssueSubType4ID (depends on the “Issue Subtype 4” feature)
LocationID (depends on the “Use Locations” feature)
NextActionTo (depends on the “Next Action” feature in Optional Fields)
- Licensing Note: Only an “Agent” user may be used for assignment for a NextActionTo property value.
ProjectID (depends on the “Use Projects” feature)
RequiredByDate (depends on the “Required By Date” feature in Optional Fields)
SeverityID (depends on the “Use SLAs” feature)
SpecialFunction1 (depends on the “Use Custom Record Table” feature in Optional Fields)
SpecialFunction2 (depends on the “Use Custom Record Table” feature in Optional Fields)
SpecialFunction3 (depends on the “Use Custom Record Table” feature in Optional Fields)
SpecialFunction4 (depends on the “Use Custom Record Table” feature in Optional Fields)
SpecialFunction5 (depends on the “Use Custom Record Table” feature in Optional Fields)
SubStatusID (depends on the “Issue Substatus” feature in Optional Fields)
TargetDate (depends on the “Target Date” feature in Optional Fields)

Please note that the value of the ProjectID property (if specified) must represent the Int32 ID value for an existing project. The existing projects may be retrieved using the “Get All Projects” method of the Projects API controller. Within the Issuetrak UI, the “ProjectID” property refers to the user-assigned project text identifier, not the Int32 value.

The response code on success will be 201 (Created), and the response body will represent the 32-bit integer value representing the ID of the newly-created Issue.

Response DTO Schema:

CreateIssueDTO
{
  ShouldSuppressEmailForCreateOperation (boolean),
  Notes (array[CreateNoteWithIssueDTO]),
  UserDefinedFields (array[CreateIssueUserDefinedFieldDTO]),
  SubmittedDate (ISO 8601 string),
  EnteredBy (string),
  SeverityID (integer),
  Subject (string),
  Description (string),
  IsDescriptionRichText (boolean),
  IssueTypeID (integer),
  IssueSubTypeID (integer),
  IssueSubType2ID (integer),
  IssueSubType3ID (integer),
  IssueSubType4ID (integer),
  Priority (string),
  AssetNumber (integer),
  LocationID (string),
  SubmittedBy (string),
  AssignedTo (string),
  TargetDate (ISO 8601 string),
  RequiredByDate (ISO 8601 string),
  NextActionTo (string),
  SubStatusID (integer),
  ProjectID (integer),
  OrganizationID (integer),
  ShouldNeverSendEmailForIssue (boolean),
  ClassID (integer),
  DepartmentID (integer),
  SpecialFunction1 (string),
  SpecialFunction2 (string),
  SpecialFunction3 (string),
  SpecialFunction4 (string),
  SpecialFunction5 (string)
}
CreateNoteWithIssueDTO
{
  CreatedDate (ISO 8601 string),
  CreatedBy (string),
  NoteText (string),
  IsPrivate (boolean),
  IsRichText (boolean)
}
CreateIssueUserDefinedFieldDTO
{
 UserDefinedFieldID (integer),
 Value (string)
}

Request HTTP Verb: POST

Response Status Codes:

Success: 201
Invalid Data: 400

Request Properties:

The ShouldSuppressEmailForCreateOperation property value determines whether or not e-mail notifications will be sent by Issuetrak during the creation of this Issue. If ‘false', e-mail notifications will be sent normally. If 'true’, e-mail notifications will not be sent.
The CreatedBy property value must reference an existing, active User within the Issuetrak application.

Sample Request URL: ~/api/v1/issues/

Sample Request:

{
 “ShouldSuppressEmailForCreateOperation”: true,
 “Notes”: [],
 “UserDefinedFields”: [
  {
   “UserDefinedFieldID”: 4,
   “Value”: “Large Text 1 User-defined Field Property Created on: 10/09/2014 04:27:02. Random text follows: FOHTYEGRVNTSEHYRQTTAXDETWXDDITCCRNITGTUGEJC”
  },
  {
   “UserDefinedFieldID”: 5,
   “Value”: “Large Text 2 User-defined Field Property Created on: 10/09/2014 04:27:02. Random text follows: FOHTYEGRVNTSEHYRQTTAXDETWXDDITCCRNITGTUGEJC”
  }
 ],
 “SubmittedDate”: “2014-10-09T16:27:02.1445287Z”,
 “EnteredBy”: “Admin”,
 “SeverityID”: 1,
 “Subject”: “This subject was created on 10/09/2014 04:27:02. Random text follows:  SDYBUFPYRPRXGSURGMFWNJZXILVOSWKTKQTCXLKZSK”,
 “Description”: “This description was created on 10/09/2014 04:27:02. Random text follows: FOHTYEGRVNTSEHYRQTTAXDETWXDDITCCRNITGTUGEJCSUZRKALDFVFKCKOX”,
 “IsDescriptionRichText”: false,
 “IssueTypeID”: 0,
 “IssueSubTypeID”: 0,
 “IssueSubType2ID”: 0,
 “IssueSubType3ID”: 0,
 “IssueSubType4ID”: 0,
 “PriorityID”: 1,
 “AssetNumber”: 0,
 “LocationID”: "",
 “SubmittedBy”: “Admin”,
 “AssignedTo”: "",
 “TargetDate”: null,
 “RequiredByDate”: null,
 “NextActionTo”: "",
 “SubStatusID”: 0,
 “ProjectID”: 0,
 “OrganizationID”: 1,
 “ShouldNeverSendEmailForIssue”: true,
 “ClassID”: 1,
 “DepartmentID”: 1,
 “SpecialFunction1”: null,
 “SpecialFunction2”: null,
 “SpecialFunction3”: null,
 “SpecialFunction4”: null,
 “SpecialFunction5”: null
}

Sample Response HTTP Status Code: 201

Sample Response Body: 104416

Update an Issue

Description: This API method updates an existing Issue within the Issuetrak data store. The UpdateIssueDTO object conveys the properties of the Issue along with any User-defined Field instances to be associated with the new Issue. If invalid data are supplied, an error message will be returned with a 400 HTTP status code.

For example, if a non-null value is provided for the “ClassID” property and the “Use Issue Classes” feature is not activated, an error of the following form will be returned:

The specified value for the ‘ClassID' property is invalid because the 'Issue Classes’ feature is not activated.

UpdateIssueDTO properties that depend on specific Issuetrak feature activation:

AssetNumber (depends on the “Activate Asset Management” setting)
CauseID (depends on the “Causes” feature in Optional Fields)
ClassID (depends on the “Activate Issue Classes” feature)
DepartmentID (depends on “Use Departments” and “Use Resp Dept” features)
IssueSubTypeID (depends on the “Issue Subtype 1” feature)
IssueSubType2ID (depends on the “Issue Subtype 2” feature)
IssueSubType3ID (depends on the “Issue Subtype 3” feature)
IssueSubType4ID (depends on the “Issue Subtype 4” feature)
LocationID (depends on the “Use Locations” feature)
NextActionTo (depends on the “Next Action” feature in Optional Fields)
- Licensing Note: Only an “Agent” user may be used for assignment for a NextActionTo property value.
ProjectID (depends on the “Use Projects” feature)
RequiredByDate (depends on the “Required By Date” feature in Optional Fields)
SeverityID (depends on the “Use SLAs” feature)
SpecialFunction1 (depends on the “Use Custom Record Table” feature in Optional Fields)
SpecialFunction2 (depends on the “Use Custom Record Table” feature in Optional Fields)
SpecialFunction3 (depends on the “Use Custom Record Table” feature in Optional Fields)
SpecialFunction4 (depends on the “Use Custom Record Table” feature in Optional Fields)
SpecialFunction5 (depends on the “Use Custom Record Table” feature in Optional Fields)
SubStatusID (depends on the “Issue Substatus” feature in Optional Fields)
TargetDate (depends on the “Target Date” feature in Optional Fields)

The response code on success will be 200 (OK), and the response body will represent the 32-bit integer value representing the Issue Number of the updated Issue.

Response DTO Schema:

UpdateIssueDTO
{
 IssueNumber (integer),
 IssueSolution (string),
 Status (string),
 ClosedBy (string),
 ClosedDate (ISO 8601 string),
 CauseID (integer),
 ShouldSuppressEmailForUpdateOperation (boolean),
 UserDefinedFields (array[UpdateIssueUserDefinedFieldDTO]),
 SeverityID (integer),
 ResponseTime (ISO 8601 string),
 IsFirstCallResolution (boolean),
 Subject (string),
 Description (string),
 IsDescriptionRichText (boolean),
 IssueTypeID (integer),
 IssueSubTypeID (integer),
 IssueSubType2ID (integer),
 IssueSubType3ID (integer),
 IssueSubType4ID (integer),
 Priority (string),
 AssetNumber (integer),
 LocationID (string),
 SubmittedBy (string),
 AssignedTo (string),
 TargetDate (ISO 8601 string),
 RequiredByDate (ISO 8601 string),
 NextActionTo (string),
 SubStatusID (integer),
 ProjectID (integer),
 OrganizationID (integer),
 ShouldNeverSendEmailForIssue (boolean),
 ClassID (integer),
 DepartmentID (integer),
 SpecialFunction1 (string),
 SpecialFunction2 (string),
 SpecialFunction3 (string),
 SpecialFunction4 (string),
 SpecialFunction5 (string)
}
UpdateIssueUserDefinedFieldDTO
{
 IssueNumber (integer),
 UserDefinedFieldID (integer),
 Value (string)
}

Request HTTP Verb: POST

Response Status Codes:

Success: 200
Invalid Data: 400

Request Properties:

The ShouldSuppressEmailForUpdateOperation property value determines whether or not e-mail notifications will be sent by Issuetrak during the update of this Issue. If ‘false', e-mail notifications will be sent normally. If 'true’, e-mail notifications will not be sent.

Sample Request URL: ~/api/v1/issues/

Sample Request:

{
 “ID”: 79048,
 “IssueNumber”: 79048,
 “IssueSolution”: "",
 “Status”: “Open”,
 “ClosedBy”: "",
 “ClosedDate”: null,
 “CauseID”: null,
 “ShouldSuppressEmailForUpdateOperation”: false,
 “UserDefinedFields”: [
  {
   “IssueNumber”: 79048,
   “UserDefinedFieldID”: 4,
   “Value”: “Large Text 1 User-defined Field Property Updated on: 10/09/2014 04:30:00”
  },
  {
   “IssueNumber”: 79048,
   “UserDefinedFieldID”: 5,
   “Value”: “Large Text 2 User-defined Field Property Updated on: 10/09/2014 04:30:00”
  }
 ],
 “SeverityID”: 1,
 “ResponseTIme”: “2014-10-9T10:55:00”,
 “IsFirstCallResolution”: false,
 “Subject”: “This Issue's Subject (DB: IssueDescription) was updated on 10/09/2014 04:30:00.UPVBSPTMYCPPPLJPPDFQVMOPUEFFBTETYJIBXKOPQFPJSPULDNAYKZOIAGGNJOKEXWQGCHRFOQAPWFXFK”,
 “Description”: “This Issue's Description (first note) was updated on 10/09/2014 04:30:00.UPVBSPTMYCPPPLJPPDFQVMOPUEFFBTETYJIBXKOPQFPJSPULDNAYKZOIAGGNJOKEXWQGCHRFQAPWFXFKUBN”,
 “IsDescriptionRichText”: false,
 “IssueTypeID”: null,
 “IssueSubTypeID”: null,
 “IssueSubType2ID”: null,
 “IssueSubType3ID”: null,
 “IssueSubType4ID”: null,
 “Priority”: “High”,
 “AssetNumber”: null,
 “LocationID”: "",
 “SubmittedBy”: “Admin”,
 “AssignedTo”: "",
 “TargetDate”: null,
 “RequiredByDate”: null,
 “NextActionTo”: "",
 “SubStatusID”: 14,
 “ProjectID”: null,
 “OrganizationID”: 1,
 “ShouldNeverSendEmailForIssue”: null,
 “ClassID”: 1,
 “DepartmentID”: 1,
 “SpecialFunction1”: null,
 “SpecialFunction2”: null,
 “SpecialFunction3”: null,
 “SpecialFunction4”: null,
 “SpecialFunction5”: null
}

Sample Response HTTP Status Code: 200

Sample Response Body: 79048 (represents the Issue Number for the Issue updated)

Search Issues

Description: This method retrieves a collection of Issues from the Issuetrak data store for specified query set definitions. The query set definitions can contain one or more query expressions arranged into query sets with each query set related to the other query sets via an “AND” or “OR” logical operator.

ReadIssueDTO properties that may be used as the “FieldName” property value within the “QuerySetExpressions” of the searchIssueDTO JSON representation:

IssueNumber (integer)
IssueSolution (string)
Status (string)
ClosedBy (string)
ClosedDate (ISO 8601 string)
SubmittedDate (ISO 8601 string)
CauseID (integer)
Subject (string)
Description (string)
IssueTypeID (integer)
IssueSubTypeID (integer)
IssueSubType2ID (integer)
IssueSubType3ID (integer)
IssueSubType4ID (integer)
PriorityID (integer)
AssetNumber (integer)
LocationID (string)
SubmittedBy (string)
AssignedTo (string)
TargetDate (ISO 8601 string)
RequiredByDate (ISO 8601 string)
NextActionTo (string)
SubStatusID (integer)
ProjectID (integer)
OrganizationID (integer)
ClassID (integer)
DepartmentID (integer)
SpecialFunction1 (string)
SpecialFunction2 (string)
SpecialFunction3 (string)
SpecialFunction4 (string)
SpecialFunction5 (string)

To search on User Defined Fields, specify the FieldName property of the query expression using the format “UDI.ID” where ID is the primary key of the UDFields table record for the User Defined Field you want to search on. For example, if you want to search Issues on a User Defined Field with a primary key in the UDFields table of 5 you would use FieldName = “UDI.5”.

Additionally, to change the output result set ordering, one or more query order definitions may be specified with each query order definition consisting of a property name over which to apply the sorting and the sorting direction: ASC or DESC.

Paging of the results is specified by including a zero-based page index and the desired page size.

A successful response will include an HTTP status code of 200 (OK) and a response body containing a serialized collection of ReadIssueDTO instances.

Each ReadIssueDTO response instance will contain a collection of ReadNoteDTO instances if the {CanIncludeNotes} property was specified as true; otherwise, the “Notes” array will be null.

Response DTO Schema:

SearchIssueDTO
{
 CanIncludeNotes (boolean),
 QuerySetDefinitions (array[SearchQuerySetDTO]),
 QueryOrderingDefinitions (array[SearchQueryOrderingDTO]),
 PageIndex (integer),
 PageSize (integer)
}
SearchQuerySetDTO
{
 QuerySetIndex (integer),
 QuerySetOperator (string) = [‘Undefined' or 'AND' or 'OR’],
 QuerySetExpressions (array[SearchQueryExpressionDTO])
}
SearchQueryOrderingDTO
{
 QueryOrderingDirection (string) = [‘ASC' or 'DESC’],
 FieldName (string)
}
SearchQueryExpressionDTO
{
 QueryExpressionOperator (interger) = ['0', '1', '2']integerEnum:0, 1, 2,],
 QueryExpressionOperation (integer) = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12',
 '13', '14', '15', '16', '17', '18', '19', '20', '21', '22', '23', '24', '25', '26]integerEnum:0, 1, 2, 3,
 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
 FieldName (string),
 FieldFilterValue1 (string),
 FieldFilterValue2 (string)
}

Request HTTP Verb: POST

Response Status Codes:

Success: 200
Serialization Issue: 400

Response Properties: None

Sample Request URL: ~/api/v1/issues/search

Sample Request – Search on Issue Number:

{
 “QuerySetDefinitions”: [
  {
   “QuerySetIndex”: 0,
   “QuerySetOperator”: “AND”,
   “QuerySetExpressions”: [
    {
     “QueryExpressionOperator”: “AND”,
     “QueryExpressionOperation”: “Equal”,
     “FieldName”: “IssueNumber”,
     “FieldFilterValue1”: “122”,
     “FieldFilterValue2”: ""
    }
   ]
  }
 ],
 “QueryOrderingDefinitions”: [
  {
   “QueryOrderingDirection”: “DESC”,
   “FieldName”: “IssueNumber”
  }
 ],
 “PageIndex”: 0,
 “PageSize”: 10,
 “CanIncludeNotes”: false
}

Sample Request – Search on User Defined Field:

{
 “QuerySetDefinitions”: [
  {
   “QuerySetIndex”: 0,
   “QuerySetOperator”: “AND”,
   “QuerySetExpressions”: [
    {
     “QueryExpressionOperator”: “AND”,
     “QueryExpressionOperation”: “Between”,
     “FieldName”: “UDI.6”,
     “FieldFilterValue1”: “2013-01-01T00:00:00”,
     “FieldFilterValue2”: “2013-12-31T00:00:00”
    }
   ]
  }
 ],
 “QueryOrderingDefinitions”: [
  {
   “QueryOrderingDirection”: “DESC”,
   “FieldName”: “IssueNumber”
  }
 ],
 “PageIndex”: 0,
 “PageSize”: 10,
 “CanIncludeNotes”: false
}

Sample Response HTTP Status Code: 200

Sample Response Body:

{
 “IsPageIndexZeroBased”: true,
 “PageIndex”: 0,
 “CountForPage”: 1,
 “PageSize”: 10,
 “TotalCount”: 1,
 “Collection”: [
  {
   “IssueNumber”: 122,
   “IssueSolution”: "",
   “Status”: “open”,
   “ClosedBy”: “esmith”,
   “ClosedDate”: “2011-06-27T12:09:16”,
   “SubmittedDate”: “2011-06-23T09:15:00”,
   “CauseID”: null, 
   “Notes”: [],
   “UserDefinedFields”: [
    {
     “ExtensionData”: [],
     “Metadata”: [],
     “IssueNumber”: 122,
     “DisplayName”: “Payment Date”,
     “UserDefinedFieldID”: 6,
     “Value”: “2014-07-31T11:00:00”
    },
    {
     “ExtensionData”: [],
     “Metadata”: [],
     “IssueNumber”: 122,
     “DisplayName”: “Amount”,
     “UserDefinedFieldID”: 7,
     “Value”: 24.99
    }
   ],
   “ExtensionData”: [],
   “Metadata”: [
    {
     “Key”: “APIVersion”,
     “Value”: “12.5”
    },
    {
     “Key”: “QueryDate”,
     “Value”: “2014-12-05T14:02:55.4400115Z”
    }
   ],
   “Subject”: “Issue Subject”,
   “Description”: “Issue Description”,
   “IsDescriptionRichText”: false,
   “IssueTypeID”: 5,
   “IssueSubTypeID”: 0,
   “IssueSubType2ID”: 0,
   “IssueSubType3ID”: 0,
   “IssueSubType4ID”: 0,
   “Priority”: “Medium”,
   “AssetNumber”: null,
   “LocationID”: "",
   “SubmittedBy”: “admin”,
   “AssignedTo”: "",
   “TargetDate”: null,
   “RequiredByDate”: null,
   “NextActionTo”: null,
   “SubStatusID”: 13,
   “ProjectID”: 0,
   “OrganizationID”: 1,
   “ShouldNeverSendEmailForIssue”: null,
   “ClassID”: 0,
   “DepartmentID”: 0,
   “SpecialFunction1”: "",
   “SpecialFunction2”: "",
   “SpecialFunction3”: "",
   “SpecialFunction4”: "",
   “SpecialFunction5”: ""
  }
 ]
}

Summary

Retrieve an Issue by Issue Number

Retrieve a Collection of Issues for a List of Issue Numbers

Create an Issue

Update an Issue

Search Issues

Related Articles