API Operations for Users

Summary

Operation Name: Retrieve a User by User ID
Relative API Request Path: ~/api/v1/users/{userID}/{includeUserPhoto}
HTTP Verb: GET
Description: Retrieve a single User by User ID.

Operation Name: Retrieve all Users
Relative API Request Path: ~/api/v1/users/{ includeUserPhotos}
HTTP Verb: GET
Description: Retrieve a collection of currently defined Users.

Operation Name: Create a User
Relative API Request Path: ~/api/v1/users
HTTP Verb: POST
Description: Create a User

Operation Name: Update a User
Relative API Request Path: ~/api/v1/users
HTTP Verb: PUT
Description: Update a User

Operation Name: Update a User Password
Relative API Request Path: ~/api/v1/users/password
HTTP Verb: PUT
Description: Update a User Password

Operation Name: Inactivate a User
Relative API Request Path: ~/api/v1/users/inactivate
HTTP Verb: PUT
Description: Inactivate a User

Retrieve a User by User ID

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

The “includeUserPhoto” is a true or false parameter is a Boolean indicating whether or the binary content for any existing user photo image file should be retrieved and included in the response. If the “includeUserPhoto” parameter is true and if a user photo image file exists for the specified user, a base-64 encoded byte arrayr representing the photo image file will be included in the UserPhotoBytes property of the response. If the “includeUserPhoto” parameter is false or if the user photo image file is not defined, the UserPhotoBytes property will be null.

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

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

Response DTO Schema:

ReadUserDTO
{
 ExtensionData (Array[CustomKeyValuePairDataElement]),
 Metadata (Array[CustomKeyValuePairDataElement]),
 UserID (string),
 UserNumber (integer),
 FirstName (string),
 LastName (string),
 DisplayName (string),
 Address1 (string),
 Address2 (string),
 City (string),
 State (string),
 ZIPCode (string),
 Country (string),
 EmailAddress (string),
 Pager (string),
 Phone (string),
 DepartmentID (integer),
 OrganizationID (integer),
 LocationID (string),
 IsActive (boolean),
 ShouldShowDebug (boolean),
 IsSysAdmin (boolean),
 CreatedBy (string),
 CreatedDate (date-time),
 ModifiedBy (string),
 ModifiedDate (date-time),
 LastLoginDate (date-time),
 CannotLogin (boolean),
 HasNoAuthentication (boolean),
 LastPasswordChange (date-time),
 LoginAttempts (integer),
 UserDefined1ID (integer),
 UserDefined1 (string),
 UserDefined2ID (integer),
 UserDefined2 (string),
 UserDefined3ID (integer),
 UserDefined3 (string),
 UserDefinedDate (date-time),
 TimeZoneID (integer),
 DoesTimeZoneUseDaylightSavings (boolean),
 HomePageID (integer),
 DashboardReload (integer),
 ShouldDashboardShowTimer (boolean),
 DashboardDefaultClass (integer),
 UserPhotoBytes (Base64 string),
 DashboardDefaultMonths (integer),
 RedirectTo (string),
 ListFormat (string)

}

Request HTTP Verb: GET

Response Status Codes:

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

Response DTO Property Notes:

  • The ExtensionData property is not used in version 1 of the API.
  • 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/users/11/false

Sample Response:

