Advanced Portal Designer Documentation
Index

Invitations

APD Invitations allow controlled self-registration for new portal users. Administrators define rules for who can register and what access they receive.

What Are Invitations?

Invitations are rules that:

  • Control who can register
  • Determine automatic settings for new users
  • Assign companies, profiles, and entity mappings
  • Support various validation methods

Invitation Types

There are exactly three invitation types in the source:

Type Description Use Case
Invite Code The user enters a specific code Controlled distribution
E-mail Matches an exact email address Pre-provisioning a single user
E-mail domain Matches the domain portion of the user's email Company-wide access

"Customer No.", "Vendor No." and "No Validation" types are not invitation types in APD — they were not present in any released build. To pre-provision a customer or vendor, use the Invite Code type and set User Type / NAV Identification on the invitation.

Accessing Invitations

  1. Open the Advanced Portal Designer menu page (search for it in Tell Me)
  2. Click Invitations to open the invitation list

Creating Invitations

Invite Code Type

Distribute a specific code to users:

  1. Create new invitation
  2. Set Invitation Type = Invite Code
  3. Enter Invitation Value (the code; APD lower-cases the value on save)
  4. Mark Active = Yes
  5. Configure User Type, NAV Identification, Company, and Security Filters
  6. Save

Example:

Invitation Type: Invite Code
Invitation Value: welcome2024
Active: Yes
Company: CRONUS
Security Filters: CUSTOMER
User Type: Customer
NAV Identification: (leave blank to require the user to provide it)

E-mail Type

Pre-provision a specific user by email:

  1. Create new invitation
  2. Set Invitation Type = E-mail
  3. Enter the user's exact email address as Invitation Value
  4. Mark Active = Yes
  5. Fill in User Type, NAV Identification, Company, Security Filters
  6. Save

Example:

Invitation Type: E-mail
Invitation Value: john@contoso.com
Active: Yes
Company: CRONUS
Security Filters: CUSTOMER
User Type: Customer
NAV Identification: 10000

E-mail Domain Type

Allow any user whose email is in the matching domain to be auto-configured:

  1. Create new invitation
  2. Set Invitation Type = E-mail domain
  3. Enter the bare domain (without @) as Invitation Value — e.g. contoso.com
  4. Mark Active = Yes
  5. Configure settings
  6. Save

Example:

Invitation Type: E-mail domain
Invitation Value: contoso.com
Active: Yes
Company: CRONUS
Security Filters: EMPLOYEE

Anyone authenticating with a contoso.com email picks up these settings.

Invitation Properties

These are the actual fields on the APD Invitation Hgd table:

Field Description
Invitation Type Invite Code, E-mail, or E-mail domain
Invitation Value Code, email, or bare domain to match (lower-cased on save)
Active Boolean — set to Yes for the invitation to be usable
Company Default BC company for matched users
User Type BC Type to apply (Customer, Vendor, Contact, Sales Person)
NAV Identification BC Number to apply (Customer No., Vendor No., etc.) — typed against the chosen User Type
Security Filters Profiles assigned to matched users (filter expression)
Info 2 / Info 3 / Info 4 Free-form metadata (Text / Boolean / Boolean)
Claimed Count Read-only count of how many users have claimed this invitation

APD does not provide an "Expiration Date", "Max Uses", or "Copy Navision Identification" field on invitations. Lifecycle is controlled by the Active boolean — toggle it off when you want to retire a code.

Invitations with External Authentication

Invitations work automatically with Auth0 and Microsoft Entra users through email domain matching.

How It Works

When an external user authenticates for the first time:

  1. APD creates a new user record
  2. APD extracts the email from the identity token
  3. APD checks invitations for:
    • Exact email match (Invitation Type: E-mail)
    • Email domain match (Invitation Type: E-mail domain)
  4. If match found, invitation settings applied to user

Email Domain Invitation for External Auth

This is the most common pattern for external authentication:

Invitation Type: E-mail domain
Invitation Value: contoso.com      (without @)
Company: CRONUS
Security Filters: EMPLOYEE
Navision Type: Customer

