User Metering

[Karuna-Mendix]

https://mendix.atlassian.net/browse/TW-2769

[JaapF]

As per my previous comment - maybe not yet in Control Center - 2nd PR?

[satyammx]

We should remove reference to Control Center in this section.
Irrespective of the control center visibility, we do data collection, processing and deduplication

[Karuna-Mendix]

What about - Prompt data processing: Usage data is collected, processed, and deduplicated regularly. I can keep the original sentence again when the Usage data PR is available.

[Karuna-Mendix]

Or should I remove the point completely?

[JaapF]

Maybe the remark about deployments should be added here.

"End-user metering is currently applied to applications deployed to Mendix Cloud and Mendix Cloud Dedicated environments."

[satyammx]

historical data section is also relevant for control center.

[Karuna-Mendix]

@JaapF, do you mean to add the remark about deployments under the Key features section as a new bullet?

[Karuna-Mendix]

It does sound like a limitation, not a Key Feature. I may be wrong.

[JaapF]

The headings says "deduplication" but the contents don't say anything about deduplication. I think it should be added as a first step.

Suggestion:
"Users are deduplicated based on common identifier values. A real-life person who has different identifier values in the aggregated data cannot be recognized as same user, so will be counted as multiple users. The deduplication mechanism evaluates 2 user attributes, see [section xyz]" (the section where we talk about system.user.name and userCommons.nameduseridentifier.value, etc,..

[Karuna-Mendix]

If deduplication is the 1st step, should I change the heading to: How deduplication and user classification work? @JaapF

[JaapF]

Let's add:
"A multi-app user that is marked as internal in one app and is marked as external in another app will be counted as an internal user."

[satyammx]

@JaapF I'd say this is internal logic. Why do we want to write it here and confuse the audience?

[satyammx]

@JaapF @Karuna-Mendix the whole section somehow sounds very apologetic and guessing why you could have done it wrong. Documentation should be more directive IMO.

We ought to be first telling - "you are supposed to do xyz... ". These usecases when a customer might have done it wrong might be best suited for a Q&A or FAQ IMO.

What do you think?

[Karuna-Mendix]

Hi @satyammx @JaapF, I tried asking Siemens GPT to improve the current section for a more directive tone. It showed the following revision to the text. Let me know if you find it useful.

Guidelines for Unique User Identification (Deduplication)
Mendix offers multi-app user licenses, which allow a single user to access multiple applications while being counted only once for metering purposes. This applies to both internal and external users. Accurate user metering and correct multi-app user deduplication depend critically on consistent user identification across all your applications.

To ensure unique multi-app users are correctly identified and metered, you must maintain a consistent user identifier across all relevant applications.

The Mendix metering mechanism uses the UserCommons.namedUserIdentifier.value attribute as the primary user identifier. If this attribute is not available or populated, it falls back to system.user.name. For a detailed overview of relevant entities and attributes, refer to the "Domain Model Entities" section.

Key Requirements for Multi-App User Identification:

Consistent Identifier Value: The same value for a given multi-app user must be stored in the chosen identifier attribute (UserCommons.namedUserIdentifier.value or system.user.name) across all applications that user accesses. Inconsistent values will result in the user being counted as multiple distinct users.

Best Practices for Choosing and Implementing a Cross-App User Identifier:

User identification strategies can vary across application portfolios, especially if applications were developed independently or use different provisioning methods. Consider the following guidelines to establish a robust and consistent identification strategy:

1. Prioritize UserCommons.namedUserIdentifier.value: Always aim to use and populate UserCommons.namedUserIdentifier.value for user identification. This provides a dedicated field for metering purposes and offers flexibility regardless of the system.user.name value.

2. Use a Stable, Globally Unique Identifier: Select an identifier that is stable and consistently unique across your entire user base and application portfolio.

• Recommended: User's Email Address: Mendix strongly recommends storing the user's email address in UserCommons.namedUserIdentifier.value. This is typically a stable and globally unique identifier that users are familiar with.
• Handling Case Sensitivity: If using email addresses or other text-based identifiers, always store these values in lowercase to prevent metering issues due to case sensitivity. The system.user.name attribute is case-sensitive by design. Mendix's standard SAML, OIDC SSO, and SCIM modules already apply this for email claims received from Identity Providers (IdPs).

3. Address Pairwise Identifiers (e.g., OIDC sub claim): Some identity providers (like Microsoft Entra ID's OIDC sub claim) generate "pairwise" identifiers, which are unique per application for the same user. This is designed to prevent correlation across different service providers but will lead to incorrect multi-app metering within your portfolio.
   Solution for Microsoft Entra ID: If using the OIDC SSO module with Microsoft Entra ID, configure your application to store the oid claim (which contains Entra ID's user object ID) in system.user.name. The oid claim provides a consistent identifier for a multi-app user across all applications.

4. Integrating with Existing Application Logic: If your current applications use varying system.user.name values or different provisioning methods, you can implement UserCommons.namedUserIdentifier.value without altering existing logic.
   Strategy: Continue using your existing application logic for system.user.name if necessary, but additionally implement logic to populate UserCommons.namedUserIdentifier.value with your chosen consistent cross-app identifier (e.g., email address or oid claim). This ensures the metering mechanism has a reliable, consistent identifier to use.

For more information on user types and definitions, refer to the "User Types and Definitions" section.

[satyammx]

@JaapF Since we do not support UserCommons.Nam.... yet from a User Metering perspective, is it wise to call this out OR should we skip?

[satyammx]

@JaapF - this is not a supported entity from a User Metering perspective yet. Will lead to loss of usage data, if csutomers start implementing it.

How do you propose we move forward, considering supporting this additional attribute is not foreseen in the short term.

[satyammx]

@JaapF @Karuna-Mendix
UserCommons.namedUserIdentifier.value
should we refer to this attricbute since this is not yet supported by the Metering sidecar and the metering stack overall?