MLM Admin Applet

Overview

The MLM Admin applet is where you run a member-gets-member referral programme. You create a program (a referral campaign with a start and end date), enrol members from Membership Admin as participants, and the applet keeps the lineage — who introduced whom, one upline-to-downline link at a time, up to ten levels deep. New downlines arrive by invitation (an e-mail, SMS or WhatsApp message sent through a contact-centre channel, accepted on a registration page) or by scanning a participant’s QR link, which drops them onto your storefront’s sign-up page with the inviter’s key attached.

The applet records the tree. It pays nobody: the money is an MLM-type scheme in Commission Scheme, and the Sales Commission posting run walks the lineage up from the buyer and writes one commission line per upline level.

Where it fits

Screens and menus

Route root: applets/wavelet/erp/mlm-admin-applet/. Opening the applet lands on Invitations.

Program Create has a single Details tab. Program Edit has five tabs and a Delete button:

The participant’s QR Code tab renders core2/tnt/dm/mlm/programs/{tenantCode}/participant/invite-by-guid/{participantGuid} as a QR image, a copyable link and a PNG download — the self-service invitation link described under Lifecycle.

Settings and Personalization menus

Configuration

Before you can use it

Applet settings

Settings live in an applet-local settings container (not the shared field-configuration component); there is no applet-settings model file in this project. Tenant administrators can open the screens; nothing they save is read.

Model-only keys: none — the project has no settings model. Keys read at runtime without a declaration: none found.

Document behaviour settings

Not applicable — no documents.

Feature visibility / permissions

API permissions are the TNT_API_DM_MLM_* family in MlmPermissions.java (L14–95: OWNER, ADMIN, MEMBER, CREATE, UPDATE, DELETE, READ for each of the six tables) plus TNT_API_DM_MLM_REGISTRATION_{OWNER, ADMIN} (L99–102, marked in source as still to be revised). The acceptance and QR-redirect endpoints are anonymous by design (they are used by people who are not yet users).

Route guards: none — app.routing.ts declares no canActivate. The applet’s own PermissionResolver only maps target tables to services for the shared permission screens. No client-side permission definitions are registered for this applet (0 rows in bl_applet_client_side_perm_dfn for mlm-admin-applet, queried 2026-09-15).

Fields

Program (bl_mlm_program_hdr)

Participant (bl_mlm_program_participant_hdr)

Lineage (bl_mlm_lineage_hdr)

Invitation (bl_mlm_invitation_hdr)

Entity Contact (bl_mlm_entity_contact_hdr)

Communication Endpoint Link (bl_mlm_program_cc_endpoint_link)

Lifecycle and effects

Posting proof: nothing posts, nothing moves. ServerDocTypes.java, JournalPostingTypeHandler.java and GenericDocumentTypeHandler.java contain no entry matching MLM, LINEAGE or REFERRAL (grep at backend commit 45edc03526: zero hits in each). No record in this applet is a generic document; there is no amount or quantity signum, no Dr/Cr equation, no stock processor, nothing for VOID to reverse. Every table carries only status ACTIVE / INACTIVE.

How a downline joins — two paths

    stateDiagram-v2
    [*] --> CREATED : invitation saved in the applet
    CREATED --> SENT : MLM_INVITATION_LINK_PROCESSOR sends via the program's endpoint links
    SENT --> ACCEPTED : invitee registers through mlm/invitation-acceptance
    [*] --> ACCEPTED : QR / storefront sign-up with the inviter's key (SELF_CLICKED)
    ACCEPTED --> LINEAGE_UPDATED : INVITATION_INSERTION_INTO_LINEAGE_PROCESSOR writes the lineage row
    LINEAGE_UPDATED --> [*]
    note right of CREATED
        REJECTED and EXPIRED exist in the enum
        but nothing sets them automatically
    end note
  

Path 1 — an invitation sent by the applet. You create an invitation for one or more invitees. MLM_INVITATION_LINK_PROCESSOR (MlmInvitationLinkProcessor.java L45; registered in JobProcessorClassName.java L272) picks every ACTIVE invitation whose status is CREATED (L154–163), loads the program’s ACTIVE endpoint links in priority order (L142–151), builds the message from a contact-centre template — the template’s <URL-KEY> is replaced by the program’s URL Forward resolved for the inviter, and the inviter’s entity e-mail is copied in (EmailEndpointService.java L53–90) — and sends by SMS (needs an invitee phone), e-mail (needs an invitee e-mail) or WhatsApp (L118–132). On a 2xx reply the status becomes SENT (L176–179); on failure it tries the next link, up to three attempts, then throws (L102–114). The invitee opens the link and posts to POST core2/tnt/dm/mlm/invitation-acceptance (anonymous; MlmRegistrationController.java L29) with the inviter participant guid, first and last name, e-mail or phone, a password and a referral source (MlmRegistrationRequest.java L7–13). If no confirmed login exists for that e-mail or phone, the backend creates a login subject, a registration record that expires in eight hours, and e-mails or texts a six-digit code and registration key (MlmRegistrationService.java L84–114, L270–313, L392–441); the caller then finishes with POST …/invitation-acceptance/password-creation (code, key, password; L477–560). With or without that step, the backend finds or creates the customer entity, finds or creates the membership card, creates the participant, and sets the matching invitation — same inviter and program, same e-mail or phone — to ACCEPTED with the child member and entity filled in (L349–367). No match raises NO INVITATION CONTAINER COULD BE FOUND.