Result: All users with @contoso.com email who authenticate via Auth0 or Entra automatically receive:

  • Company assignment
  • Security profile
  • BC entity type

External Auth Invitation Examples

Customer Portal with Entra:

Invitation Type: E-mail domain
Invitation Value: customer.com
Company: CRONUS
Security Filters: CUSTOMER
Navision Type: Customer

Partner Portal with Auth0:

Invitation Type: E-mail domain
Invitation Value: partner.com
Company: CRONUS
Security Filters: PARTNER
Navision Type: Contact

Employee Portal with Entra:

Invitation Type: E-mail domain
Invitation Value: yourcompany.com
Active: Yes
Company: CRONUS
Security Filters: EMPLOYEE
User Type: Sales Person

Not Mapped After Invitation

Even with invitation matching, users may still be Not Mapped if:

  • The invitation sets Navision Type but not NAV Identification
  • The user needs a specific BC record link

Invitation sets:

  • Company ✓
  • Security Filters ✓
  • Navision Type ✓
  • NAV Identification ✗ (user-specific)

The user must still provide or have admin assign their specific Customer No., Vendor No., etc.

Complete External Auth Flow with Invitations

┌──────────────────────────────┐
│ User clicks "Login with      │
│ Microsoft" or "Login with    │
│ Auth0"                       │
└──────────────┬───────────────┘
               ▼
┌──────────────────────────────┐
│ User authenticates with      │
│ external provider            │
└──────────────┬───────────────┘
               ▼
┌──────────────────────────────┐
│ APD receives token           │
│ Email: john@contoso.com      │
└──────────────┬───────────────┘
               ▼
┌──────────────────────────────┐
│ APD creates user record      │
│ NotMapped = true             │
└──────────────┬───────────────┘
               ▼
┌──────────────────────────────┐
│ APD checks invitations       │
│ Finds: E-mail domain =       │
│        contoso.com           │
└──────────────┬───────────────┘
               ▼
┌──────────────────────────────┐
│ Invitation applied:          │
│ • Company = CRONUS           │
│ • Security = CUSTOMER        │
│ • BC Type = Customer         │
│ • NAV ID = (still blank)     │
└──────────────┬───────────────┘
               ▼
┌──────────────────────────────┐
│ User still NotMapped         │
│ (no NAV Identification)      │
│ → Redirected to              │
│   Not Mapped Action          │
└──────────────────────────────┘

Avoiding Not Mapped with Invitations

To fully configure users via invitation (bypassing Not Mapped):

Option 1: Specific Email Invitation

Create invitation for specific user with full mapping:

Invitation Type: E-mail
Invitation Value: john@contoso.com
Company: CRONUS
Security Filters: CUSTOMER
Navision Type: Customer
NAV Identification: 10000

This user won't be Not Mapped because NAV Identification is set.

Option 2: No BC Entity Required

If your portal doesn't need BC entity mapping:

  • Don't set Navision Type in invitation
  • Don't use %4 placeholder in security filters
  • Users won't be Not Mapped

Registration Behavior

Field Description
Active Invitation is usable — set to Yes to enable, No to retire

Registration Process

User Flow

  1. User navigates to registration page
  2. Enters invitation code/validation info
  3. Completes registration form
  4. System validates against invitations
  5. User created with invitation settings
  6. User can log in

Matching Order

APD matches invitations in this order:

  1. Invite Code — exact match of the value the user entered
  2. E-mail — exact match of the user's email
  3. E-mail domain — bare-domain match of the user's email

The first matching, Active invitation applies. There is no fallback "no validation" mode — without a matching invitation, registration is rejected for native auth, and external-auth users are created with no invitation settings (typically ending up in the Not Mapped flow).

Registration Page Template

Basic Registration Form

<form method="post">
    <input type="hidden" name="action" value="REGISTER">

    <div class="form-group">
        <label>Invitation Code</label>
        <input type="text" name="invitecode" required>
    </div>
    
    <div class="form-group">
        <label>Email</label>
        <input type="email" name="email" required>
    </div>
    
    <div class="form-group">
        <label>Desired Username</label>
        <input type="text" name="username" required>
    </div>
    
    <div class="form-group">
        <label>Password</label>
        <input type="password" name="password" required>
    </div>
    
    <div class="form-group">
        <label>Confirm Password</label>
        <input type="password" name="confirmpassword" required>
    </div>
    
    <button type="submit">Register</button>