{
 “ExtensionData”: [],
 “Metadata”: [
  {
   “Key”: “APIVersion”,
   “Value”: “10.2”
  },
  {
   “Key”: “QueryDate”,
   “Value”: “2015-03-27T18:18:27.647502Z”
  }
 ],
 “UserID”: “Test.User.1239”,
 “UserNumber”: 1239,
 “FirstName”: “Test”,
 “LastName”: “User”,
 “DisplayName”: “Test.User.Update”,
 “Address1”: “Test Address 1”,
 “Address2”: “Test Address 2”,
 “City”: “Test City”,
 “State”: “VA”,
 “ZIPCode”: “23320”,
 “Country”: “United States”,
 “EmailAddress”: “test@test.com”,
 “Pager”: “555-111-1111”,
 “Phone”: “555-222-2222”,
 “DepartmentID”: null,
 “OrganizationID”: 1,
 “LocationID”: null,
 “IsActive”: true,
 “ShouldShowDebug”: true,
 “IsSysAdmin”: false,
 “CreatedBy”: “Admin”,
 “CreatedDate”: “2015-03-26T16:29:59.997”,
 “ModifiedBy”: “Admin”,
 “ModifiedDate”: “2015-03-26T16:29:59.997”,
 “LastLoginDate”: “2015-03-26T16:29:59.997”,
 “CannotLogin”: true,
 “HasNoAuthentication”: true,
 “LastPasswordChange”: “2015-03-26T16:29:59.997”,
 “LoginAttempts”: 0,
 “UserDefined1ID”: null,
 “UserDefined1”: null,
 “UserDefined2ID”: null,
 “UserDefined2”: null,
 “UserDefined3ID”: null,
 “UserDefined3”: null,
 “UserDefinedDate”: null,
 “TimeZoneID”: 26,
 “DoesTimeZoneUseDaylightSavings”: true,
 “HomePageID”: 1,
 “DashboardReload”: 0,
 “ShouldDashboardShowTimer”: true,
 “DashboardDefaultClass”: 0,
 “UserPhotoBytes”: null,
 “DashboardDefaultMonths”: 1,
 “RedirectTo”: “CSIssue_Submit.asp”,
 “ListFormat”: “Standard”
}

Retrieve All Users

Description: This API method retrieves a collection of all currently-defined Users from the Issuetrak data store.

No UserPhotoBytes content is retrieved during this API method. All of the ReadUserDTO instances will have the UserPhotoBytes content property set to null.

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

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

Response DTO Schema:

{
 “IsPageIndexZeroBased”: false,
 “PageIndex”: 0,
 “CountForPage”: 0,
 “PageSize”: 0,
 “TotalCount”: 0,
 “Collection”: [
  {
   “ExtensionData”: [],
   “Metadata”: [
    {
     “Key”: “APIVersion”,
     “Value”: “10.2”
    },
    {
     “Key”: “QueryDate”,
     “Value”: “2015-03-27T18:18:27.647502Z”
    }
   ],
   UserID: “Test.User.1239”,
   UserNumber: 1239,
   FirstName: “Test”,
   LastName: “User”,
   DisplayName: “Test.User.Update”,
   Address1: “Test Address 1”,
   Address2: “Test Address 2”,
   City: “Test City”,
   State: “VA”,
   ZIPCode: “23320”,
   Country: “United States”,
   EmailAddress: “test@test.com”,
   Pager: “555-111-1111”,
   Phone: “555-222-2222”,
   DepartmentID: null,
   OrganizationID: 1,
   LocationID: null,
   IsActive: true,
   ShouldShowDebug: true,
   IsSysAdmin: false,
   CreatedBy: “Admin”,
   CreatedDate: “2015-03-26T16:29:59.997”,
   ModifiedBy: “Admin”,
   ModifiedDate: “2015-03-26T16:29:59.997”,
   LastLoginDate: “2015-03-26T16:29:59.997”,
   CannotLogin: true,
   HasNoAuthentication: true,
   LastPasswordChange: “2015-03-26T16:29:59.997”,
   LoginAttempts: 0,
   UserDefined1ID: null,
   UserDefined1: null,
   UserDefined2ID: null,
   UserDefined2: null,
   UserDefined3ID: null,
   UserDefined3: null,
   UserDefinedDate: null,
   TimeZoneID: 26,
   DoesTimeZoneUseDaylightSavings: true,
   HomePageID: 1,
   DashboardReload: 0,
   ShouldDashboardShowTimer: true,
   DashboardDefaultClass: 0,
   UserPhotoBytes: null,
   DashboardDefaultMonths: 1,
   RedirectTo: “CSIssue_Submit.asp”,
   ListFormat: “Standard”
  } 
 ]
}

