Users V6
User API is the portal to user creation and access management for Integrated customer. The user v6 is connected to the Account Manager application which replace the User Management. The API is here to manage users, manage user access and view used application.
Password management: in case of SSO project, the users will be created as Active. In case of Trax Authentication, the user will receive an email/text message requesting him to fill the user setup form, where he will be required to create his password.
Querying users from Trax, contains user metadata, roles and apps usage
Creating and Updating users in Trax in an asynchronous way -- not yet available
GET
Supported Protocol: HTTPS
GET /api/:version_number/:project_name/entity/user
curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/api/v6/my-project/entity/user
Request Details
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Query Parameters
version_number string *
The current implemented API version. <Major> version (in this case 'v6')
project_name string *
Project name as provided by Trax
Mandatory fields marked indicated by
*
Response Details
Response
[
{
"pk": 1,
"email": "john.doe@customer.com",
"username": "john.doe@customer.com",
"fullName": "John Doe",
"userType": "External",
"scopeType": "Global",
"creationTime": "2020-09-02T14:09:18.000Z",
"status": "ACTIVE",
"project": "api Demo",
"roles": [
"Mobile Users"
],
"consumerLicense": "-",
"additionalAttribute1": null,
"additionalAttribute2": null,
"additionalAttribute3": null,
"additionalAttribute4": null,
"additionalAttribute5": null,
"additionalAttribute6": null,
"additionalAttribute7": null,
"additionalAttribute8": null,
"additionalAttribute9": null,
"additionalAttribute10": null,
"apps": [
{
"app": "Mobile App",
"lastActivity": null,
"activity0": null,
"activity1": null,
"activity2": null,
"activity3": null,
"activity4": null,
"activity5": null,
"activity6": null,
"activity7": null,
"activity8": null,
"activity9": null,
"activity10": null,
"activity11": null,
"activity12": null,
"activity13": null
}
]
}
]
The User GET reply body will contain the following fields:
pk integer
user unique id in Trax
email string
A valid, working, email, that is universally unique
username string
User's login name
fullName string
User's first and last name
userType string
Differentiate between Trax ("Internal") and customer ("External")
scopeType string
Global: user have access to more than 1 project in trax
Local: user only have access to the queried project
creationTime: date
Date when the user was created in Trax
status string
User status in Trax.
project string
name of the queried project
roles Object[]
List of roles connected to the users. There can be more than 1 role in this list
consumerLicense string
Which CPG NXT license is consumed by the user.
additionalAttribute (1 to 10) string
free text field to store extra user information
apps Object[]
List of apps connected to the users
app - app name
lastActivity - last activity date on the app
activity (0-13) - 0 current month, 1 last month, 13, 12 months from now
Validation and Errors
The following are the validations and errors that may appear due to an invalid GET request:
Unknown Field
-
Error Code: 400 - Bad Request
-
Error: Unknown Field: <field_name>
Internal Server Error
-
Error Code: 500 - Internal Server Error
-
Error: Trax Internal Error
Incorrect or expired token
-
Error Code: 401 - Unauthorized
-
Error: Incorrect or expired token
Requesting a forbidden resource
-
Error Code: 403 - Forbidden
-
Error: A forbidden resource has been requested <resource>
POST - NOT AVAILABLE YET
Creating, Deleting, and Updating users in Trax is done asynchronously. The users POST should be done via the Async jobs framework using the information below
User Update Operation Details
Operations are done in an "update + insert" style:
-
In order to add a new user:
-
Add an object/row with all the required fields. The operation will succeed only if all the mandatory fields will be provided
-
-
In order to update a user:
-
Add an object/row with all the required fields for an already existing user. The operation will succeed only if all the mandatory fields will be provided.
-
Empty field values will be treated as setting a field value to null
-
Request Example
Assume that Trax already contains valid data for 2 users:
In the JSON and the CSV examples below, the following effect will occur on the data that is stored in Trax:
-
A new user, email, with email "email" will be added as a Mobile Users
-
A second user, "phone number" will be added as Mobile Users
User deletion: There is no hard delete in Trax, user set to DISABLED will lose access to the queried project
User POST Request File Fields
Request Example - JSON
[
{
"email": "email",
"username": "email",
"fullName": "First - Last Name",
"status": "ACTIVE",
"roles": [
"Mobile Users"
],
"additionalAttribute1": null,
"additionalAttribute2": null,
"additionalAttribute3": null,
"additionalAttribute4": null,
"additionalAttribute5": null,
"additionalAttribute6": null,
"additionalAttribute7": null,
"additionalAttribute8": null,
"additionalAttribute9": null,
"additionalAttribute10": null
},
{
"email": "null",
"username": "phone number",
"fullName": "First - Last Name",
"status": "ACTIVE",
"roles": [
"Mobile Users"
],
"additionalAttribute1": null,
"additionalAttribute2": null,
"additionalAttribute3": null,
"additionalAttribute4": null,
"additionalAttribute5": null,
"additionalAttribute6": null,
"additionalAttribute7": null,
"additionalAttribute8": null,
"additionalAttribute9": null,
"additionalAttribute10": null
}
]
Request Example - CSV
email,username,fullName,status,roles,additionalAttribute1,additionalAttribute2,additionalAttribute3,additionalAttribute4,additionalAttribute5,additionalAttribute6,additionalAttribute7,additionalAttribute8,additionalAttribute9,additionalAttribute10
email,email,First - Last Name,ACTIVE,Mobile users,,,,,,,,,,
null,phone number,First - Last Name,ACTIVE,Mobile Users,,,,,,,,,,
Mandatory fields marked indicated by
*
username string *
User's user name. It can be either a universally unique email address or phone number. If one of the items added later (eg user initially created with email and mobile number is added later), then the identifier originally used to create the account is the unique identifier
email string
User's first name
fullName string
User's full name
Roles Object[] *
Roles the user should have when the user account is instantiated. It should come from the preexisting list of roles that exist in your project. Roles control the user access in Trax project. in API V6, you can assign more than 1 role to the user.
status string
User's status. Active, Disabled, or Pending. Pending is the state between when they have been added and when they have validated their login credentials
additionalAttribute (1 to 10) string
free text field to store extra user information
Response, Validation, and Errors
The initial response for a valid async job request will be 202 Accepted.
When the async job is queried, the outcome of the job will be available only when the status is 'done'.
For more info, see the Async-Jobs page
Validation and Error File
When uploading the file, the Trax system runs numerous validations on the file to confirm it has all the necessary fields.
Should there be issues with the file, an error file will be generated. It will contain one or several of the following errors based on failing the related validation:
Mandatory Variables - Missing Mandatory
Fields During creation
-
Missing mandatory field:<field_name>
-
Missing mandatory fields:
<field_name>,<field_name>....
Variable Types
-
Invalid variable type:<field_name>-expected type: <expected_variable_type>
-
Invalid variable types:<field_name>-expected type: <expected_variable_type>,
<field_name>-expected type: <expected_variable_type>...
Incorrect Format - Email Format will be validated
-
Incorrect format for field: <field_name>, the correct format: <correct_format>
Error File Example
[
to be filled
]