Accounts Module – User Guide

Overview

The Accounts Module provides functionality to manage user accounts within the portal. Users can perform the following actions:

• View all active accounts
• Create new accounts
• Update existing accounts
• Delete accounts
• Assign users to groups
• Configure additional metadata fields

The module communicates with backend APIs using a Bearer authentication token.

---

Architecture Overview

The Accounts feature consists of several layers:

Portal Page
   │
   ├── Accounts Wrapper (MobX Observer)
   │
   ├── Accounts Component
   │       │
   │       ├── Grid UI (DevExpress React Grid)
   │       ├── Popup Editing Form
   │       └── Delete Confirmation Dialog
   │
   └── API Layer
           ├── fetchAccounts
           ├── createAccount
           ├── updateAccount
           └── deleteAccount

---

Configuration

The Accounts page is enabled through the portal configuration file.

Example:

{
  "name": "Accounts",
  "type": "Accounts",
  "enabled": true,
  "configuration": {
    "authHost": "http://DS-DEV1:81"
  }
}

Configuration Fields

Field	Description
authHost	Base API host used for authentication and account management
metadata	Optional fields to extend account attributes
userGroupsDefaultSelected	Default user group assigned to newly created users

---

Authentication

All API calls require a Bearer Token.

Example:

Authorization: Bearer <accessToken>

The token is retrieved through the authService.

const { accessToken } = authService.getSession();

The Accounts component receives the token as:

token={appSession.pageAccessToken || accessToken}

---

Accounts Table

The Accounts page displays a data grid containing all active users.

Only users with:

activated === true

are displayed.

Default Columns

Column	Description
Username	Unique identifier of the account
Name	Display name of the user
Email	User email address
User Groups	Groups assigned to the user

---

Metadata Columns

Additional columns can be dynamically added using the metadata configuration.

Example metadata configuration:

[
  {
    "key": "myChoice",
    "label": "My Choice",
    "type": "SingleChoice",
    "options": ["A","B","C"],
    "default": "B"
  }
]

Supported Metadata Types

Type	Description
Text	Free text field
Boolean	True/False value
SingleChoice	Dropdown selection
MultiChoice	Multiple selection
MultiText	List of text values

---

CRUD Operations

Create Account

A new account can be created using the Add (+) button.

API Endpoint

POST /api/accounts

Example payload:

{
  "id": "john",
  "name": "John Doe",
  "email": "john@example.com",
  "userGroups": ["Editors"]
}

Notes:

• Creating an account automatically activates it.
• Password must be provided in the form.

---

Update Account

Editing an account updates the user record.

API Endpoint

PUT /api/accounts

Important:

All fields must be included in the payload except password.

If a field is missing it may be set to null.

---

Delete Account

Deleting an account requires confirmation.

API Endpoint

DELETE /api/accounts/{username}

After deletion:

• The table automatically refreshes.
• The confirmation dialog closes.

---

Password Management

Reset Password

Generates a password reset token and sends an email to the user.

Endpoint

POST /api/accounts/passwordreset

Query parameter

mailBody=<message template>

Body

"user@email.com"

---

Update Password

Updates password using a reset token.

Endpoint

PUT /api/accounts/password

Query parameter

token=<passwordToken>

Body

"newPassword"

---

Account Activation

Accounts can be activated using a token.

Endpoint

PUT /api/accounts/password/token=<accountToken>

Requires Authorization header.

---

Filtering and Sorting

The Accounts table supports:

• Column filtering
• Sorting
• Column visibility control

Implemented using:

@devexpress/dx-react-grid

Key features:

Feature	Description
Filtering	Filter users by column value
Sorting	Sort ascending or descending
Column Chooser	Show or hide columns
Virtual Table	Optimized rendering for large datasets

---

Error Handling

Errors returned from API calls are handled by:

handleError()

Displayed in the popup editing form.

Example:

setErrorMessage(error.message)

Errors are cleared automatically after display.

---

Data Loading

Data is loaded when the component mounts.

useEffect(() => {
  fetchData();
}, []);

Data sources:

GET /api/accounts
GET /api/usergroups

---

Storybook Example

The module can be tested in Storybook.

AccountsStory

Example usage:

<Accounts
  host={host}
  metadata={metadata}
  userGroupsDefaultSelected={["Editors"]}
  token={token.accessToken.token}
/>

---

Dependencies

Main libraries used:

• React
• MobX
• RxJS
• Material UI
• DevExpress React Grid

---

Best Practices

Recommended practices when using this module:

• Always include full payloads on updates
• Validate email before submission
• Define metadata fields carefully
• Restrict user groups to authorized roles
• Monitor API errors for backend validation issues

---

Troubleshooting

Users Not Visible

Check if the user is activated.

activated === true

---

API Unauthorized

Verify:

• Token validity
• Authorization header

---

Metadata Not Displayed

Ensure metadata is passed correctly:

metadata={metadata}

---

Summary

The Accounts module enables administrators to manage user accounts through a configurable, extensible interface.

Core capabilities include:

• Account creation
• User group management
• Metadata extension
• Password reset functionality
• Dynamic table filtering and sorting

---