Request HTTP Verb: GET

Response Status Codes:

  • Success: 200
  • Non-existent User: 404

Response DTO Property Notes:

  • 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 ReadUserDTO objects returned.
  • The ExtensionData property is not implemented in v1 of the API.

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

Sample Response:

{
 “IsPageIndexZeroBased”: true,
 “PageIndex”: 0,
 “CountForPage”: 1,
 “PageSize”: 2147483647,
 “TotalCount”: 1,
 “Collection”: [
  {
   “ExtensionData”: [“KeyValuePair[String,Object]”],
   “Metadata”: [“KeyValuePair[String,Object]”],
   “UserID”: 0,
   “UserName”: "",
   “DisplayOrder”: 0
  }
 ]
}

Create a User

Description: This API method creates a new User associated with a specific UserID within the Issuetrak data store. The CreateUserDTO object conveys the properties of the new User. Because UserID values must be unique, the specified UserID value must not currently exist. If the UserID currently exists, an error message will be returned with a 400 HTTP status code.

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

When creating a User using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed.

Response DTO Schema:

CreateUserDTO
{
 UserID (string),
 Password (string),
 UserTypeID (integer),
 FirstName (string),
 LastName (string),
 DisplayName (string),
 Address1 (string),
 Address2 (string),
 City (string),
 State (string),
 ZIPCode (string),
 Country (string),
 EmailAddress (string),
 Pager (string),
 Phone (string),
 DepartmentID (integer),
 OrganizationID (integer),
 LocationID (string),
 IsActive (boolean),
 ShouldShowDebug (boolean),
 IsSysAdmin (boolean),
 CreatedBy (string),
 CreatedDate (date-time),
 ModifiedBy (string),
 ModifiedDate (date-time),
 LastLoginDate (date-time),
 CannotLogin (boolean),
 HasNoAuthentication (boolean),
 LastPasswordChange (date-time),
 LoginAttempts (integer),
 UserDefined1ID (integer),
 UserDefined1 (string),
 UserDefined2ID (integer),
 UserDefined2 (string),
 UserDefined3ID (integer),
 UserDefined3 (string),
 UserDefinedDate (date-time),
 TimeZoneID (integer),
 DoesTimeZoneUseDaylightSavings (boolean),
 HomePageID (integer),
 DashboardReload (integer),
 ShouldDashboardShowTimer (boolean),
 SystemUser (string),
 DashboardDefaultClass (integer),
 UserPhotoBytes (Base64 string),
 DashboardDefaultMonths (integer),
 RedirectTo (string),
 ListFormat (string)
}

Request HTTP Verb: POST

Response Status Codes:

  • Success: 201
  • Invalid User Properties: 400 (Bad Request, e.g., a negative integer is supplied)
  • Invalid User DTO: 422 (Unprocessable Entity, e.g., a non-numeric value is supplied)

