Package edu.internet2.middleware.grouper.app.truefoundry

Class TrueFoundryApiCommands

java.lang.Object
edu.internet2.middleware.grouper.app.truefoundry.TrueFoundryApiCommands
public class TrueFoundryApiCommands extends Object

  • Field Details

    • doNotLogHeaders

      public static final Set<String> doNotLogHeaders

    • grouperLoaderConfig

      public static GrouperLoaderConfig grouperLoaderConfig

    • ROLE_NAME_TEAM_MANAGER

      public static final String ROLE_NAME_TEAM_MANAGER
      The team-manager role is managed internally by TrueFoundry and must not be assigned via the provisioner.
      See Also:

    • ROLE_NAME_TENANT_ADMIN

      public static final String ROLE_NAME_TENANT_ADMIN
      The tenant-admin role is a system role that can be assigned to users but cannot be created, updated, or deleted via the provisioner.
      See Also:

    • TEAM_NAME_EVERYONE

      public static final String TEAM_NAME_EVERYONE
      The "everyone" team is managed internally by TrueFoundry and must not be created, updated, or deleted via the provisioner.
      See Also:

  • Constructor Details

    • TrueFoundryApiCommands

      public TrueFoundryApiCommands()

  • Method Details

    • retrieveSubjectsData

      public static TrueFoundryApiCommands.SubjectsData retrieveSubjectsData(String configId, TrueFoundrySettings settings)
      Retrieve all subjects data in a single call: active users (paginated) AND all teams (with their members and managers) from GET /api/svc/v1/subjects. Teams are deduplicated by ID across pages.
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings (uses ignoreUserEmails)
      Returns:
      SubjectsData with users and teams lists

    • retrieveUsers

      public static List<TrueFoundryUser> retrieveUsers(String configId, boolean includeInactiveUsers, TrueFoundrySettings settings)
      Retrieve all users from TrueFoundry via the subjects endpoint. Uses GET /api/svc/v1/subjects with limit/offset paging. Filters to the users array only (excludes teams, virtualAccounts, externalIdentities).
      Parameters:
      configId - the external system config id
      includeInactiveUsers - true to include deactivated users, false to filter them out
      settings - TrueFoundry settings (uses ignoreUserEmails)
      Returns:
      list of TrueFoundryUser objects

    • retrieveUserByEmail

      public static TrueFoundryUser retrieveUserByEmail(String configId, TrueFoundrySettings settings, String email, boolean includeInactiveUsers)
      Search for a single user by email via the subjects endpoint. Uses GET /api/svc/v1/subjects?query={email}. Returns null if not found (totalUsers=0).
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings
      email - the email to search for
      includeInactiveUsers - true to include deactivated users, false to filter them out
      Returns:
      the matching TrueFoundryUser, or null if not found

    • createUser

      public static TrueFoundryUser createUser(String configId, TrueFoundrySettings settings, TrueFoundryUser user)
      Create a user in TrueFoundry. If the user already exists (including inactive), reactivate and return them. If they don't exist, register a new user and retrieve by email to get the assigned ID. If the user has a displayName and SCIM is configured (tenantName and ssoId are not blank), the display name is set via SCIM PATCH after creation.
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings (uses tenantName, ssoId for SCIM display name, defaultTeamMemberEmail for delete cleanup)
      user - the user to create (must have email set; displayName is optional)
      Returns:
      the created or reactivated TrueFoundryUser with id populated

    • deactivateUser

      public static void deactivateUser(String configId, TrueFoundrySettings settings, String email)
      Deactivate a user in TrueFoundry via PATCH /api/svc/v1/users/deactivate. Sets active=false on the user. Use activateUser to re-enable.
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings
      email - the email of the user to deactivate

    • activateUser

      public static boolean activateUser(String configId, TrueFoundrySettings settings, String email)
      Activate (re-enable) a previously deactivated user via PATCH /api/svc/v1/users/activate.
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings
      email - the email of the user to activate
      Returns:
      true if activated successfully, false if user not found (404)

    • updateUserDisplayName

      public static void updateUserDisplayName(String configId, TrueFoundrySettings settings, String id, String displayName)
      Update the display name of a natively-registered TrueFoundry user via SCIM PATCH. URL: PATCH /api/svc/v1/scim/v2/{tenantName}/{ssoId}/Users/{id} Only call this if both tenantName and ssoId are configured. Do NOT use SCIM to create users — only PATCH existing natively-registered users.
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings (uses tenantName and ssoId)
      id - the native TrueFoundry user ID (not email) used in the SCIM URL
      displayName - the new display name to set

    • assignUserRole

      public static void assignUserRole(String configId, TrueFoundrySettings settings, String email, String roleName)
      Assign a role to a user via PATCH /api/svc/v1/users/roles. resourceType is derived from the role name: "tenant-admin" uses "tenant", all others use "account". The "team-manager" role is system-managed and cannot be assigned via the provisioner. Note: role assignment does not work for SCIM-created users (isEditable=false).
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings
      email - the email of the user to assign the role to
      roleName - the role name (e.g. "member", "read-only-member", "tenant-admin", or a custom role name)

    • retrieveRoles

      public static List<TrueFoundryGroup> retrieveRoles(String configId, TrueFoundrySettings settings)
      Retrieve all roles from TrueFoundry via GET /api/svc/v1/role/list. No paging — all roles returned in one call. Filters to roles with resourceType "account" or "tenant" (provisioner-managed).
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings (uses ignoreRoleNames)
      Returns:
      list of TrueFoundryGroup objects with groupType=role

    • createOrUpdateRole

      public static TrueFoundryGroup createOrUpdateRole(String configId, TrueFoundrySettings settings, TrueFoundryGroup role)
      Create or update a custom role via PUT /api/svc/v1/role (upsert by name). All manifest fields are required: name, displayName, resourceType, description, permissions, type. Returns the created/updated role with its assigned ID. Note: roles should be managed by administrators in the TrueFoundry UI; role create/update is provided for completeness but is generally not invoked by the provisioner.
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings
      role - the role to create or update
      Returns:
      the created/updated TrueFoundryGroup with assigned id

    • deleteRole

      public static void deleteRole(String configId, TrueFoundrySettings settings, String roleId)
      Delete a role by its ID via DELETE /api/svc/v1/role/{id}. Returns 200 on success. 404 is treated as non-fatal (already deleted). Note: roles should be managed by administrators in the TrueFoundry UI; role delete is provided for completeness but is generally not invoked by the provisioner.
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings
      roleId - the TrueFoundry role ID

    • retrieveTeams

      public static List<TrueFoundryGroup> retrieveTeams(String configId, TrueFoundrySettings settings)
      Retrieve all teams from TrueFoundry via GET /api/svc/v1/teams/user. Uses limit/offset paging. pagination.total used to detect end of pages.
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings
      Returns:
      list of TrueFoundryGroup objects with groupType=team

    • getTeamById

      public static TrueFoundryGroup getTeamById(String configId, TrueFoundrySettings settings, String teamId)
      Get a single team by its ID via GET /api/svc/v1/teams/{id}. Returns null if the team is not found (404).
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings
      teamId - the TrueFoundry team ID
      Returns:
      the TrueFoundryGroup, or null if not found

    • createTeam

      public static TrueFoundryGroup createTeam(String configId, TrueFoundrySettings settings, TrueFoundryGroup team)
      Create a new team. TrueFoundry requires at least one member per team at all times. If defaultTeamMemberEmailAddress is provided it is added as the initial member. Memberships are added afterward via addTeamMembers.
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings (uses defaultTeamMemberEmail)
      team - the team (must have name set)
      Returns:
      the created TrueFoundryGroup with assigned id, or null if 409

    • updateTeam

      public static TrueFoundryGroup updateTeam(String configId, TrueFoundrySettings settings, TrueFoundryGroup team)
      Update group-level fields on an existing team (e.g. name) while preserving the current member and manager lists.
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings
      team - the team with updated fields (must have id and name set)
      Returns:
      the updated TrueFoundryGroup, or null if 409

    • addTeamMembers

      public static TrueFoundryGroup addTeamMembers(String configId, TrueFoundrySettings settings, String teamId, List<String> managerEmails, List<String> regularMemberEmails)
      Add multiple members to a team in a single PUT call. Retrieves the current team state, applies all additions at once, then PUTs the full manifest. Regular members are added to the members list; managers are added to both lists. If an email appears in regularMemberEmails and was previously a manager, it is demoted.
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings
      teamId - the team id
      managerEmails - emails to add as team managers (also added to members list)
      regularMemberEmails - emails to add as regular members (removed from managers if present)
      Returns:
      the updated TrueFoundryGroup, or null if 409

    • removeTeamMembers

      public static TrueFoundryGroup removeTeamMembers(String configId, TrueFoundrySettings settings, String teamId, List<String> emailsToRemove)
      Remove multiple members from a team in a single PUT call. Retrieves the current team state, removes all specified emails from both the members and managers lists, then PUTs the full manifest. TrueFoundry requires at least one member per team at all times. If removing all members would leave the team empty, the defaultTeamMemberEmailAddress is kept (or re-added) so the team always has at least one member. The service team is responsible for keeping at least one real person in each team; the default member is a safety net only.
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings (uses defaultTeamMemberEmail)
      teamId - the team id
      emailsToRemove - emails to remove from both members and managers lists
      Returns:
      the updated TrueFoundryGroup, or null if team not found

    • replaceTeamMembers

      public static TrueFoundryGroup replaceTeamMembers(String configId, TrueFoundrySettings settings, String teamId, List<String> memberEmails, List<String> managerEmails)
      Replace the full member and manager lists on a team with a single PUT. Used by the provisioner's replaceGroupMemberships path (replaceMemberships=true on full sync). The team must already exist. TrueFoundry requires at least one member per team, so the defaultTeamMemberEmailAddress is added if the resulting member list would be empty. Managers that are not also in memberEmails are dropped (TrueFoundry requires managers to be members).
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings (uses defaultTeamMemberEmail)
      teamId - the team id
      memberEmails - the full list of desired member emails (managers are typically included too)
      managerEmails - the full list of desired manager emails (may be null or empty)
      Returns:
      the updated TrueFoundryGroup, or null if team not found

    • deleteTeam

      public static void deleteTeam(String configId, TrueFoundrySettings settings, String teamId)
      Delete a team by its ID via DELETE /api/svc/v1/teams/{id}. Retrieves the team first to guard against deleting the system-managed "everyone" team. Returns 200 on success. Returns 404 if not found — treated as non-fatal (already deleted).
      Parameters:
      configId - the external system config id
      settings - TrueFoundry settings
      teamId - the TrueFoundry team ID

    • main

      public static void main(String[] args)
      Manual integration test that exercises every command against a real TrueFoundry instance. Requires grouper-loader.properties configured with a "trueFoundryDev" external system entry. Creates a test user and team, runs all operations, then deletes them for cleanup.

    • validateTrueFoundryName

      public static void validateTrueFoundryName(String name, String context)
      Validate that a TrueFoundry name conforms to the required format: must start with a lowercase letter, end with a lowercase letter or digit, contain only lowercase letters, digits, and hyphens in between, and be between 3 and 36 characters total. Throws a RuntimeException if the name is invalid.
      Parameters:
      name - the name to validate
      context - description for error messages (e.g. "team name", "role name")

    • parseIgnoreSet

      public static Set<String> parseIgnoreSet(String commaSeparated)
      Parse a comma-separated ignore string into a lowercase set for case-insensitive matching.
      Parameters:
      commaSeparated - the comma-separated string (may be null or blank)
      Returns:
      the set of lowercase trimmed values, or null if input is blank