Clarity user session counts and metrics

Products

• Clarity PPM On Premise
• Clarity PPM SaaS

Issue/Introduction

We need help understanding how user sessions are generated within Clarity. Also we need to understand how user sessions get initiated and terminated so that we understand these metrics.  

Resolution

User sessions in Clarity are more than just a simple login; they are a multi-layered handshake between the Application Server (Tomcat), the Database, and the Client (Browser/REST Tool).

To understand how these sessions are generated and managed, it helps to look at the three distinct layers of the architecture:

1. The Authentication Layer (Initiation)

The moment a user attempts to connect, Clarity initiates an authentication flow based on your configuration (Standard, LDAP, or SSO).

Classic UI: Uses a traditional JSESSIONID cookie. The server validates the credentials and issues a cookie that the browser sends back with every request.

Modern UX & REST API: Uses a more modern approach with JWT (JSON Web Tokens) or Bearer Tokens. When you login to the MUX, the system generates an access token. This token is stateless, meaning the server doesn't have to "remember" you in its local memory; the token itself proves who you are.

2. The Database Layer (Persistence)

Regardless of how you log in (UI, XOG, or REST), Clarity tracks every active session in the database.

 This is critical for license auditing and system maintenance.Table NamePurposeCMN_SESSIONSStores currently active sessions. When a user logs out, their row is deleted from here.CMN_SESSION_AUDITSA historical log of every login/logout event. This table grows indefinitely and is used for audit reports.CMN_SEC_USERSThe core user table. A session is always linked back to a record here via USER_ID.

3. The Lifecycle of a Session

The "Generation" of a session follows a specific lifecycle:

Creation: The user provides credentials. If valid, the app server creates a record in CMN_SESSIONS with a unique SESSION_ID.

Activity Tracking: Every time a user clicks a button or runs a process, the LAST_UPDATED_DATE in CMN_SESSIONS is updated.

Timeout: If the user is idle for longer than the Session Timeout (configured in Clarity System Administration/CSA), the session becomes "Invalid."

Cleanup: The Clean User Sessions job runs in the background. It looks for sessions where the timeout has passed and deletes them from CMN_SESSIONS, effectively "logging out" the user.