Path 2 — a QR or shared link. Each participant’s QR tab exposes GET core2/tnt/dm/mlm/programs/{tenantCode}/participant/invite-by-guid/{participantGuid} (anonymous; MlmProgramHdrController.java L197–230). It answers with a 302 to the program’s URL Forward with <URL-KEY> replaced by the participant guid, or 404 when the URL lacks the placeholder or is not a valid URL. When the visitor registers on the storefront with that key as invited_by, post-registration (PostRegistrationService.java L95–96) calls TenantUserConfigurationService.stepLinkUserToMLM (L995–1021): it looks the inviter up by guid or invite key (MlmProgramParticipantHdrUow.getByInviteKeyOrGuid L332–341), creates the new user’s entity, membership card and participant with referral source INVITE (L1043–1072), and writes an invitation that is already ACCEPTED, type SELF_CLICKED, lineage type MEMBERSHIP (L1075–1103). A website whose post-registration request sets mlm_enforce_for_all turns a missing key into the hard error INVITE_URL_KEY_NOT_FOUND_BUT_THE_MLM_ENFORCE_FOR_ALL_SET_TO_TRUE (L1016–1018).

Both paths end the same way. INVITATION_INSERTION_INTO_LINEAGE_PROCESSOR (InvitationInsertionIntoLineageProcessor.java L39; registered L265) takes every ACTIVE invitation at ACCEPTED that carries a child member and entity and a parent participant, member and entity (L78–95), requires the child to already be a participant (NO_PARTICIPANT_FOUND otherwise, L141–156), creates the lineage row through MlmLineageHdrService.create — which computes the level — and sets the invitation to LINEAGE_UPDATED (L106–111).

Lineage maintenance. Changing a row’s upline re-levels its whole subtree (MlmLineageHdrService L42–50, MlmLineageHdrUow.updateForChildrenLevels L530–580); deleting a row re-levels the descendants (L90–112). GET …/mlm/lineages/uplines/{participantGuid} and /downlines/{participantGuid} (MlmLineageHdrController.java L249, L271) return the chain each way; Membership Admin’s MLM tab reads them.

Where the money is. The sales-commission posting run (CommissionPostingServices.java) reads the lineage only for a scheme whose Commission Type is MLM (L205): it loads the buyer entity’s participants (L209–210), walks the lineage upward level by level (getMlmUplineMembers L731–752 — level 0 is the buyer, then each parent), and writes one bl_fi_sale_commission_intermediate_processing_txn_line per upline per sales line with the program guid, level, member and upline entity (L273–287), skipping levels whose treatment is zero. The scheme applied is the one the commission cycle selects; the program’s own Commission Scheme field is not consulted — CommissionReportUow.java L460–463 joins the program only to print its name on the report. The member’s referral_code on the membership card is a separate mechanism that no MLM code reads.

Endpoints (all under core2/tnt/dm/mlm/): programs, program-participants (plus POST …/login-ep for a logged-in user to enrol themselves and GET …/login-entity-ep/query for their own participations), lineages (plus /uplines/…, /downlines/…), invitation, entity-contacts, mlm-program-cc-ep-link — each with POST, PUT, DELETE /{guid}, GET, GET /{guid}, GET /query — and the two anonymous acceptance endpoints above.

Related applets

• Membership Admin — participants are its membership cards; its member edit screen’s MLM and Referrals tabs show the tree this applet builds.
• Commission Scheme — the MLM commission type and its per-level treatments (up to ten uplines) are defined there.
• Sales Commission — the posting run that walks the lineage and the report that shows MLM Program and MLM Member per line.
• Customer Maintenance and Entity — the entities behind participants and entity contacts; acceptance creates a customer entity when none exists.
• Unified Contact Center — the e-mail, SMS and WhatsApp endpoints and message templates the invitation processor sends through.
• CP Commerce Admin — the storefront whose sign-up completes the QR path and whose post-registration settings can make the inviter key mandatory.

Troubleshooting

Related documentation

• Membership module
• Membership applets
• Commission Scheme — the MLM commission type
• Integrate an external system — headers for the core2/tnt/dm/mlm/ endpoints