Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.aptlydone.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Groups are the organizational dimensions Aptly uses to scope authority and access. Every Decision, Delegation, Matrix, Document, User, and Position can be associated with one or more groups, and those associations drive what each user can see, do, and approve across the platform. Two related concepts work together:
  • Group Types — the dimensions available on the tenant (e.g., Organizations, Locations, Departments, plus any custom types). Configured under Settings → Account Settings → Group Types.
  • Groups — the individual records within each enabled type (e.g., “ProxyComm North America” within Organizations; “London HQ” within Locations). Managed under Settings → Groups.
Groups can be created and maintained manually in Aptly or provisioned from external systems via Directory Sync (SCIM) or HRIS integrations. Mapping between source-system attributes and Aptly group types is fully configurable per tenant.

​
🏢 Group Types

Aptly ships with three default Group Types, plus optional custom types for organizations that need additional dimensions.
Group TypeDefault stateNotes
OrganizationsAlways enabledCannot be disabled. Typically used for legal entities.
LocationsEnabled by default; can be disabledOptional dimension for geographic or site-based scoping.
DepartmentsEnabled by default; can be disabledRequired for the Functional delegation pathway.
Custom Group TypesSubscription-tier dependentExamples: Committees, Projects, Properties, Sales Regions, Lines of Business.
Each Group Type has an Address Enabled option that controls whether individual groups in that type can store a postal address. Organizations support addresses by default; Locations, Departments, and custom types only show address fields when Address Enabled is turned on for the type.
If the tenant subscription doesn’t include custom group types, the + Add Group Type control is disabled with an explanatory tooltip. Contact your Aptly account team to enable custom group types if needed.

​
🧩 Hierarchies

Group Types support hierarchical nesting, but the rules differ between Organizations and the other types.

​
Organizations

  • May have one parent, which must be another Organization.
  • Cannot be parented by Locations, Departments, or custom group types.

​
Locations, Departments, and custom group types

  • May have multiple parents.
  • Parents can be from any enabled group type — for example, a Location can be parented by both an Organization and a Department.
  • The model is intentionally flexible to accommodate different organizational structures; there is no required cross-type nesting order.

​
Parent–child inheritance

Parent–child group hierarchies are respected during permission evaluation. A user aligned with a parent group is treated as aligned with that group’s child groups for the purposes of group-scoped role permissions.

​
Example structure

The structure below is one possible model — not a required configuration. Tenants can nest types in whatever order suits their governance model.
  • Aptly Global Holdings (Organization)
    • Aptly North America (Organization)
      • New York HQ (Location)
      • San Francisco Office (Location)
      • Finance (Department)
    • Aptly EMEA (Organization)
      • London HQ (Location)
      • Paris Office (Location)
      • Legal (Department)

​
🎯 Effective group membership

When a permission on a role is set to scope Groups, Aptly evaluates the user’s effective group membership to determine whether the permission applies to a given record. Effective group membership combines:
  • Direct group assignments on the user (Organizations, Locations, Departments, custom types), and
  • Inherited group assignments via the user’s Positions (because Positions can themselves be scoped to one or more groups).
Parent–child inheritance also applies: a user aligned with a parent group is treated as aligned with that group’s children.
Example: a user has no Organizations assigned directly, but their Position is scoped to ProxyComm US. If a Decision is also scoped to ProxyComm US and the user’s role has decision.view set to Groups, the user can view that Decision via inherited group membership from their Position.
This makes Positions a primary lever for managing group-scoped access — assigning a user to a Position that’s properly scoped is often more durable than maintaining direct group assignments on the user.
See Roles & Permissions → for the full permission and scope model, including how All, Groups, None, and the sharing-aware scopes used by Matrices and Documents combine with stakeholder relationships to determine effective access.

​
⚙️ Sync and integrations

Groups can be created and maintained manually in Aptly, or provisioned from external systems alongside users and positions.

​
Directory Sync (SCIM)

