BERIFFA Keystone for administrators

This guide is for the administrators of a BERIFFA Keystone system: users with the role BER_ADMIN. BERIFFA hosts and operates your server; you decide who may do what on it.

How permissions work

• Every person needs a user on each system: DEV, QAS and PRD are separate. Signing in alone is not enough.
• A user can log on only while it is not locked and within its validity dates.
• What a user may do comes from the roles assigned in user maintenance (USER). The server checks them on every request.
• The Main Menu and the command field come from the server. A T-code the user may not run gives "You are not authorized to use transaction X", also when it does not exist or is inactive.
• Role changes take effect at the user's next request. The menu shows them after F5, at the next logon, or a minute later on the Main Menu.

Built-in roles

• BER_ADMIN: everything, including user maintenance (USER), role maintenance (ROLE), the licence (LIC) and every T-code.
• BER_USER: basic access. Every active user can already use PROF, STAT and MSGS.
• BER_EMPLOYEE: entering their own times (TIME), and projects in display mode (PRJ, PRJE).
• BER_PROJECT_MANAGER: everything BER_EMPLOYEE can do, plus creating projects, changing the projects they manage and approving time on them in TAPR (never their own).
• BER_TCODE_DEVELOPER: TCOD for Documentation, External link and Web page T-codes.

Built-in roles cannot be changed or deleted. A new user gets BER_USER and BER_EMPLOYEE ticked by default.

Users (USER)

Type USER in the command field (User Maintenance). Search for part of a user name, name or e-mail, and select a line to display the user.

Create a user