Response DTO Property Notes:

  • The UserID property value is not required. If a null value is supplied, an auto-generated UserNumber value will be substituted.
  • The UserTypeID is required and must represent an existing UserType.
  • The Password property value is not required. If a null value is supplied, then no password will be set for the user. This will prevent the user from being able to sign in.
  • The FirstName property value is required.
  • The LastName property value is required.
  • The DisplayName property value is not required. If a null value is supplied, the FirstName and LastName values will be concatenated with an intervening space to form a substitute value.
  • The EmailAddress, if specified, must represent a validly formatted e-mail address.
  • The OrganizationID is required and must represent an existing Organization.
  • The DepartmentID property value, if specified, must represent an existing Department.
  • The LocationID property value, if specified, must reprsent an existing Location. Note that the LocationID is a text value in contrast to the OrganizationID and DepartmentID values.
  • The TimeZoneID property value is requires and must represent an existing TimeZone. The existing timezones may be retrieved using the “Retrieve all TimeZones” TimeZones API controller method.
  • The HomePageID property value is required and must represent the MenuItemID for an existing MenuItem corresponding to the desired home page. The existing menu items may be retrieved using the “Retrieve all Menu Items” MenuItems API controller method.
  • The CreatedBy property value is required, and the specified value must reference an existing, active User within the Issuetrak application.
  • The CreatedDate property value is required.
  • If the ModifiedBy property value is specified, the value must reference an existing, active User within the Issuetrak application.
  • The UserPhotoBytes property, if specified, represents the Base-64 encoded form of the image for the user. The image is best viewed at 150x150 pixels and must be less or equal to 500 KB in total size. Specify a null value for an empty UserPhoto. The image file format will be inferred from the byte array supplied after base-64 decoding.
  • The RedirectTo property is required and must be one of the following values (without the single quotes): ‘Dashboard.asp' or 'CSIssue_View.asp' or 'CSIssue_Submit.asp' or 'TrakHome.asp’.
  • The ListFormat property is required and must be one of the following values (without the single quotes): ‘Dashboard' or 'Standard’.
  • The LastPasswordChange property is deprecated and calculated as of Issuetrak API 10.3.0.

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

Sample Request:

{
 UserID: “TestUser1”,
 Password: “Test12345”,
 UserTypeID: 2,
 FirstName: “Test”,
 LastName: “User”,
 DisplayName: “Test.User”,
 Address1: “Test Address 1”,
 Address2: “Test Address 2”,
 City: “Test City”,
 State: “Test State”,
 ZIPCode: “12345-6789”,
 Country: “United States”,
 EmailAddress: “test@test.com”,
 Pager: “757-555-1111”,
 Phone: “757-555-2222”,
 OrganizationID: 1,
 DepartmentID: null,
 LocationID: null,
 IsInactive: false,
 ShouldShowDebug: true,
 IsSysAdmin: false,
 CreatedBy: “APIUser”,
 CreatedDate: “2015-03-04T16:09:34.955Z”,
 ModifiedBy: “APIUser”,
 ModifiedDate: “2015-03-04T16:09:34.955Z”,
 LastLoginDate: “2015-03-04T16:09:34.955Z”,
 CannotLogin: false,
 HasNoAuthentication: false,
 LastPasswordChange: “2015-03-04T16:09:34.955Z”,
 LoginAttempts: 0,
 UserDefined1ID: null,
 UserDefined1: null,
 UserDefined2ID: null,
 UserDefined2: null,
 UserDefined3ID: null,
 UserDefined3: null,
 UserDefinedDate: null,
 TimeZoneID: 0,
 TimeZoneDlt: true,
 HomePageID: -1,
 DashboardReload: 0,
 ShouldDashboardShowTimer: true,
 SystemUser: null,
 DashboardDefaultClass: null,
 UserPhotoBytes: null,
 DashboardDefaultMonths: null,
 RedirectTo: “CSIssue_Submit.asp”,
 ListFormat: “Standard”
}

Sample Response HTTP Status Code: 201

Sample Response Body: TestUser1 (represents the newly-created User ID)

Update a User

Description: This API method updates an existing User associated with a specific UserNumber within the Issuetrak data store. The UpdateUserDTO object conveys the properties of the existing User. Because UserID values must be unique, the specified UserID value must not currently exist for a user with a different UserNumber. If the UserID currently exists, an error message will be returned with a 400 HTTP status code.

The User Password property cannot updated with this API method. Please use the dedicated API controller method for password updates.

The response code on success will be 200 (OK), and the response body will represent the text value representing the ID of the edited User.

When creating a User using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed.

Response DTO Schema:

UpdateUserDTO
{
 UserID (string),
 UserNumber (integer),
 UserTypeID (integer),
 FirstName (string),
 LastName (string),
 DisplayName (string),
 Address1 (string),
 Address2 (string),
 City (string),
 State (string),
 ZIPCode (string),
 Country (string),
 EmailAddress (string),
 Pager (string),
 Phone (string),
 DepartmentID (integer),
 OrganizationID (integer),
 LocationID (string),
 IsActive (boolean),
 ShouldShowDebug (boolean),
 IsSysAdmin (boolean),
 CreatedBy (string),
 CreatedDate (date-time),
 ModifiedBy (string),
 ModifiedDate (date-time),
 LastLoginDate (date-time),
 CannotLogin (boolean),
 HasNoAuthentication (boolean),
 LastPasswordChange (date-time),
 LoginAttempts (integer),
 UserDefined1ID (integer),
 UserDefined1 (string),
 UserDefined2ID (integer),
 UserDefined2 (string),
 UserDefined3ID (integer),
 UserDefined3 (string),
 UserDefinedDate (date-time),
 TimeZoneID (integer),
 DoesTimeZoneUseDaylightSavings (boolean),
 HomePageID (integer),
 DashboardReload (integer),
 ShouldDashboardShowTimer (boolean),
 SystemUser (string),
 DashboardDefaultClass (integer),
 UserPhotoBytes (Base64 string),
 DashboardDefaultMonths (integer),
 RedirectTo (string),
 ListFormat (string)
}

*Request HTTP Verb: PUT

Response Status Codes:

  • Success: 200
  • Invalid User Properties: 400 (Bad Request, e.g., a negative integer is supplied)
  • Invalid User DTO: 422 (Unprocessable Entity, e.g., a non-numeric value is supplied)

Response DTO Property Notes:

  • The UserTypeID is required and must represent an existing UserType.
  • The FirstName property value is required.
  • The LastName property value is required.
  • The EmailAddress, if specified, must represent a validly formatted e-mail address.
  • The OrganizationID is required and must represent an existing Organization.
  • The DepartmentID property value, if specified, must represent an existing Department.
  • The LocationID property value, if specified, must reprsent an existing Location. Note that the LocationID is a text value in contrast to the OrganizationID and DepartmentID values.
  • The TimeZoneID property value, if specified, must represent an existing TimeZone. The existing timezones may be retrieved using the “Retrieve all TimeZones” TimeZones API controller method.
  • The HomePageID property value is required and must represent the MenuItemID for an existing MenuItem corresponding to the desired home page. The existing menu items may be retrieved using the “Retrieve all Menu Items” MenuItems API controller method.
  • The CreatedBy property value is required, and the specified value must reference an existing, active User within the Issuetrak application.
  • The CreatedDate property value is required.
  • If the ModifiedBy property value must reference an existing, active User within the Issuetrak application.
  • The ModifiedDate property value is required.
  • The UserPhotoBytes property, if specified, represents the Base-64 encoded form of the image for the user. The image is best viewed at 150x150 pixels and must be less or equal to 500 KB in total size. Specify a null value for an empty UserPhoto. The image file format will be inferred from the byte array supplied after base-64 decoding. If there is an existing UserPhoto and a null value is supplied in the UpdateUserDTO, the existing UserPhoto will be deleted.
  • The RedirectTo property is required and must be one of the following values (without the single quotes): ‘Dashboard.asp' or 'CSIssue_View.asp' or 'CSIssue_Submit.asp' or 'TrakHome.asp’.
  • The ListFormat property is required and must be one of the following values (without the single quotes): ‘Dashboard' or 'Standard’.
  • The LastPasswordChange property is deprecated and calculated as of Issuetrak API 10.3.0.

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

Sample Request:

{
 UserID: “TestUser1”,
 UserTypeID: 2,
 FirstName: “Test”,
 LastName: “User”,
 DisplayName: “Test.User”,
 Address1: “Test Address 1”,
 Address2: “Test Address 2”,
 City: “Test City”,
 State: “Test State”,
 ZIPCode: “12345-6789”,
 Country: “United States”,
 EmailAddress: “test@test.com”,
 Pager: “757-555-1111”,
 Phone: “757-555-2222”,
 OrganizationID: 1,
 DepartmentID: null,
 LocationID: null,
 IsInactive: false,
 ShouldShowDebug: true,
 IsSysAdmin: false,
 CreatedBy: “APIUser”,
 CreatedDate: “2015-03-04T16:09:34.955Z”,
 ModifiedBy: “APIUser”,
 ModifiedDate: “2015-03-04T16:09:34.955Z”,
 LastLoginDate: “2015-03-04T16:09:34.955Z”,
 CannotLogin: false,
 HasNoAuthentication: false,
 LastPasswordChange: “2015-03-04T16:09:34.955Z”,
 LoginAttempts: 0,
 UserDefined1ID: null,
 UserDefined1: null,
 UserDefined2ID: null,
 UserDefined2: null,
 UserDefined3ID: null,
 UserDefined3: null,
 UserDefinedDate: null,
 TimeZoneID: 0,
 TimeZoneDlt: true,
 HomePageID: -1,
 DashboardReload: 0,
 ShouldDashboardShowTimer: true,
 SystemUser: null,
 DashboardDefaultClass: null,
 UserPhotoBytes: null,
 DashboardDefaultMonths: null,
 RedirectTo: “CSIssue_Submit.asp”,
 ListFormat: “Standard”
}

Sample Response HTTP Status Code: 200

Sample Response Body: TestUser1 (represents the edited User ID)

Update a User Password

Description: This API method updates the password for an existing User associated with a specific UserID within the Issuetrak data store. The UpdateUserPasswordDTO object conveys the new password. Because UserID values must be unique, the specified UserID value must currently exist. If the UserID currently exists, an error message will be returned with a 400 HTTP status code.

The response code on success will be 200 (OK), and the response body will represent the text value representing the ID of the edited User.

When creating a User using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed.

Response DTO Schema:

UpdateUserPasswordDTO
{
 UserID (string),
 Password (string
}

Request HTTP Verb: PUT

Response Status Codes:

  • Success: 200
  • Invalid User Properties: 400 (Bad Request, e.g., a negative integer is supplied)
  • Invalid User DTO: 422 (Unprocessable Entity, e.g., a non-numeric value is supplied)

Response DTO Property Notes:

  • The UserID property value must represent an existing UserID.
  • The Password property value is required and must not exceed 150 characters in length.

Sample Request URL: ~/api/v1/users/password/

Sample Request:

{
 “UserID”: “TestUser1”,
 “Password”: “New.Password”
}

Sample Response HTTP Status Code: 200

Sample Response Body: TestUser1 (represents the edited User ID)

Inactivate a User

Description: This API method updates an existing User associated with a specific UserID within the Issuetrak data store. The InactivateUserDTO object conveys the UserID of the existing User to inactivate. Because UserID values must be unique, the specified UserID value must exist. If the UserID does not currently exists, an error message will be returned with a 400 HTTP status code.

The response code on success will be 200 (OK), and the response body will represent the text value representing the ID of the inactivated User.

When inactivating a User using the API, no special character decoding (e.g., HTML decoding &lt; as < or &gt; as >) is performed.

Response DTO Schema:

{
 UserID (string),
}

Request HTTP Verb: PUT

Response Status Codes:

  • Success: 200
  • Invalid User Properties: 400 (Bad Request, e.g., a non-existent UserID is specified)
  • Invalid User DTO: 422 (Unprocessable Entity, e.g., a non-numeric value is supplied)

Response DTO Property Notes:

  • The UserID property value is required and must exist.

Sample Request URL: ~/api/v1/users/inactivate

Sample Request:

{
 “UserID”: “InactiveUser”,
}

Sample Response HTTP Status Code: 200

Sample Response Body: InactiveUser (represents the inactivated User ID)