The User Roles API offer a set of customizable and predefined roles that can be assigned to Users/Drivers. A User Role contains Permissions that indicates the actions the User is allowed to do. The User’s accessible services are dependent on the User Role and checked against the Permissions that are assigned under them in the system.
Fields
| Tag | Data Type | Required | Description |
| accountId | Long | No | The id of the Account that owns this record. |
| id | Auto-incremented Long | Auto | Unique Identifier |
| lastChangedDate | Text | Auto | Auto-generated timestamp of the last change made to this record Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z) |
| name | Character (100) | Yes | The name of the User Role. |
| permissions | Array | Yes | A collection of Permissions that the User Role has. |
| system | Boolean | No | Indicates if a User Role is system or not. |
Default User Roles
| Name | Description |
| USER_ROLE_ACCOUNTADMIN | Indicates if a User is an Account Admin. An Account Admin has overall access to the Account.
|
| USER_ROLE_FLEETMANAGER | Indicates if a User is a Fleet Manager. A Fleet Manager has access to Users, Equipment, Terminals and DVIR Forms information.
|
| USER_ROLE_USERADMIN | Indicates if a User is a User Admin. A User Admin has access to Users’ information.
|
| USER_ROLE_ASSETADMIN | Indicates if a User is an Asset Admin. An Asset Admin can manage the Account’s Equipment.
|
| USER_ROLE_WORKORDERASSIGNEE | Indicates if a User is work order assignee. A Work Order Assignee can be assigned Work Orders from the portal. Actions that can be performed by a Work Order Assignee include:
|
| USER_VIEW_ONLY | Indicates if a User has VIEW ONLY Permissions. A User with all the view Permissions can perform the following:
|
Create
| API PATH: | /api/v2/userRoles |
| METHOD: | POST |
| EXAMPLE REQUEST: |
[
{
"name":"User Role 1",
"permissions":[
{
"category":"Users",
"displayName":"PERM_IS_ACCOUNT_ADMIN",
"id":4,
"name":"PERM_IS_ACCOUNT_ADMIN",
"isDisable":false
},
{
"category":"Users",
"displayName":"PERM_IS_ASSET_ADMIN",
"id":7,
"name":"PERM_IS_ASSET_ADMIN",
"isDisable":false
},
{
"category":"Users",
"displayName":"PERM_IS_DRIVER",
"id":9,
"name":"PERM_IS_DRIVER",
"isDisable":false
},
{
"category":"Drivers",
"displayName":"PERM_VIEW_PORTAL_DRIVERS_TAB",
"id":13,"name":"PERM_VIEW_PORTAL_DRIVERS_TAB",
"isDisable":false
}
],
"system":false
}
]
|
| EXAMPLE RESPONSE: |
[
{
"name": "User Role 1",
"system": false,
"permissions": [
"PERM_IS_ACCOUNT_ADMIN",
"PERM_IS_ASSET_ADMIN",
"PERM_IS_DRIVER",
"PERM_VIEW_PORTAL_DRIVERS_TAB"
],
"accountId": 1248806,
"id": 1253423,
"lastChangedDate": "2018-06-11T12:00:00.000Z"
}
]
|
Read
| API PATH: | /api/v2/userRoles |
| METHOD: | GET |
| PARAMETERS: | offset – Retrieves matching records after an offset value (e.g. offset=2, zero offset by default) limit – Retrieves a number of records per page specified by the value (e.g. limit=10, all records by default) |
| SORTING: | sort=id – Sort records by their id field in ascending order (DEFAULT) sort=-id – Sort records by their id field in descending order sort=name – Sort records by their name field in ascending order sort=-name – Sort records by their name field in descending order |
| QUERY STRING EXAMPLE | Get the User Role with the specified id: api/v2/userRoles/1253423 Get two User Roles of the current Account with an offset of 1 : ?offset=1&limit=2 Get all User Roles of the current Account sorted by names alphabetically: ?sort=name |
| EXAMPLE RESPONSE: |
[
{
"name": "User Role 1",
"system": false,
"permissions": [
"PERM_IS_ACCOUNT_ADMIN",
"PERM_IS_ASSET_ADMIN",
"PERM_IS_DRIVER",
"PERM_VIEW_PORTAL_DRIVERS_TAB"
],
"accountId": 1248806,
"id": 1253423,
"lastChangedDate": "2018-06-11T12:00:00.000Z"
}
]
|
Update
| API PATH: | /api/v2/userRoles |
| METHOD: | PUT |
| EXAMPLE REQUEST: |
[
{
"name":"User Role 1",
"permissions": [
{
"category":"Users",
"displayName":"PERM_IS_DRIVER",
"id":9,
"name":"PERM_IS_DRIVER",
"isDisable":false
},
{
"category":"Users",
"displayName":"PERM_IS_WORK_ORDER_ASSIGNEE",
"id":10,
"name":"PERM_IS_WORK_ORDER_ASSIGNEE",
"isDisable":false
}
],
"id":1253423,
"system":false
}
]
|
| EXAMPLE RESPONSE: |
[
{
"name": "User Role 1",
"system": false,
"permissions": [
"PERM_IS_DRIVER",
"PERM_IS_WORK_ORDER_ASSIGNEE"
],
"accountId": 1248806,
"id": 1253423,
"lastChangedDate": "2018-06-11T12:00:00.000Z"
}
]
|
Delete
| API PATH: | /api/v2/userRoles/<id> |
| METHOD: | DELETE |
API error calls
| ERROR MESSAGE | POSSIBLE CAUSES |
| The new User role to insert should not have an id. | POST error because request must not contain an id |
| Permission <permission name> does not exist. | POST or PUT error because the Permission does not exist in the Account. |
| User cannot create/update User role that contains: <permission name> | POST or PUT error because the current User is not allowed to create or update a User Role with one of the Permissions. |
| A User role with the given id was not found | PUT error because id was not found in the Account |
| Can’t modify default User role <User role name> | PUT error because User cannot update a default User Role |
| Can’t delete default User role <User role name> | DELETE error because User cannot update a default User Role |