Tetra Chromeleon Agent User Role Fetch Command
The following procedure shows how to have the Tetra Chromeleon Agent programmatically retrieve user and role information from Chromeleon and upload it to the Tetra Data Platform (TDP) by using the User Role Fetch command and the Command Service.
Use Cases
The User Role Fetch command can help you do any of the following:
- Auditing and Compliance: Track user role assignments for regulatory compliance
- User Management: Monitor user access levels across Chromeleon installations
- Security Analysis: Review role assignments to ensure proper access controls
- Documentation: Generate up-to-date documentation of user permissions
Prerequisites
To run the User Role Fetch command, you must have the following:
- A running Tetra Chromeleon Agent v2.2.x or higher installed and configured with its queue enabled.
- A valid JSON Web Token (JWT) for the service user running the command. To create a JWT, see Generate a JWT for a Service User.
- Your TDP organization's slug (ORG SLUG). To find your org slug, see View Organization Details.
- Access to a tool that will allow you to run REST API calls, such as curl or Postman.
- User Mode activated in your Chromeleon software.
Step 1: Verify That the Agent Can Receive Commands
To allow the Agent to securely receive and run commands from the TDP, do the following:
- From the Tetra Chromeleon Agent Management Console, in the left navigation menu, under Menu, choose Configuration.
- Verify that the Receive Commands toggle is set to Yes (the default value).
For more information, see Enter TDP Connection Settings in the Tetra Chromeleon Agent Installation Guide.
Step 2: Run the User Role Fetch Command
To run the Tetra Chromeleon Agent User Role Fetch command, do the following:
- Create a valid Create Command in your code editor by using the following User Role Fetch Command Example code snippet.
- Copy and run the updated command by using a tool that will allow you to run REST API calls, such as curl or Postman.
After the Agent receives the User Role Fetch command, it does the following:
- Connects to Chromeleon and authenticates using the configured credentials
- Retrieves all available roles from Chromeleon
- For each role, it retrieves the list of users assigned to that role
- Generates a response containing the role-user mappings
For an example response, see the Command Response section.
Command Structure
The User Role Fetch command uses the following structure:
{
"targetId": "7659ef3a-95e9-4e4c-9742-eaf18e4a8af8",
"action": "TetraScience.Agent.chromeleon.UserRoleFetch",
"expiresAt": "2025-12-31T23:58:43.749Z",
"payload": {}
}
User Role Fetch Command Example
IMPORTANT
You must enter values for the following variables:
- For
POST
, enterhttps://api.tetrascience.com/v1/commands
- For
ts-auth-token
, enter your service user's JWT.- For
x-org-slug
, enter your organization's slug.- Make sure that you enter a valid request body that includes all of the Required fields listed in the Request Body Data Fields table.
curl --location --request POST 'https://api.tetrascience.com/v1/commands' \
--header 'ts-auth-token: <JWT Token>' \
--header 'x-org-slug: <Your Org Slug>' \
--header 'Content-Type: application/json' \
--data-raw '{
"targetId": "<Agent ID>",
"action": "TetraScience.Agent.chromeleon.UserRoleFetch",
"expiresAt": "2025-12-31T23:58:43.749Z",
"payload": {}
}'
Request Body Data Fields
Field | Description | Example |
---|---|---|
targetId | (Required) The ID of the Tetra Chromeleon Agent that receives the command | 7659ef3a-95e9-4e4c-9742-eaf18e4a8af8 |
action | (Required) Command name (this field is a constant varible) | TetraScience.Agent.chromeleon.UserRoleFetch |
expiresAt | (Required) Command expiration date in ISO-8601 format | 2025-12-31T23:58:43.749Z |
payload | (Required) An empty object for this command, but still required | For an example "payload" , see the User Role Fetch Command Example. |
Command Response
The command response includes a list of all available roles from Chromeleon and the users assigned to each role.
Example Response
[
{
"RoleName": "Full Access",
"Users": ["User1", "User2"]
},
{
"RoleName": "Users",
"Users": ["User3", "User4"]
}
]
Response Fields
Field | Description |
---|---|
RoleName | The name of the Chromeleon role |
Users | Array of usernames assigned to the role |
Troubleshooting
The Tetra Chromeleon Agent will send a FAILURE
status back to the TDP after it receives a User Role Fetch command under any of the following conditions:
Potential Issue | Resolution |
---|---|
The command is expired. | Update the request body's "expiresAt" value. |
Authentication failures | For ts-auth-token , make sure that you enter a valid service user JWT. For x-org-slug , make sure that you enter a valid organization slug. |
Network connectivity issues | Verify that you've configured the Agent's data connection with the TDP correctly. For instructions, see Step 4: Configure the Data Connection in the Tetra Chromeleon Agent Installation Guide (v2.2.x). |
Chromeleon User Mode isn't activated | Activate User Mode in your Chromeleon software. For more information, see Enable and configure user management in the Chromeleon documentation. |
Limitations
Keep in mind the following limitations when running the User Fetch Role command:
- The command will only return information about roles and users that exist in Chromeleon at the time the command is executed.
- Users not assigned to any role will not appear in the response.
- This command requires Chromeleon User Mode to be activated.
Updated 6 days ago