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 < as < or > 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
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 < as < or > 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 < as < or > 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., an invalid 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 < as < or > 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., an invalid 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 < as < or > 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., an invalid 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 < as < or > 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., an invalid 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)