1. Click Create User.
2. User name: 1 to 12 characters (A–Z, 0–9, dot, underscore, hyphen), stored in upper case. It cannot be changed later.
3. Fill in the full name (required) and e-mail, tick the roles, and set Valid from and, if needed, Valid to.
4. Initial password: a random 14-character password is proposed. Keep it or type your own (12 to 128 characters, not containing the user name). Leave it empty only for a user who signs in with Microsoft, and fill in the Microsoft Entra link (tenant ID and object ID) instead.
5. Save with Ctrl+S.
6. Give the person the installer (download it from the BERIFFA Keystone download page with your company's beriffa.com account), the user name and your server's BERIFFA Service Token. Give the initial password through a different channel, for example by phone.

At the first logon the person chooses their own password and sets up an authenticator app.

Change, reset and lock

• Change: select the user, click Display ↔ Change, edit name, e-mail, roles, validity or the Microsoft link, and save with Ctrl+S.
• Reset Password proposes a new initial password that the user changes at the next logon. It also ends a temporary block after failed logons.
• Reset Authenticator removes the user's authenticator app and recovery codes, for example after a lost phone. Check the person's identity first, for example by calling them back on a known number.
• Lock / Unlock: a locked user is refused at the next request, also in sessions that are already open.

Safety rules

• You cannot lock your own user.
• The last active administrator cannot lose BER_ADMIN, be locked or be made invalid. Always keep at least two administrators.
• Users cannot be deleted: lock them or set Valid to instead.
• Every change is written to the audit log with your user name.

Roles (ROLE)

ROLE (Role Maintenance) lists the delivered roles, which are read-only, and your own roles. Select a role to see the T-codes that require it, the T-code types it may maintain in TCOD, and the users it is assigned to.

• Create: click Create, complete the code (it must start with Z_ or Y_, up to 30 characters), enter a description and save with Ctrl+S. The role appears in USER at once.
• Let a role run a T-code: select the role, click Add T-code and type the code. If the T-code was open to every user, ROLE asks before it restricts it.
• Remove T-code takes the role off a T-code. ROLE never removes a T-code's only role, because the T-code would then be open to every user.
• Delete is refused while users have the role or T-codes require it; ROLE says which.
• Built-in T-codes keep the roles they were delivered with.

Your own T-codes (TCOD)

TCOD (Create/Change T-codes) is for users with BER_TCODE_DEVELOPER or BER_ADMIN. The left side lists all T-codes of the system; the right side shows the selected one. To create a T-code:

1. Click Create.
2. Transaction code: starts with Z or Y, 1 to 20 characters (A–Z, 0–9, underscore), for example ZHANDBOOK.
3. Short text: 1 to 80 characters, shown in the menu and the window title.
4. Type: Documentation, External link, Web page, PowerShell script, Python script or Report. Scripts and reports need BER_ADMIN. The type cannot be changed later.
5. Active: ticked means that users can run it at once.
6. Menu folders: up to four folders, filled from the left, for example Tools and Intranet.
7. Settings of the type: the Documentation text in Markdown (up to 200 KB); the https:// address of a link or web page; the script and its arguments (up to 64 KB and 32 arguments); or the SQL query of a report (up to 64 KB).
8. Who may run it: tick roles; a user needs one of them. No role ticked means every user may run it. BER_ADMIN may always run every T-code.
9. Press Enter to check your input and Ctrl+S to save.

• Display ↔ Change edits a T-code; its code and type stay fixed.
• Test (F8) runs the saved T-code in a new session window, as users see it.
• Activate / Deactivate: an inactive T-code disappears from every menu but stays in TCOD.
• Delete removes the T-code for good, also from every user's favorites.
• Built-in T-codes cannot be changed, deactivated or deleted.
• Never put passwords or other secrets into scripts or SQL: every user who may run the T-code receives its content.

Reports

A report T-code holds one read-only query: SELECT, or WITH … SELECT. It runs in a read-only transaction and can read only the reporting views: users, user_roles, roles, transactions, audit_events, projects, wbs_elements and time_entries. Write the view names without a schema. For example, approved hours per person and week:

SELECT user_name, iso_year, iso_week, sum(hours) AS hours
FROM time_entries
WHERE status = 'Approved'
GROUP BY user_name, iso_year, iso_week
ORDER BY iso_year DESC, iso_week DESC, user_name

• Everyone who may run a report sees its whole result. Set required roles on every report that shows e-mail addresses, costs or other personal data, for example a custom role Z_CONTROLLING.
• Round averages and divisions in the query, for example round(avg(hours), 2).
• Reports have no parameters yet: make one T-code per variant.
• By default a report may run for 15 seconds and returns at most 10,000 rows.

Scripts

Only BER_ADMIN creates script T-codes. Set required roles so that only the right people can run them. Users approve every version on every PC before it runs, and every run is recorded in the audit log with the exit code, the duration and the script's fingerprint.

STAT and MSGS

• STAT shows the program and server versions, the system, how the user is logged on and the licence state. Ask users to have it ready when they contact support.
• MSGS lists the system messages for all users, then the licence notices. System messages also appear before logon and in the alarm indicator.
• There is no screen to maintain system messages yet. To announce planned downtime or similar, ask BERIFFA support to publish a message for your system.

Audit log

The server records security events: logons and log-offs, failed logons and blocks, password and authenticator changes, user and role changes, T-code changes, report and script runs, and licence events. There is no screen for the audit log yet; a report T-code on the audit_events view (time, event type, user name, program version and T-code) lets you review them.

Licence and LIC

Every system (PRD, QAS and DEV) has its own licence from BERIFFA. It names your company, the server, the system and the number of users, and runs for up to a year. BERIFFA installs and renews it; normally you do nothing. While licence checking is switched off for a system, STAT shows "Not checked" and nothing in this section applies.

The user limit

• Your licence allows a number of active users: tier S up to 10, M up to 25, L up to 50 and XL up to 100.
• A user is active on a day when it is not locked and the day lies within its validity dates. Locked users and users past their Valid to date do not count, nor do BERIFFA support users and technical users agreed with BERIFFA.
• At the limit, user maintenance (USER) refuses a change that would add an active user: creating one, unlocking one, or moving a Valid to date further out. Lock a person who has left, set their Valid to date, or ask BERIFFA for a larger tier.
• Existing users always keep working, even when a new licence has a lower limit.

Notices and read-only

• 30 to 8 days before the end: administrators see an information notice.
• The last 7 days: everyone sees a warning.
• Up to 14 days after the end (the grace period): everything still works, and everyone sees a warning.
• BERIFFA has withdrawn the licence: everything works until the date in the notice, then the system becomes read-only.
• The system has not reached BERIFFA's licence service: administrators are told after 3 days, everyone after 10. After 14 days, and one more failed check, the system becomes read-only until a check succeeds. Tell BERIFFA support at the first notice.
• After the grace period, from the withdrawal date, or without a valid licence, the system becomes read-only and every window shows a red banner.

Read-only never deletes or hides data. People can still log on and off, display everything, use the menu and favorites, and run and export reports. Administrators can still change existing users, lock and unlock them (within the user limit), reset passwords and authenticator apps, and install a new licence. Everything else that saves data is refused with "Not saved. This system is read-only because …". As soon as a valid licence is installed, everything works again.

LIC

LIC (Licence Administration, BER_ADMIN only) shows the current notices, the licence state, the active users against the limit, the users BERIFFA does not count, the installed licence (number, tier, user limit, validity and grace period), the online check with BERIFFA and the last installations. It works in every state, also while the system is read-only. To install a licence yourself:

1. BERIFFA sends you the licence as a file or as text in an e-mail. It starts with BKL1.
2. Open LIC and paste the text into Install a licence, or click Open File… and choose the file.
3. Click Install Licence (or press Ctrl+S). The status bar confirms the tier, the user limit and the end date, and the read-only banner disappears.

Check Now asks BERIFFA's licence service at once, for example after BERIFFA has registered a renewal. If a notice says that the system has not reached the BERIFFA licence service, tell BERIFFA support; once the cause is fixed, a successful Check Now lifts the notices, and read-only, at once.

Monthly checklist

1. Users: in USER, lock people who have left or set their Valid to date.
2. Administrators: at least two active users with BER_ADMIN, and nobody else.
3. Roles: check in ROLE which T-codes your roles allow, and which T-codes require no role at all.
4. Audit log: look for many failed logons or blocks for one user.
5. Versions: STAT shows the expected versions, and nobody reports "No update is offered".
6. Licence: LIC shows Valid and enough room under the user limit.