When SCIM is configured, Aptly accepts group, user, and position records from your identity provider (e.g., Microsoft Entra ID, Okta). Group records can be mapped from directory attributes such as Company, Department, or Location, with the source-attribute-to-Aptly-group-type mapping configured per tenant.

​
HRIS integrations

HRIS systems (Workday, SAP SuccessFactors, Oracle HCM, etc) can sync groups, users, and positions through the Aptly Integrations Marketplace. Mapping is configurable per integration, and source attributes can be aligned to Aptly group types as needed.

​
Indicators and read-only behavior

  • Synced groups display a sync source indicator in the Aptly UI, with a hover tooltip identifying the source (e.g., “Synced via ADP Workforce Now” or “Managed via Directory Sync”).
  • Synced groups are read-only in Aptly — changes must be made in the source system and re-synced.
  • Manually created groups can coexist with synced groups in the same tenant.

​
Multi-source coexistence

A tenant may have both Directory Sync and one or more HRIS integrations enabled simultaneously. Aptly tracks each synced field’s source integration and uses defined mapping rules to determine which integration is permitted to update each field, preventing accidental overwrites or removals when the same record is referenced by multiple sources.
For SCIM setup, attribute mapping, and provider-specific guidance, see SSO & SCIM Config →.

​
🚦 Lifecycle and changes

Group Types and individual Groups have separate lifecycle behaviors. Both support keeping or removing existing associations when something is disabled or deactivated.

​
Group Type lifecycle (Account Settings → Group Types)

  • Enable / disable — Group Types other than Organizations can be toggled on or off. Disabling a Group Type prompts the admin to choose between Keep Associations and Disable (preserves historical assignments; type is hidden from new records) and Remove Associations and Disable (removes assignments operationally; history is retained in version history).
  • Add custom Group Type — When supported by the tenant subscription, admins can add custom types with a unique name (max 50 characters) and optionally toggle Address Enabled.
  • Edit — Custom Group Types can be renamed and have their Address Enabled setting changed at any time.
  • Delete — Custom Group Types can be deleted only when no groups within the type are associated with any records. Deletion is blocked otherwise.
Departments and the Functional pathway: the Functional delegation pathway depends on Departments being enabled. If Decisions or Delegations still use the Functional pathway, Aptly blocks disabling Departments until those references are removed. See Delegation Lifecycle → for pathway behavior.
Organizations cannot be disabled. Attempting to disable Organizations returns an explanatory message — the type is required.

​
Group lifecycle (Settings → Groups)

  • Edit — Display name, legal name (Organizations), parent groups, and address (where applicable) can be updated via the group’s actions menu.
  • Deactivate — Recommended when a group should no longer be used. Deactivating prompts the admin to choose between Keep Associations and Deactivate (existing associations remain intact) and Remove Associations and Deactivate (associations are removed operationally; history is retained).
  • Delete — Permitted only when the group has no dependencies. Aptly blocks deletion when the group is associated with one or more users, positions, Decisions, or Delegations.
Removing associations from a group used in delegation pathways (especially Functional) can flag downstream delegations as Invalid. After a Remove Associations action, review delegation alerts and remediate as needed. See the Invalid Delegations KB article for full triggers and remediation.

​
🔎 Where Groups are used

Group assignments drive scoping and filtering across the platform:
  • Decisions — define the scope of authority and which groups can issue or receive delegations from the Decision.
  • Delegations — inherit group scope from the parent Decision; can be further restricted, but not expanded, on each delegation.
  • Matrices — scope which decisions, delegations, and personnel appear in the matrix view.
  • Documents — scope visibility and stakeholder eligibility for documents linked to records.
  • Users — direct group assignments contribute to the user’s effective group membership.
  • Positions — group scope on Positions drives inherited group membership for the users assigned to them.
  • Roles & Permissions — the Groups scope on a permission evaluates against the user’s effective group membership and the record’s group assignments.

​
🧾 Related Pages

Need help modeling Group Types and Groups to match your organizational structure, or aligning sync sources from your HRIS or directory? Contact support@aptlydone.com or visit the Aptly Support Portal.