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

This API method retrieves a 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 array 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 a 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),
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 (string): ISO 8601 string,
ModifiedBy (string),
ModifiedDate (string): ISO 8601 string,
LastLoginDate (string): ISO 8601 string,
CannotLogin (boolean),
HasNoAuthentication (boolean),
LastPasswordChange (string): ISO 8601 string,
LoginAttempts (integer),
UserDefined1ID (integer),
UserDefined1 (string),
UserDefined2ID (integer),
UserDefined2 (string),
UserDefined3ID (integer),
UserDefined3 (string),
UserDefinedDate (string): ISO 8601 string,
TimeZoneID (integer),
DoesTimeZoneUseDaylightSavings (boolean),
HomePageID (integer)integerMin. Value:1Max. Value:2147483647,
DashboardReload (integer),
ShouldDashboardShowTimer (boolean),
DashboardDefaultClass (integer),
UserPhotoBytes (string): Base64 string,
DashboardDefaultMonths (integer),
RedirectTo (string),
ListFormat (string)
}CustomKeyValuePairDataElement {
Key (string, optional),
Value (object, optional)
}

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": [
    {
      "Key": "string",
      "Value": {}
    }
  ],
  "Metadata": [
    {
      "Key": "string",
      "Value": {}
    }
  ],
  "UserID": "string",
  "UserNumber": 0,
  "UserTypeID": 0,
  "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": 0,
  "OrganizationID": 0,
  "LocationID": "string",
  "IsActive": true,
  "ShouldShowDebug": true,
  "IsSysAdmin": true,
  "CreatedBy": "string",
  "CreatedDate": "string",
  "ModifiedBy": "string",
  "ModifiedDate": "string",
  "LastLoginDate": "string",
  "CannotLogin": true,
  "HasNoAuthentication": true,
  "LastPasswordChange": "string",
  "LoginAttempts": 0,
  "UserDefined1ID": 0,
  "UserDefined1": "string",
  "UserDefined2ID": 0,
  "UserDefined2": "string",
  "UserDefined3ID": 0,
  "UserDefined3": "string",
  "UserDefinedDate": "string",
  "TimeZoneID": 0,
  "DoesTimeZoneUseDaylightSavings": true,
  "HomePageID": 0,
  "DashboardReload": 0,
  "ShouldDashboardShowTimer": true,
  "DashboardDefaultClass": 0,
  "UserPhotoBytes": "string",
  "DashboardDefaultMonths": 0,
  "RedirectTo": "string",
  "ListFormat": "string"
}


 

Retrieve All Users

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 a 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:
 QueryResultsContainer[ReadUserDTO] 
{
IsPageIndexZeroBased (boolean, optional),
PageIndex (integer, optional),
CountForPage (integer, optional),
PageSize (integer, optional),
TotalCount (integer, optional),
Collection (Array[ReadUserDTO], optional)
}ReadUserDTO {
ExtensionData (Array[CustomKeyValuePairDataElement]),
Metadata (Array[CustomKeyValuePairDataElement]),
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 (string): ISO 8601 string,
ModifiedBy (string),
ModifiedDate (string): ISO 8601 string,
LastLoginDate (string):ISO 8601 string,
CannotLogin (boolean),
HasNoAuthentication (boolean),
LastPasswordChange (string): ISO 8601 string,
LoginAttempts (integer),
UserDefined1ID (integer),
UserDefined1 (string),
UserDefined2ID (integer),
UserDefined2 (string),
UserDefined3ID (integer),
UserDefined3 (string),
UserDefinedDate (string): ISO 8601 string,
TimeZoneID (integer),
DoesTimeZoneUseDaylightSavings (boolean),
HomePageID (integer)integerMin. Value:1Max. Value:2147483647,
DashboardReload (integer),
ShouldDashboardShowTimer (boolean),
DashboardDefaultClass (integer),
UserPhotoBytes (string): Base64 string ,
DashboardDefaultMonths (integer),
RedirectTo (string),
ListFormat (string)
}CustomKeyValuePairDataElement {
Key (string, optional),
Value (object, optional)
} 

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": 0,
  "PageSize": 0,
  "TotalCount": 0,
  "Collection": [
    {
      "ExtensionData": [
        {
          "Key": "string",
          "Value": {}
        }
      ],
      "Metadata": [
        {
          "Key": "string",
          "Value": {}
        }
      ],
      "UserID": "string",
      "UserNumber": 0,
      "UserTypeID": 0,
      "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": 0,
      "OrganizationID": 0,
      "LocationID": "string",
      "IsActive": true,
      "ShouldShowDebug": true,
      "IsSysAdmin": true,
      "CreatedBy": "string",
      "CreatedDate": "string",
      "ModifiedBy": "string",
      "ModifiedDate": "string",
      "LastLoginDate": "string",
      "CannotLogin": true,
      "HasNoAuthentication": true,
      "LastPasswordChange": "string",
      "LoginAttempts": 0,
      "UserDefined1ID": 0,
      "UserDefined1": "string",
      "UserDefined2ID": 0,
      "UserDefined2": "string",
      "UserDefined3ID": 0,
      "UserDefined3": "string",
      "UserDefinedDate": "string",
      "TimeZoneID": 0,
      "DoesTimeZoneUseDaylightSavings": true,
      "HomePageID": 0,
      "DashboardReload": 0,
      "ShouldDashboardShowTimer": true,
      "DashboardDefaultClass": 0,
      "UserPhotoBytes": "string",
      "DashboardDefaultMonths": 0,
      "RedirectTo": "string",
      "ListFormat": "string"
    }
  ]
}


 