</form>

Customer Self-Registration

<form method="post">
    <input type="hidden" name="action" value="REGISTER">
    
    <div class="form-group">
        <label>Customer Number</label>
        <input type="text" name="customerno" required>
        <small>Enter your customer number as shown on your invoices</small>
    </div>
    
    <div class="form-group">
        <label>Email</label>
        <input type="email" name="email" required>
    </div>
    
    <!-- Password fields -->
    
    <button type="submit">Register</button>
</form>

Domain-Based Registration

<form method="post">
    <input type="hidden" name="action" value="REGISTER">
    
    <div class="form-group">
        <label>Work Email</label>
        <input type="email" name="email" required 
               pattern=".+@contoso\.com$"
               title="Please use your Contoso email address">
    </div>
    
    <!-- Other fields -->
    
    <button type="submit">Register</button>
</form>

Common Patterns

Multi-Tier Access

Create different invitations for different access levels:

-- Basic customer invitation --
Invitation Code: BASIC2024
Security Filters: CUSTOMER

-- Premium customer invitation --
Invitation Code: PREMIUM2024
Security Filters: CUSTOMER|PREMIUM

Partner Registration

For business partners:

Invitation Type: E-mail domain
Invitation Value: @partner1.com
Company: CRONUS
Security Filters: PARTNER
Navision Type: Customer

Employee Onboarding

For internal users:

Invitation Type: E-mail domain
Invitation Value: yourcompany.com
Active: Yes
Company: CRONUS
Security Filters: EMPLOYEE
User Type: Sales Person

User Type only supports the four BC entity types (Customer, Vendor, Contact, Sales Person). Pick Sales Person for users mapped to a Salesperson/Purchaser record, or leave the type blank if no BC entity link is needed.

Automatic Entity Mapping

To assign a BC entity at registration time, set User Type and NAV Identification on the invitation itself. For example, a per-user invitation with a known Customer No.:

Invitation Type: E-mail
Invitation Value: john@contoso.com
User Type: Customer
NAV Identification: 10000

The matched user is fully mapped on creation and skips the Not Mapped flow.

For a generic domain invitation where the BC entity differs per user, leave NAV Identification blank and either (a) assign it manually in BC, or (b) collect it through a Not Mapped Action template that updates the user record from a script/codeunit action.

Security Considerations

Code Distribution

  • Don't publish invitation codes publicly
  • Distribute through secure channels
  • Consider single-use codes for sensitive access

Validation Strength

Type Security Level
Invite Code High (must know the code)
E-mail High (only that specific address matches)
E-mail domain Low (anyone with a matching domain matches)

Lifecycle

APD does not provide an expiration date or max-use limit on invitations. To retire an invitation, set Active = No on the invitation card. Monitor the Claimed Count field on each invitation to see how many users have claimed it.

Troubleshooting

"Invalid Invitation Code"

  1. Check code is entered correctly
  2. Verify invitation exists and is active
  3. Check expiration date
  4. Check max uses not exceeded

User Not Getting Correct Access

  1. Review invitation settings
  2. Check Security Filters value
  3. Verify invitation matched correctly
  4. Check for conflicting invitations

Multiple Invitations Matching

First matching, Active invitation applies. Matching order is fixed: Invite Code → E-mail → E-mail domain. To prefer an exact email match over a domain match, create the E-mail invitation in addition to the domain invitation — the more specific E-mail match runs first.

Best Practices

Organization

  • Name codes clearly (CUSTOMER2024, VENDOR2024)
  • Document invitation purposes
  • Review and clean up regularly

Security

  • Use strong invitation codes
  • Set appropriate expiration dates
  • Monitor registration activity
  • Disable unused invitations

User Experience

  • Provide clear instructions
  • Show helpful error messages
  • Confirm successful registration