Create a User

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 (string): ISO 8601 string,
ModifiedBy (string),
ModifiedDate (string): ISO 8601 string,
LastLoginDate (string): ISO 8601 string,
CannotLogin (boolean),
HasNoAuthentication (boolean),
LastPasswordChange (string): ISO 8601 string,
LoginAttempts (integer),
UserDefined1ID (integer),
UserDefined1 (string),
UserDefined2ID (integer),
UserDefined2 (string),
UserDefined3ID (integer),
UserDefined3 (string),
UserDefinedDate (string): ISO 8601 string,
TimeZoneID (integer),
DoesTimeZoneUseDaylightSavings (boolean),
HomePageID (integer)integerMin. Value:1Max. Value:2147483647,
DashboardReload (integer),
ShouldDashboardShowTimer (boolean),
DashboardDefaultClass (integer),
UserPhotoBytes (string): 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:
Property Name Required Notes
UserTypeID Must represent an existing UserType.
FirstName
LastName
EmailAddress If specified, must represent a validly formatted e-mail address.
OrganizationID Must represent an existing Organization.
DepartmentID If specified, must represent an existing Department.
LocationID If specified, must represent an existing Location. Note that the LocationID is a text value in contrast to the OrganizationID and DepartmentID.
TimeZoneID If specified, must represent an existing TimeZone. The existing timezones may be retrieved using the “Retrieve all TimeZones” TimeZones API controller method.
HomePageID 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.
CreatedBy The specified value must reference an existing, active User within the Issuetrak application.
CreatedDate
ModifiedBy Must reference an existing, active User within the Issuetrak application.
ModifiedDate
UserPhotoBytes 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.
RedirectTo Must be one of the following values (without the single quotes): ‘Dashboard.asp' or 'CSIssue_View.asp' or 'CSIssue_Submit.asp' or 'TrakHome.asp’.
ListFormat Must be one of the following values (without the single quotes): ‘Dashboard' or 'Standard’.

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

Sample Request:
{
  "UserID": "string",
  "Password": "string",
  "UserTypeID": 0,
  "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": 0,
  "OrganizationID": 0,
  "LocationID": "string",
  "IsActive": true,
  "ShouldShowDebug": true,
  "IsSysAdmin": true,
  "CreatedBy": "string",
  "CreatedDate": "string",
  "ModifiedBy": "string",
  "ModifiedDate": "string",
  "LastLoginDate": "string",
  "CannotLogin": true,
  "HasNoAuthentication": true,
  "LastPasswordChange": "string",
  "LoginAttempts": 0,
  "UserDefined1ID": 0,
  "UserDefined1": "string",
  "UserDefined2ID": 0,
  "UserDefined2": "string",
  "UserDefined3ID": 0,
  "UserDefined3": "string",
  "UserDefinedDate": "string",
  "TimeZoneID": 0,
  "DoesTimeZoneUseDaylightSavings": true,
  "HomePageID": 0,
  "DashboardReload": 0,
  "ShouldDashboardShowTimer": true,
  "DashboardDefaultClass": 0,
  "UserPhotoBytes": "string",
  "DashboardDefaultMonths": 0,
  "RedirectTo": "string",
  "ListFormat": "string"
}

Sample Response HTTP Status Code: 201

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


 

Update a User

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. 

Setting a user's organization via the API will result in the requested organization becoming the primary organization for the user.  If the user previously had multiple organization memberships, then these will be retained and the user will continue to have membership in their previous primary organization (but without it being their primary organization). 

The User Password property cannot be 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 (string): ISO 8601 string,
ModifiedBy (string),
ModifiedDate (string): ISO 8601 string,
LastLoginDate (string): ISO 8601 string,
CannotLogin (boolean),
HasNoAuthentication (boolean),
LastPasswordChange (string): ISO 8601 string,
LoginAttempts (integer),
UserDefined1ID (integer),
UserDefined1 (string),
UserDefined2ID (integer),
UserDefined2 (string),
UserDefined3ID (integer),
UserDefined3 (string),
UserDefinedDate (string): ISO 8601 string,
TimeZoneID (integer),
DoesTimeZoneUseDaylightSavings (boolean),
HomePageID (integer)integerMin. Value:1Max. Value:2147483647,
DashboardReload (integer),
ShouldDashboardShowTimer (boolean),
DashboardDefaultClass (integer),
UserPhotoBytes (string): 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:
Property Name Required Notes
UserTypeID Must represent an existing UserType.
FirstName
LastName
EmailAddress If specified, must represent a validly formatted e-mail address.
OrganizationID Must represent an existing Organization.
DepartmentID If specified, must represent an existing Department.
LocationID If specified, must represent an existing Location. Note that the LocationID is a text value in contrast to the OrganizationID and DepartmentID.
TimeZoneID If specified, must represent an existing TimeZone. The existing timezones may be retrieved using the “Retrieve all TimeZones” TimeZones API controller method.
HomePageID 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.
CreatedBy The specified value must reference an existing, active User within the Issuetrak application.
CreatedDate
ModifiedBy Must reference an existing, active User within the Issuetrak application.
ModifiedDate
UserPhotoBytes 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.
RedirectTo Must be one of the following values (without the single quotes): ‘Dashboard.asp' or 'CSIssue_View.asp' or 'CSIssue_Submit.asp' or 'TrakHome.asp’.
ListFormat Must be one of the following values (without the single quotes): ‘Dashboard' or 'Standard’.

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

Sample Request:
{
  "UserID": "string",
  "UserNumber": 0,
  "UserTypeID": 0,
  "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": 0,
  "OrganizationID": 0,
  "LocationID": "string",
  "IsActive": true,
  "ShouldShowDebug": true,
  "IsSysAdmin": true,
  "CreatedBy": "string",
  "CreatedDate": "string",
  "ModifiedBy": "string",
  "ModifiedDate": "string",
  "LastLoginDate": "string",
  "CannotLogin": true,
  "HasNoAuthentication": true,
  "LastPasswordChange": "string",
  "LoginAttempts": 0,
  "UserDefined1ID": 0,
  "UserDefined1": "string",
  "UserDefined2ID": 0,
  "UserDefined2": "string",
  "UserDefined3ID": 0,
  "UserDefined3": "string",
  "UserDefinedDate": "string",
  "TimeZoneID": 0,
  "DoesTimeZoneUseDaylightSavings": true,
  "HomePageID": 0,
  "DashboardReload": 0,
  "ShouldDashboardShowTimer": true,
  "DashboardDefaultClass": 0,
  "UserPhotoBytes": "string",
  "DashboardDefaultMonths": 0,
  "RedirectTo": "string",
  "ListFormat": "string"
}

Sample Response HTTP Status Code: 200

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


 

Update a User Password

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

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 exist, 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)