UserManager

Need help? Ask Kademi

Manages profiles, groups and memberships for the current account, and is the main entry point for user administration from apps. Registered as 'userManager', so it is reached from server side JavaScript and from Velocity templates under that name. It covers profile lookup and creation, group and membership maintenance, custom (extra) field storage, membership applications and opt-ins, password resets and two factor authentication, login and login-as tokens, addresses, unsubscribes and duplicate profile merging. Almost every method resolves the current tenant organisation from the request context and refuses to read or write anything outside it, so results are always scoped to the current account.

Group: Managers

Properties

Property	Returns	Description
allRoles	`List<Map<String,String>>`	Every role available in the current account, ie the roles declared by the apps which are active, as maps of name and description sorted by name.
availableRoles	`Map<String,Role>`	The roles offered by the apps currently active for the account, keyed by role name. Use it to present a list of roles an administrator can grant.
currentLoginNonce	LoginNonceBean	The login nonce backing the current request, which lets templates and JavaScript tell whether the session is a login-as session, whether it is read-only, and who started it. Null when there is no current request or the session was not started from a nonce.
currentProfile	`Profile`	The profile of the currently logged in user, or null when the request is anonymous.
dynamicGroups	`List<Group>`	The groups in the current account whose membership is determined by rules rather than by stored membership records.
emailVerificationEnabled	`boolean`	True if email verification is switched on in the user app settings for the current website, or for the current account when there is no website in context.
emailVerificationTokenValidity	`long`
groups	`List<Group>`	Every group defined in the current account, including mailing lists, subscription groups and dynamic rules based groups, but excluding soft deleted ones.
loginAsImpersonatedProfile	`Profile`	For a login-as session, the profile currently being impersonated. Null in an ordinary session.
loginAsInitiatingProfile	`Profile`	For a login-as session, the manager or admin who started the impersonation. Null in an ordinary session.
matchMethods	`List<DuplicateProfileMatchMethod>`	The ways duplicate profiles can be matched in this account - by email, by username, by first and last name, and by each custom field defined on any of the account's groups. Pass one of these to findDuplicates.
openGroups	`List<Group>`	The groups in the current account which users may join themselves, ie those with an open registration mode. The built in public group is excluded.
pendingApplications	`List<GroupMembershipApplication>`	The membership applications the current user is permitted to approve or reject, capped at one hundred. An application qualifies when its organisation is within an organisation where the current user holds the admin or user admin role.
phoneUniqueEnabled	`boolean`	True if the account requires phone numbers to be unique across profiles, which makes updateUser reject a duplicate phone number.
readOnlyLoginAs	`boolean`	True if the current session is a read-only login-as session. The platform already strips write and ACL privileges for such sessions, so controllers should call this to also block mutating actions which are only gated at read content level, eg placing orders, spending points or editing a profile.
userOrgs	`List<Organisation>`

Methods

`streamEventBuilder()`

Returns: StreamEventBeanBuilder

Creates a builder for a StreamEventBean, which is the bean used to add an entry to a profile's activity timeline.

`checkValidPassword(String password, Profile profile)`

Returns: boolean

Checks that the given password complies with every password complexity policy which applies to the profile, ie the policies attached to the groups the profile is a member of. Does not record anything, it just validates.

Parameter	Description
`password`	the plain text password to check
`profile`	the profile whose group password policies are applied

`checkValidPassword(String password, Profile profile, Narrative narrative)`

Returns: boolean

Checks that the given password complies with every password complexity policy which applies to the profile, writing the reason for any failure into the given narrative so it can be shown to the user.

Parameter	Description
`password`	the plain text password to check
`profile`	the profile whose group password policies are applied
`narrative`	optional narrative to collect failure messages, may be null

`isSecondFactorAuthentificationEnabled(Profile profile)`

Returns: Boolean

True if the profile has two factor authentication set up, ie it has a signature credential holding a TOTP secret key.

Parameter	Description
`profile`	the profile to check

`temp2FACode(Profile profile)`

Returns: Temp2FAData

Generates a new, not yet saved TOTP secret key for the profile along with a QR code image of the otpauth enrolment URL, for display in a set up two factor authentication screen. Nothing is persisted until save2FACode is called with the same secret and a code from the user's authenticator. Throws a RuntimeException if the current user is not permitted to edit the profile's password.

Parameter	Description
`profile`	the profile the secret key is being generated for

`save2FACode(Profile profile, String secretKey, String userCode2FA)`

Returns: void

Completes two factor authentication enrolment by verifying that the code the user read from their authenticator matches the given secret key, then deleting any previous signature credentials and saving the new one against the profile. Fires a credential updated event, a funnel event and a reindex of the profile. Throws a RuntimeException if the current user cannot edit the profile's password, if the code does not match, or if the secret key is the same as the one already stored.

Parameter	Description
`profile`	the profile to enable two factor authentication for
`secretKey`	the base32 secret key returned earlier by temp2FACode
`userCode2FA`	the current one time code the user read from their authenticator app

`disable2FA(Profile profile)`

Returns: void

Turns off two factor authentication for the profile by deleting all of its signature credentials, then fires a credential disabled event and a reindex of the profile. Throws a RuntimeException if the current user is not permitted to edit the profile's password.

Parameter	Description
`profile`	the profile to disable two factor authentication for

`blockEntity(BaseEntity blockedEntity, Date blockUntilDate)`

Returns: AccessBlock

Creates and saves an access block which prevents the given profile or organisation from logging in until the given date, and flushes the access block cache so the block takes effect immediately.

Parameter	Description
`blockedEntity`	the profile or organisation to block
`blockUntilDate`	the date the block expires

`findActiveBlocksForEntity(BaseEntity block)`

Returns: List<AccessBlock>

Finds the access blocks on the given entity which are currently in force, ie those whose blocked until date has not yet passed.

Parameter	Description
`block`	the profile or organisation to look up blocks for

`findBlocksForEntity(BaseEntity block)`

Returns: List<AccessBlock>

Finds every access block recorded against the given entity in the current account, including expired ones.

Parameter	Description
`block`	the profile or organisation to look up blocks for

`findBlockById(long id)`

Returns: AccessBlock

Looks up a single access block by its internal id.

Parameter	Description
`id`	the access block id

`deleteBlock(AccessBlock ab)`

Returns: void

Deletes an access block and flushes the access block cache so the entity can log in again immediately. If the block is on a profile, throws a RuntimeException unless the current user is permitted to edit that profile's password.

Parameter	Description
`ab`	the access block to delete

`getCurrentProfile()`

Returns: Profile

The profile of the currently logged in user, or null when the request is anonymous.

`currentOperationAttributes()`

Returns: Map<String,Object>

An in-memory map of attributes attached to the current operation, which lets different parts of the same operation pass values to each other. Returns null when there is no current operation, eg outside of a tracked request or job.

`findRole(String role)`

Returns: Role

Finds a role by name among the roles made available by the apps currently active on the website or account being served. Logs the active app list if the role is not found, which is usually a sign that the app which declares the role is not enabled.

Parameter	Description
`role`	the role name to look for

`addRoleToGroupForRepo(Role foundRole, Group group, Repository r)`

Returns: GroupRole

Grants the role to the group scoped to a single repository, so members of the group hold the role only over that repository's content. Returns the existing grant unchanged if the group already has this role on that repository.

Parameter	Description
`foundRole`	the role to grant, usually obtained from findRole
`group`	the group to grant the role to
`r`	the repository the grant is limited to

`addRoleToGroupForOrg(Role foundRole, Group group, Organisation org)`

Returns: GroupRole

Grants the role to the group scoped to a single organisation, so members of the group hold the role only within that organisation and its children. Returns the existing grant unchanged if the group already has this role within that organisation.

Parameter	Description
`foundRole`	the role to grant, usually obtained from findRole
`group`	the group to grant the role to
`org`	the organisation the grant is limited to

`addRoleToGroupForOwnOrg(Role foundRole, Group group)`

Returns: GroupRole

Grants the role to the group scoped to whichever organisation each membership is within, ie with no explicit repository or organisation restriction. Returns the existing grant unchanged if the group already holds this unrestricted role. Throws a RuntimeException if either argument is null.

Parameter	Description
`foundRole`	the role to grant, usually obtained from findRole
`group`	the group to grant the role to

`newProfileBuilder()`

Returns: ProfileBuilder

Creates a ProfileBuilder, which is the convenient way to create a new profile together with its memberships, custom fields and addresses. Set properties on the builder and then call its build method.

`removeLoginIds(Profile forUser, List<String> nonces)`

Returns: int

Deletes the named login nonces, which revokes the corresponding remembered logins and login-as sessions for the given user. Nonces which do not exist are skipped. Throws a RuntimeException if no user is given, if the current user cannot edit that user's password, or if any nonce belongs to a different profile.

Parameter	Description
`forUser`	the profile whose login nonces are being revoked
`nonces`	the nonce values to delete

`deleteMembership(GroupMembership membership)`

Returns: void

Removes a profile from a group by deleting the given group membership, firing the usual membership removal processing.

Parameter	Description
`membership`	the group membership to delete

`getMembership(Long id)`

Returns: GroupMembership

Looks up a group membership by its internal id, returning it only if it is within the current account.

Parameter	Description
`id`	the group membership id

`isInHomeOrg(Profile profile)`

Returns: boolean

True if the profile's home account is the current account, or is an account nested within it. Profiles with no home account at all are treated as being in the current one.

Parameter	Description
`profile`	the profile to test

`isInHomeOrg(long profileId)`

Returns: boolean

Definitive check of whether the entity with the given id is a profile whose home account is the current account or one nested within it. Returns false if the id does not exist or is not a profile.

Parameter	Description
`profileId`	the internal id of the entity to test

`isInGroup(Profile p, String groupName)`

Returns: boolean

True if the profile is a member of the named group in the current account. Looks the group up by name and then applies the same rules as the group overload, so dynamic rules based groups are evaluated too.

Parameter	Description
`p`	the profile to test
`groupName`	the group name to test membership of

`isInGroup(Profile p, Group group)`

Returns: boolean

True if the profile is a member of the given group, using the profile's cached membership list.

Parameter	Description
`p`	the profile to test
`group`	the group to test membership of

`isInGroup(Profile p, MembershipList mems, Group group)`

Returns: boolean

True if the profile is a member of the given group, checking against a membership list you have already loaded. Everyone is considered a member of the public group, and for a rules based group the rules are evaluated rather than the membership list being consulted.

Parameter	Description
`p`	the profile to test
`mems`	the profile's already loaded membership list
`group`	the group to test membership of

`verifyPassword(Profile user, String password)`

Returns: boolean

Verifies that the given plain text password matches the one saved against the profile. Use this together with login to implement a custom login process.

Parameter	Description
`user`	the profile to check the password against
`password`	the plain text password entered by the user

`login(Profile loginAsProfile)`

Returns: void

Logs the given profile in by setting the login cookies on the current HTTP response. Because this can be a privilege escalation path, the current user must be permitted to edit the target profile's password. Requires a current HTTP request and a current website or account, and the target profile must be enabled.

Parameter	Description
`loginAsProfile`	the profile to log in as

`loginToken(Website website, Branch branch, Profile loginAsProfile, String path)`

Returns: ExtUrl

Builds an external URL for the given path which carries login tokens for the profile, so following it logs the user in. The returned ExtUrl holds the signed URL and the domain name the tokens are valid for. The current user must be permitted to edit the profile's password, and the website must belong to the current account.

Parameter	Description
`website`	the website the URL is for
`branch`	the branch to build the URL against, or null to use the website's live branch
`loginAsProfile`	the profile the login tokens are issued for
`path`	the path within the website the URL should point at

`loginToken(Profile profile)`

Returns: String

Generates a URL signing hash which logs the given profile in, with no reason recorded. Only the currently logged in user may generate a token for themselves, so this throws a RuntimeException if the profile is anyone else or if the context is anonymous.

Parameter	Description
`profile`	the profile the token is issued for, which must be the current user

`loginToken(Profile profile, String reason)`

Returns: String

Generates a URL signing hash which logs the given profile in, recording the given reason against the signature. Only the currently logged in user may generate a token for themselves, so this throws a RuntimeException if the profile is anyone else or if the context is anonymous.

Parameter	Description
`profile`	the profile the token is issued for, which must be the current user
`reason`	free text describing why the token was issued, recorded with the signature

`loginAsToken(String domainName, Profile profile, String reason)`

Returns: String

Creates a login-as token which lets an admin impersonate another user on the given domain. The admin must hold permissions which allow managing the target profile, and a login nonce is saved recording the initiator, the reason, the source IP and user agent, plus any restrictions such as read-only. This is intended for low volume, interactive use, ie a user clicking a button in a page, and should never be used in a background or async task or for bulk operations.

Parameter	Description
`domainName`	the domain the impersonated session will run on, which must belong to the current account
`profile`	the profile to impersonate
`reason`	free text describing why the login-as was started, recorded on the nonce

`isReadOnlyLoginAsInitiator(Profile initiator, Organisation adminOrg)`

Returns: boolean

True if the given login-as initiator, ie the manager or admin performing the login-as, is a member of one of the groups configured for read-only login-as on the given account. Sessions started by such a user have all write and ACL privileges stripped by the security manager.

Parameter	Description
`initiator`	the user starting the login-as
`adminOrg`	the account in which the login-as is happening

`getCurrentLoginNonce()`

Returns: LoginNonceBean

The login nonce backing the current request, which lets templates and JavaScript tell whether the session is a login-as session, whether it is read-only, and who started it. Null when there is no current request or the session was not started from a nonce.

`isReadOnlyLoginAs()`

Returns: boolean

True if the current session is a read-only login-as session. The platform already strips write and ACL privileges for such sessions, so controllers should call this to also block mutating actions which are only gated at read content level, eg placing orders, spending points or editing a profile.

`getLoginAsImpersonatedProfile()`

Returns: Profile

For a login-as session, the profile currently being impersonated. Null in an ordinary session.

`getLoginAsInitiatingProfile()`

Returns: Profile

For a login-as session, the manager or admin who started the impersonation. Null in an ordinary session.

`findEntityById(Long id)`

Returns: BaseEntity

Looks up a profile or organisation by its internal entity id, restricted to entities within the current account.

Parameter	Description
`id`	the internal entity id

`membershipListForOrg(Organisation orgPart)`

Returns: MembershipList

Loads every profile which has a membership within the given organisation and returns their combined membership list. This runs one query per hundred profiles, so it is expensive for large organisations.

Parameter	Description
`orgPart`	the organisation to collect memberships for

`membershipList(ProfileBean p)`

Returns: MembershipList

Returns the membership list for the profile behind the given bean, excluding expired memberships.

Parameter	Description
`p`	the profile bean to resolve and look up memberships for

`membershipList(List<ProfileBean> profileBeans)`

Returns: MembershipList

Returns the combined membership list for all of the given profile beans, loading the memberships in batches of one hundred profiles.

Parameter	Description
`profileBeans`	the profile beans to collect memberships for

`membershipListForProfiles(List<Profile> profiles)`

Returns: MembershipList

Returns the combined membership list for the given profiles, loading the memberships in batches of one hundred.

Parameter	Description
`profiles`	the profiles to collect memberships for

`flushCachedMemberships(Profile p)`

Returns: void

Clears the cached membership list held for the profile in the current account, so the next read reflects membership changes made since the cache was populated. Does nothing if no profile is given.

Parameter	Description
`p`	the profile whose cached memberships should be discarded

`members(List<Profile> profiles)`

Returns: List<GroupMembership>

Loads the group memberships for the given profiles efficiently, using one cached query per batch of one hundred profiles.

Parameter	Description
`profiles`	the profiles to load memberships for

`membershipList(Profile p)`

Returns: MembershipList

Returns the profile's memberships as a MembershipList, which offers filtering by group, organisation and so on. Expired memberships are excluded.

Parameter	Description
`p`	the profile to look up memberships for

`membershipListCached(Profile p)`

Returns: MembershipList

Returns the profile's memberships from the per-account membership cache, so repeated reads in the same request are cheap. Call flushCachedMemberships after changing memberships.

Parameter	Description
`p`	the profile to look up memberships for

`findProfileOrgsWithRoles(Profile p, String roles)`

Returns: List<Organisation>

Finds the organisations in which the profile holds at least one of the named roles, by loading its memberships and filtering them.

Parameter	Description
`p`	the profile to inspect
`roles`	the role names to look for

`membershipList(Profile p, boolean useCache)`

Returns: MembershipList

Returns the profile's memberships, optionally served from a per-request cache so the same profile is not looked up repeatedly. Expired memberships are excluded, and the request cache holds at most one hundred profiles.

Parameter	Description
`p`	the profile to look up memberships for, may be null
`useCache`	true to read from and populate the per-request cache

`membershipListForGroup(Group group)`

Returns: MembershipList

Returns every membership of the given group as a MembershipList. This reads the stored memberships, so it does not evaluate dynamic rules based groups.

Parameter	Description
`group`	the group to list members of

`membershipListForGroup(String groupName)`

Returns: MembershipList

Returns every membership of the named group in the current account as a MembershipList.

Parameter	Description
`groupName`	the group name to look up

`findAddresses(BaseEntity entity)`

Returns: List<EntityAddress>

Finds the address records saved directly against the given profile or organisation in the current account.

Parameter	Description
`entity`	the profile or organisation to look up addresses for

`findAddressByType(BaseEntity entity, String addressType)`

Returns: EntityAddress

Finds the first address saved against the entity whose address type matches exactly, eg 'Home' or 'Billing'.

Parameter	Description
`entity`	the profile or organisation to look up addresses for
`addressType`	the address type to match

`findAllAddresses(BaseEntity entity)`

Returns: Map<String,IReadableAddress>

Returns every address applicable to the entity keyed by address type. This is broader than findAddresses because for a profile it also includes the addresses of the organisations it has a primary membership in.

Parameter	Description
`entity`	the profile or organisation to collect addresses for

`findAllAddresses(BaseEntity entity, boolean includeRelated)`

Returns: Map<String,IReadableAddress>

Returns every address applicable to the entity keyed by address type. Addresses with no street, state, city or postcode are skipped, and for an organisation the organisation's own address is included under its formatted name.

Parameter	Description
`entity`	the profile or organisation to collect addresses for
`includeRelated`	if true, a profile's primary membership organisation addresses are included as well

`findAddress(Profile profile, Long entityAddressId)`

Returns: EntityAddress

Finds one of the profile's addresses by the id of the entity address record, not the id of the address itself. Returns null if the record does not exist or is not linked to the given profile.

Parameter	Description
`profile`	the profile the address must belong to
`entityAddressId`	the entity address id to look for

`updateAddress(Profile profile, FormContext rc)`

Returns: EntityAddress

Creates or updates one of the profile's addresses from submitted form data, taking the address type from the addressType parameter and the record to update from the entityAddressId parameter. When no entityAddressId is supplied a new address is created.

Parameter	Description
`profile`	the profile the address belongs to
`rc`	the form context holding the submitted address fields

`updateAddress(Profile profile, Long entityAddressId, FormContext rc, String type)`

Returns: EntityAddress

Creates or updates one of the profile's addresses from submitted form data. When no entity address id is given a new address is created and linked to the profile, otherwise the existing record is rebound, restamped with the current user and date, and saved. The profile's indexed properties are then refreshed. Throws a RuntimeException if the given entity address id does not belong to the profile.

Parameter	Description
`profile`	the profile the address belongs to
`entityAddressId`	the entity address to update, or null to create a new one
`rc`	the form context holding the submitted address fields
`type`	the address type to store, eg 'Home'

`findAllMembershipApplications(Profile profile)`

Returns: List<GroupMembershipApplication>

Finds every group membership application the profile has submitted in the current account, whatever its state.

Parameter	Description
`profile`	the applicant profile

`findPendingMembershipApplications(Profile profile)`

Returns: List<GroupMembershipApplication>

Finds the group membership applications the profile has submitted in the current account which are still awaiting a decision.

Parameter	Description
`profile`	the applicant profile

`createUser(String email, String nickName)`

Returns: Profile

Creates and saves a new profile in the current account with the given email address and nickname, then queues it for indexing. The username is derived from the email address.

Parameter	Description
`email`	the email address for the new profile
`nickName`	the display nickname for the new profile

`createUserWithId(String userId)`

Returns: Profile

Creates and saves a new profile in the current account with the given username, leaving email, nickname and password unset, then queues it for indexing.

Parameter	Description
`userId`	the username to give the new profile

`removeMember(Profile profile)`

Returns: void

Removes the profile from the current account, recording the current user as the person who did it.

Parameter	Description
`profile`	the profile to remove

`extraFields(Profile p)`

Returns: Map<ExtraField,String>

Returns the profile's custom field values from its primary group memberships, keyed by the field definition so the metadata such as title and type is available alongside each value.

Parameter	Description
`p`	the profile to read custom fields for

`extraFields(Profile p, boolean primaryOnly)`

Returns: Map<ExtraField,String>

Returns the profile's custom field values keyed by the field definition, so the metadata such as title and type is available alongside each value.

Parameter	Description
`p`	the profile to read custom fields for
`primaryOnly`	if true only primary group memberships are considered, otherwise all memberships are

`allExtraFields(GroupMembership gm)`

Returns: Map<ExtraField,String>

Returns every custom field defined on the membership's group together with the value stored on that membership, ordered by the field ordering and then by name. Unlike extraFields this includes fields which have no value yet, and includes file upload fields.

Parameter	Description
`gm`	the membership to read fields and values from

`allExtraFields(Profile p, boolean primaryOnly)`

Returns: Map<ExtraField,String>

Returns every custom field defined on the groups the profile belongs to together with its stored value, ordered by the field ordering and then by name. Unlike extraFields this includes fields which have no value yet, and includes file upload fields.

Parameter	Description
`p`	the profile to read fields and values for
`primaryOnly`	if true only primary group memberships are considered, otherwise all memberships are

`updateProfile(Profile p, FormContext context)`

Returns: Profile

Binds the submitted form parameters onto the profile, stores any custom field values found in the same parameters, then saves the profile and reindexes it. Throws an exception if the current user is not permitted to edit the profile.

Parameter	Description
`p`	the profile to update
`context`	the form context holding the submitted parameters

`updateProfileStatus(Profile profile, Boolean enable)`

Returns: void

Enables or disables the profile, ie controls whether it can log in. Throws a RuntimeException if the profile's home account is not the current account.

Parameter	Description
`profile`	the profile to enable or disable
`enable`	true to enable the profile, false to disable it

`extraFieldValues(Profile p)`

Returns: Map<String,String>

Returns the profile's custom field values as a simple map of field name to value, gathered across every membership within the current account. Fields with a blank value are omitted.

Parameter	Description
`p`	the profile to read custom field values for

`extraFields(MembershipBean bean)`

Returns: Map<ExtraField,String>

Returns the custom field values stored on a single membership, keyed by the field definition so the metadata is available alongside each value.

Parameter	Description
`bean`	the membership to read custom fields from

`extraFieldValue(MembershipBean bean, String fieldName)`

Returns: String

Returns the value of a single named custom field on the given membership.

Parameter	Description
`bean`	the membership to read the custom field from
`fieldName`	the name of the custom field

`updateUser(Profile p)`

Returns: void

Saves changes made to the profile object, lower cases its email address, validates it, flushes its cached memberships and queues it for reindexing. Call this after setting properties on a profile.

Parameter	Description
`p`	the profile to save

`updateUser(Profile p, boolean check)`

Returns: void

Saves changes made to the profile object, flushes its cached memberships and queues it for reindexing, optionally skipping the uniqueness and validity checks. Skipping the checks is only appropriate for bulk operations where the data is already known to be valid.

Parameter	Description
`p`	the profile to save
`check`	true to run the usual validation checks, false to skip them

`addExtraField(Group group, String name, String value)`

Returns: void

Adds or replaces a custom field definition on the group. The group's field set is duplicated before being changed, so existing memberships keep their previous definition set until they are next saved.

Parameter	Description
`group`	the group to add the field definition to
`name`	the field name
`value`	the encoded field definition, eg its type and options, treated as an empty string if null

`removeExtraField(Group group, String name)`

Returns: void

Removes a custom field definition from the group and deletes any profile identifier records built from that field in the current account. Does nothing if the group has no field set.

Parameter	Description
`group`	the group to remove the field definition from
`name`	the field name to remove

`updateExtraFieldOrdering(Group group, String fieldName, int ordering)`

Returns: void

Sets the display ordering of an existing custom field on the group by rewriting the ordering entry in its encoded definition. Does nothing if the group has no field set or no field of that name.

Parameter	Description
`group`	the group holding the field definition
`fieldName`	the field to reorder
`ordering`	the new ordering value, lower sorts first

`storeExtraFields(GroupMembership gm, Map<String,String> parameters)`

Returns: void

Saves custom field values for a single membership from a map of parameters keyed by field name, then reindexes the member. Only fields defined on the membership's group are stored.

Parameter	Description
`gm`	the membership to store the field values on
`parameters`	the submitted values keyed by field name

`storeExtraFields(GroupMembership gm, FormContext form)`

Returns: void

Saves custom field values for a single membership from the parameters and uploaded files of a form submission, then reindexes the member. Only fields defined on the membership's group are stored.

Parameter	Description
`gm`	the membership to store the field values on
`form`	the form context holding the submitted parameters and files

`storeExtraFields(Profile p, Map<String,String> parameters)`

Returns: void

Saves custom field values across all of a profile's memberships, from parameters named as membership id then a dot then the field name, eg 43653.favColour, then reindexes the profile.

Parameter	Description
`p`	the profile whose memberships are being updated
`parameters`	the submitted values keyed by membership id and field name

`extraFieldDefinitions(Group group)`

Returns: List<ExtraField>

Returns the custom field definitions declared on the group, sorted by their ordering and then by name. Use this to render a form for the group's fields.

Parameter	Description
`group`	the group to read field definitions from

`saveToFieldSet(List<ExtraField> extraFields, Map<String,String> parameters, Map<String,FileItem> files)`

Returns: NvSet

Saves the submitted values and uploaded files for the given field definitions into a new name and value set, and returns it so it can be attached to a membership or other entity. Use extraFieldDefinitions to obtain the list of definitions.

Parameter	Description
`extraFields`	the field definitions which describe what to store
`parameters`	the submitted values keyed by field name
`files`	the uploaded files keyed by field name

`uploadExtraFieldFile(FileItem fileItem, List<String> allowedMimeTypes)`

Returns: String

Stores an uploaded file in the account's ExtraField_Files folder so it can be referenced by a file upload custom field, rejecting it if its content type is not in the allowed list.

Parameter	Description
`fileItem`	the uploaded file
`allowedMimeTypes`	the content types which may be accepted

`group(String groupName)`

Returns: Group

Looks up a group in the current account by its name, ie its textual identifier rather than its title.

Parameter	Description
`groupName`	the group name to look for

`group(long id)`

Returns: Group

Looks up a group in the current account by its internal id.

Parameter	Description
`id`	the internal group id

`getGroups()`

Returns: List<Group>

Every group defined in the current account, including mailing lists, subscription groups and dynamic rules based groups, but excluding soft deleted ones.

`getOpenGroups()`

Returns: List<Group>

The groups in the current account which users may join themselves, ie those with an open registration mode. The built in public group is excluded.

`getDynamicGroups()`

Returns: List<Group>

The groups in the current account whose membership is determined by rules rather than by stored membership records.

`findGroupPasswordPolicies(Group group)`

Returns: List<PasswordPolicyBean>

Finds the password complexity policies attached to the given group, as beans suitable for display. These are the policies applied by checkValidPassword to members of that group.

Parameter	Description
`group`	the group to read policies from

`findPasswordPolicyDescription(PasswordPolicyBean passwordPolicy)`

Returns: String

Builds a human readable description of a password policy, eg the minimum length and required character classes, for display next to a password field.

Parameter	Description
`passwordPolicy`	the policy to describe

`findOrg(String orgId)`

Returns: Organisation

Finds an organisation within the current account by its business identifier. Delegates to OrganisationManager.

Parameter	Description
`orgId`	the organisation's business identifier

`findOrgV2(String orgId)`

Returns: Organisation

Finds a non deleted organisation by its business identifier using a single cached query, then checks it is within the current account. An alternative implementation of findOrg which is expected to be faster.

Parameter	Description
`orgId`	the organisation's business identifier

`findOrg(Long id)`

Returns: Organisation

Finds an organisation by its internal id, restricted to organisations beneath the current account.

Parameter	Description
`id`	the internal organisation id

`findOrgTypeByName(String sOrgType)`

Returns: OrgType

Finds an organisation type defined on the current account by its name, eg 'Dealer' or 'Region'.

Parameter	Description
`sOrgType`	the organisation type name

`findOrgTypeById(long id)`

Returns: OrgType

Finds an organisation type defined on the current account by its internal id.

Parameter	Description
`id`	the internal organisation type id

`findBaseEntities(List<Long> ids)`

Returns: List<BaseEntity>

Looks up profiles and organisations by their internal entity ids in a single query, discarding any which are not accessible to the current account. A profile is accessible if it is enabled and either has the current account as its home account or has a membership within it.

Parameter	Description
`ids`	the internal entity ids to look up

`findBaseEntity(Long id)`

Returns: BaseEntity

Looks up a profile or organisation by its internal entity id, returning it only if it is accessible to the current account. A profile is accessible if it is enabled and either has the current account as its home account or has a membership within it.

Parameter	Description
`id`	the internal entity id

`findOrCreateMembership(Profile profile, Group group, Organisation org)`

Returns: GroupMembership

Finds the membership matching the profile, group and organisation, creating it if it does not exist, and returns either the found or the newly created membership. Creating a membership also writes a signup log and fires the signup events, so this can trigger emails and journeys. Throws if the current user would gain privileges by joining the group.

Parameter	Description
`profile`	the profile to make a member
`group`	the group to join
`org`	the organisation the membership sits within

`findOrCreateMembership(Profile profile, Group group, Organisation org, BiConsumer<GroupMembership,SignupLog> membershipCreatedCallback)`

Returns: GroupMembership

Finds the membership matching the profile, group and organisation, creating it if it does not exist. The callback is invoked with the new membership and its signup log before event processing runs, which makes it the right place to store custom fields that the events, eg signup emails, will need to read.

Parameter	Description
`profile`	the profile to make a member
`group`	the group to join
`org`	the organisation the membership sits within
`membershipCreatedCallback`	called with the new membership and signup log before events fire, only when a membership is created

`updateMembership(GroupMembership membership, Group newGroup, Organisation newOrg)`

Returns: void

Moves an existing membership to a different group and organisation, then clears the member's cached memberships. Throws if the current user would gain privileges through the new group.

Parameter	Description
`membership`	the membership to change
`newGroup`	the group the membership should now be in
`newOrg`	the organisation the membership should now sit within

`newMembershipApplication(Profile profile, Group group, Organisation org, FormContext form)`

Returns: GroupMembershipApplication

Creates and saves an application for the profile to join the group, to be approved or rejected later with processPending, and records a registration opt-in log entry with the requester's IP address.

Parameter	Description
`profile`	the applicant
`group`	the group being applied for
`org`	the organisation the membership would sit within
`form`	the form context the application was submitted from

`createOptinLog(Profile profile, Group group)`

Returns: OptInLog

Records a registration opt-in log entry for the profile against the group, capturing the requester's IP address as evidence of consent.

Parameter	Description
`profile`	the profile giving consent
`group`	the group consent was given for

`findByName(String name)`

Returns: Profile

Finds a profile in the current account by its username. Usernames are unique within an account.

Parameter	Description
`name`	the username to look for

`findByEmail(String email)`

Returns: Profile

Finds a profile in the current account by its email address.

Parameter	Description
`email`	the email address to look for

`findByUsernameOrEmail(String userNameOrEmail)`

Returns: Profile

Finds a profile in the current account whose username or email address matches the given value, which is the usual lookup for a login form.

Parameter	Description
`userNameOrEmail`	the username or email address to look for

`findById(Long id)`

Returns: Profile

Looks up a profile by its internal id, not its username. Only returns profiles which are enabled and have the current account as their home account.

Parameter	Description
`id`	the internal profile id

`findAnyById(Long id)`

Returns: ProfileBean

Returns only the safe, non sensitive details of a profile - its id, username and nickname - which means it can be used for profiles belonging to another account, eg super users.

Parameter	Description
`id`	the internal profile id

`findById(Long id, Boolean enabled)`

Returns: Profile

Looks up a profile by its internal id, not its username, restricted to profiles which have the current account as their home account.

Parameter	Description
`id`	the internal profile id
`enabled`	true for enabled profiles only, false for disabled only, or null for no status restriction

`findProfileFieldsById(Long id)`

Returns: Map<String,Object>

Returns a small map of display fields - firstName, surName, email and formattedName - for an enabled profile in the current account, without exposing the profile object itself.

Parameter	Description
`id`	the internal profile id

`selectorsMatch(List<KSelectorItem> selectors, Profile p)`

Returns: boolean

Evaluates a list of audience selectors against a profile in the current account, which is how membership of a dynamic, rules based audience is tested.

Parameter	Description
`selectors`	the selector items describing the audience
`p`	the profile to test

`findMatchingProfiles(ProfileMatchRequest request)`

Returns: List<Profile>

Runs a profile match request, built with newProfileMatchRequest, against the current account and returns the matching profiles. This is a query, so it is expensive for broad criteria.

Parameter	Description
`request`	the match criteria, eg email or phone number

`findMatching(ProfileMatchRequest request)`

Returns: List<ExtProfileBean>

Finds enabled profiles matching the given criteria, eg by phone number or email address, and returns them as beans with their formatted names.

Parameter	Description
`request`	the match criteria, built with newProfileMatchRequest

`findMatching(ProfileMatchRequest included, ProfileMatchRequest excluded)`

Returns: List<ExtProfileBean>

Finds profiles matching the first set of criteria and then removes any which also match the second set, returning the remainder as beans with their formatted names. Both requests are run as separate queries.

Parameter	Description
`included`	the criteria profiles must match
`excluded`	the criteria which excludes a profile, or null to exclude nothing

`newProfileMatchRequest()`

Returns: ProfileMatchRequest

Creates an empty profile match request. Set the search values you want on the returned object and then pass it to findMatching or findMatchingProfiles.

`findProfilesWithExternalAccess()`

Returns: List<Map>

Finds profiles homed in the current account which hold memberships in groups belonging to other accounts, ie users who have been granted access outside their own account. Each entry is a map of the profile's basic details plus a mems list describing those external memberships.

`findProfilesById(Set<Long> ids, Boolean enabled)`

Returns: List<Profile>

Loads profiles by their internal ids, running one query per batch of two hundred ids. Only profiles subordinate to the current account are returned.

Parameter	Description
`ids`	the internal profile ids to load
`enabled`	true for enabled profiles only, false for disabled only, or null for no status restriction

`numProfiles(String q, Organisation org, Group searchGroup)`

Returns: Long

Counts the profiles in the given organisation which match a free text search, optionally limited to one group. This runs a count query, so it is cheaper than loading the profiles themselves.

Parameter	Description
`q`	the free text search term
`org`	the organisation to search within
`searchGroup`	an optional group to limit the search to, may be null

`processOptIns(Profile profile, Group group, Map<String,String> parameters)`

Returns: void

Processes the opt-in choices submitted with a signup form. The optins parameter is read as a comma separated list of group names, and for each one which is a configured opt-in of the signup group the profile is added to that group and an opt-in log entry is written with the requester's IP address. Names which are not configured opt-ins are logged and ignored.

Parameter	Description
`profile`	the profile which submitted the form, ignored if null
`group`	the group being signed up to, whose configured opt-ins are honoured
`parameters`	the submitted form parameters, read for the optins value

`findOptins(Group group)`

Returns: List<OptIn>

Returns the opt-ins configured on the group, ie the other groups a user may choose to also join when signing up to this one.

Parameter	Description
`group`	the signup group to read opt-ins from

`findChildMembershipByField(String groupName, String fieldName, Object ovalue, boolean contains)`

Returns: MembershipBean

Finds the first membership of the named group whose given custom field holds the given value, caching the result on the current root folder so repeated lookups within the same site are cheap. Warns if more than one membership matches. Never throws - any failure is logged and null is returned.

Parameter	Description
`groupName`	the group whose memberships are searched
`fieldName`	the custom field to match on
`ovalue`	the value to match, converted to a string, null returns null
`contains`	true to match on the value being contained in the field, false for an exact match

`mergeProfiles(ProfileBean mergeDestination, List<ProfileBean> mergeSources)`

Returns: void

Merges each of the source profiles into the destination profile, moving their memberships and related records across. The current user must be permitted to edit every profile involved, otherwise a RuntimeException is thrown.

Parameter	Description
`mergeDestination`	the profile which is kept and receives the merged data
`mergeSources`	the profiles to merge in and discard

`mergeProfiles(Profile mergeDest, List<Long> mergeSources)`

Returns: int

Merges the profiles with the given ids into the destination profile, moving their memberships and related records across, and writes a lead note on the destination recording where the data came from. Duplicate ids and the destination's own id are ignored, and the current user must be permitted to edit each source profile.

Parameter	Description
`mergeDest`	the profile which is kept and receives the merged data
`mergeSources`	the internal ids of the profiles to merge in and discard

`groups()`

Returns: List<Group>

Every group in the current account which has not been soft deleted.

`orgTypes()`

Returns: List<OrgType>

Every organisation type defined on the current account, eg 'Dealer' or 'Region'.

`toProfileBean(Profile p)`

Returns: ExtProfileBean

Wraps a profile in an extended profile bean, which exposes its formatted name and is safe to hand to templates and JavaScript.

Parameter	Description
`p`	the profile to wrap

`toProfileBean(UserResource user)`

Returns: ExtProfileBean

Wraps the profile behind a user resource in an extended profile bean, which exposes its formatted name and is safe to hand to templates and JavaScript.

Parameter	Description
`user`	the user resource whose profile should be wrapped

`toGroupMembership(MembershipBean bean)`

Returns: GroupMembership

Resolves the underlying group membership entity from a membership bean.

Parameter	Description
`bean`	the membership bean to unwrap

`toOrgData(Organisation org)`

Returns: OrgData

Wraps an organisation in an OrgData bean, which is the form used in templates and JavaScript.

Parameter	Description
`org`	the organisation to wrap

`toOrg(OrgData od)`

Returns: Organisation

Resolves the underlying organisation entity from an OrgData bean.

Parameter	Description
`od`	the organisation data bean to unwrap

`toOrgList(List<OrgData> orgDatas)`

Returns: List<Organisation>

Resolves the underlying organisation entities from a list of OrgData beans.

Parameter	Description
`orgDatas`	the organisation data beans to unwrap, may be null

`findHighest(List<Organisation> orgs)`

Returns: Organisation

Returns whichever of the given organisations sits highest in the account's organisation hierarchy, ie the one with the fewest parents between it and the account.

Parameter	Description
`orgs`	the organisations to compare

`orgDepth(Organisation org)`

Returns: int

How many levels below the current account the given organisation sits, counting parent links. The account organisation itself has a depth of zero.

Parameter	Description
`org`	the organisation to measure

`members(Group group, Organisation org)`

Returns: List<Profile>

Finds the distinct profiles which have a stored membership of the given group within the given organisation. This reads membership records only, so dynamic rules based groups are not evaluated - use findMembers for those.

Parameter	Description
`group`	the group to list members of
`org`	the organisation the memberships must be within

`findMembers(Group group)`

Returns: List<Profile>

Finds every member of the group, evaluating the rules for a dynamic group and reading membership records for a normal one. Loads all members, so this is expensive for large groups.

Parameter	Description
`group`	the group to list members of

`findMembers(Group group, Organisation withinOrg, Boolean withPassword, Boolean enabledProfiles, SearchProperties props)`

Returns: List<GroupMembership>

Finds group memberships matching the given filters, one page at a time. Reads stored membership records, so dynamic rules based groups are not evaluated.

Parameter	Description
`group`	the group to filter on, or null for any group
`withinOrg`	the organisation the membership must be within, or null for any
`withPassword`	true for members who have a credential, false for those who do not, null for either
`enabledProfiles`	true for enabled members, false for disabled, null for either
`props`	paging and sorting for the result

`countMembers(Group group, Organisation withinOrg, Boolean withPassword, Boolean enabledProfiles)`

Returns: long

Counts the distinct memberships matching the same filters as findMembers, using a count query rather than loading the rows.

Parameter	Description
`group`	the group to filter on, or null for any group
`withinOrg`	the organisation the membership must be within, or null for any
`withPassword`	true for members who have a credential, false for those who do not, null for either
`enabledProfiles`	true for enabled members, false for disabled, null for either

`countMemberOrgs(Group group, Organisation withinOrg, Boolean withPassword, Boolean enabledProfiles)`

Returns: long

Counts the distinct organisations which the memberships matching the given filters sit within, using a count query rather than loading the rows.

Parameter	Description
`group`	the group to filter on, or null for any group
`withinOrg`	the organisation the membership must be within, or null for any
`withPassword`	true for members who have a credential, false for those who do not, null for either
`enabledProfiles`	true for enabled members, false for disabled, null for either

`numMembers(Group group)`

Returns: Long

Counts the members of the group. Works for both stored and dynamic rules based groups, evaluating the rules where necessary, so it can be expensive for a large dynamic group.

Parameter	Description
`group`	the group to count members of

`membersQuery(Group group)`

Returns: KQueryResult

Returns a query result which iterates over every member of the group in pages of one thousand, so large groups can be processed without loading them all at once. Call breakUseResults on the result to stop part way through.

Parameter	Description
`group`	the group to iterate the members of

`members(Group group, SearchProperties props)`

Returns: List<Profile>

Finds one page of the profiles which are members of the given group.

Parameter	Description
`group`	the group to list members of
`props`	paging and sorting for the result

`memberships(Organisation org)`

Returns: List<GroupMembership>

Finds every group membership which sits within the given organisation.

Parameter	Description
`org`	the organisation to list memberships for

`memberships(Group group)`

Returns: List<GroupMembership>

Finds every stored membership of the given group, across all organisations. Dynamic rules based groups are not evaluated.

Parameter	Description
`group`	the group to list memberships of

`memberships(Group group, Organisation org)`

Returns: List<GroupMembership>

Finds the memberships of the given group which sit within the given organisation.

Parameter	Description
`group`	the group to list memberships of
`org`	the organisation the memberships must be within

`memberships(Profile profile, Organisation org)`

Returns: List<GroupMembership>

Finds the profile's memberships which sit within the given organisation.

Parameter	Description
`profile`	the profile to list memberships for
`org`	the organisation the memberships must be within

`memberships(Profile profile, Group group)`

Returns: List<GroupMembership>

Finds the profile's memberships of the given group. There can be more than one where the profile belongs to the group in several organisations.

Parameter	Description
`profile`	the profile to list memberships for
`group`	the group to filter on

`memberships(Profile profile)`

Returns: List<GroupMembership>

Finds all of the profile's memberships within the current account.

Parameter	Description
`profile`	the profile to list memberships for

`memberships(Profile profile, OrgType teamOrgType)`

Returns: List<GroupMembership>

Finds the profile's memberships which sit within an organisation of the given organisation type, eg all of the user's dealer memberships.

Parameter	Description
`profile`	the profile to list memberships for
`teamOrgType`	the organisation type the membership's organisation must have

`setMembershipField(MembershipBean membershipBean, String fieldName, String fieldValue)`

Returns: void

Sets a single custom field value on the membership and fires a profile updated event so downstream processing, eg journeys and indexing, sees the change.

Parameter	Description
`membershipBean`	the membership to set the field on
`fieldName`	the custom field name
`fieldValue`	the value to store

`findDuplicates(DuplicateProfileMatchMethod matchMethod, MergeDestMode mode)`

Returns: List<DuplicateProfilesList>

Finds groups of duplicate profiles in the current account using the given match method, eg by email address, username, name or a custom field. Each returned list holds the matched value, how many profiles share it, the profiles themselves, and which of them the given mode nominates as the merge destination. This scans the account's profiles, so it is expensive.

Parameter	Description
`matchMethod`	how profiles are considered duplicates, from getMatchMethods
`mode`	which profile in each duplicate set is nominated as the merge destination - oldest, newest or numericId

`getMatchMethods()`

Returns: List<DuplicateProfileMatchMethod>

The ways duplicate profiles can be matched in this account - by email, by username, by first and last name, and by each custom field defined on any of the account's groups. Pass one of these to findDuplicates.

`findGroupByName(String groupName)`

Returns: Group

Finds a group in the current account by name using a cached query, taking the lowest id if the name is somehow duplicated.

Parameter	Description
`groupName`	the group name to look for

`findGroupById(Long id)`

Returns: Group

Finds a group by its internal id, restricted to groups belonging to the current account.

Parameter	Description
`id`	the internal group id

`findByOrg(Organisation team)`

Returns: List<Profile>

Finds the distinct profiles which have any membership within the given organisation, sorted by formatted name.

Parameter	Description
`team`	the organisation to list people for

`findByOrgType(OrgType ot)`

Returns: List<Profile>

Finds the distinct profiles which have a membership within any organisation of the given organisation type, sorted by formatted name. This walks every organisation of that type, so it is expensive on a large hierarchy.

Parameter	Description
`ot`	the organisation type to collect people from

`getPendingApplications()`

Returns: List<GroupMembershipApplication>

The membership applications the current user is permitted to approve or reject, capped at one hundred. An application qualifies when its organisation is within an organisation where the current user holds the admin or user admin role.

`pendingApplications(int max)`

Returns: List<GroupMembershipApplication>

The membership applications the current user is permitted to approve or reject, capped at the given number. An application qualifies when its organisation is within an organisation where the current user holds the admin or user admin role.

Parameter	Description
`max`	the largest number of applications to return

`pendingApplicationsCount()`

Returns: int

How many membership applications the current user is permitted to approve or reject, with no cap. Useful for a badge or counter in an admin menu.

`hasAdminUserRole(Organisation memberOrg)`

Returns: boolean

True if the current user holds the admin or user admin role either within the given organisation or across the account as a whole. Use it to decide whether to show user administration functions.

Parameter	Description
`memberOrg`	the organisation to test the roles within

`hasRole(Profile user, String roleName)`

Returns: boolean

True if the user holds the named role anywhere in the current account.

Parameter	Description
`user`	the profile to test
`roleName`	the role name to look for

`hasRole(Profile user, String roleName, Organisation memberOrg)`

Returns: boolean

True if the user holds the named role within the given organisation.

Parameter	Description
`user`	the profile to test
`roleName`	the role name to look for
`memberOrg`	the organisation to test the role within

`getRoles(Profile p)`

Returns: Set<Role>

The roles the profile holds across the current account, resolved from its group memberships and the group role grants.

Parameter	Description
`p`	the profile to read roles for

`processPending(GroupMembershipApplication gma, Boolean b)`

Returns: void

Approves or rejects a membership application. If email verification is enabled for the account, the latest active verification request for the applicant's email address is looked up and processed along with it.

Parameter	Description
`gma`	the membership application to decide, ignored if null
`b`	true to approve the application, false to reject it, ignored if null

`processPending(GroupMembershipApplication gma, EmailValidationRequest emailValidationRequest, Boolean b)`

Returns: void

Approves or rejects a membership application, and marks the given email validation request as used. On approval the membership is created, any new organisation described on the application is created with its address, type and organisation custom fields, the application's custom field values are copied onto the new membership, and the member is reindexed. On rejection a rejected subscription event is fired instead. Throws a RuntimeException if the application's organisation is not within its account.

Parameter	Description
`gma`	the membership application to decide, ignored if null
`emailValidationRequest`	an email validation request to approve at the same time, may be null
`b`	true to approve the application, false to reject it, ignored if null

`onRejectedMembership(GroupMembershipApplication gma)`

Returns: void

Fires the rejected subscription event for a membership application, which is what triggers any configured rejection emails and journeys. Called for you by processPending when an application is rejected.

Parameter	Description
`gma`	the rejected membership application

`timelineItems(Profile p)`

Returns: List<StreamEventBean>

Builds the profile's activity timeline by asking every active app which contributes to profile pages for its entries, sorted newest first and capped at one thousand items. An exception from one app is logged and does not stop the others contributing.

Parameter	Description
`p`	the profile to build the timeline for

`timelineItems(UserResource userRes)`

Returns: List<StreamEventBean>

Builds the timeline for a user resource by asking every active app which contributes to profile pages for its entries, sorted newest first and capped at one thousand items. An exception from one app is logged and does not stop the others contributing.

Parameter	Description
`userRes`	the user resource to build the timeline for

`setPassword(Profile user, String newPassword)`

Returns: void

Sets the user's password, applying the password complexity policies which are in force for that user in the current account.

Parameter	Description
`user`	the profile to set a password on
`newPassword`	the new plain text password

`generatePasswordReset(Profile user, Website website)`

Returns: PasswordReset

Creates and saves a password reset request for the user, with a token and a return URL pointing at the website's do-reset page. Send the token to the user, then look it up again with findPasswordReset when they follow the link.

Parameter	Description
`user`	the profile the reset is for
`website`	the website the reset link should return to

`findPasswordReset(String token, Website website)`

Returns: PasswordReset

Looks up a password reset request by its token on the given website, which is how a reset link is validated.

Parameter	Description
`token`	the reset token from the link
`website`	the website the reset was issued for

`findPasswordReset(Profile profile, String token, Website website)`

Returns: PasswordReset

Looks up a password reset request by its token, requiring that it was issued to the given profile on the given website.

Parameter	Description
`profile`	the profile the reset must belong to
`token`	the reset token from the link
`website`	the website the reset was issued for

`updateProfilesForOrg(Organisation org)`

Returns: void

Reindexes every distinct profile which holds a membership within the given organisation, without running the usual validation checks. Does nothing when the organisation is an account root, because reindexing every profile in an account is too expensive.

Parameter	Description
`org`	the organisation whose members should be reindexed

`isPhoneUniqueEnabled()`

Returns: boolean

True if the account requires phone numbers to be unique across profiles, which makes updateUser reject a duplicate phone number.

`getAllRoles()`

Returns: List<Map<String,String>>

Every role available in the current account, ie the roles declared by the apps which are active, as maps of name and description sorted by name.

`newAddressBean()`

Returns: AddressBean

Creates an empty address bean to be populated and passed to code which accepts an address, eg a membership application request.

`isEmailVerificationEnabled()`

Returns: boolean

True if email verification is switched on in the user app settings for the current website, or for the current account when there is no website in context.

`findEmailVerificationSubject(WebsiteRootFolder websiteRootFolder)`

Returns: String

The configured subject line for email verification messages, taken from the user app settings of the given website, or of the current website or account when none is given.

Parameter	Description
`websiteRootFolder`	the website to read the setting from, or null to use the current website or account

`findLatestActiveRequest(Profile profile)`

Returns: EmailValidationRequest

Finds the most recent email validation request for the profile which has not yet been used.

Parameter	Description
`profile`	the profile to look up a request for

`sendEmailVerification(GroupMembershipApplication groupMembershipApplication)`

Returns: EmailValidationRequest

Creates an email validation request for the email address on a membership application and sends the verification email to it.

Parameter	Description
`groupMembershipApplication`	the application whose applicant email should be verified

`sendEmailVerification(Profile profile, String email, Website website)`

Returns: EmailValidationRequest

Creates an email validation request for the given address on behalf of the profile and sends the verification email to it. Use this to verify a changed email address before it replaces the one on the profile.

Parameter	Description
`profile`	the profile the address is being verified for
`email`	the address to verify
`website`	the website the verification link should return to

`findValidEmailVerificationRequestByToken(String token, Date currentDate, Narrative narrative)`

Returns: EmailValidationRequest

Looks up an unused email validation request by its token and checks it has not expired, using the token validity configured in the user app settings. When it fails, the reason is recorded on the narrative as either tokenNotFound or tokenExpired so the page can show the right message.

Parameter	Description
`token`	the verification token from the link
`currentDate`	the date to test expiry against, normally now
`narrative`	optional narrative to receive the failure reason, may be null

`approveEmailVerificationRequest(EmailValidationRequest emailValidationRequest, Date approvedDate, boolean fireUserUpdateEvent)`

Returns: EmailValidationRequest

Marks an email validation request as used and, when the verified address differs from the one on the profile, copies the verified address onto the profile. Optionally saves and reindexes the profile at the same time.

Parameter	Description
`emailValidationRequest`	the request to approve
`approvedDate`	the date to record as the used date
`fireUserUpdateEvent`	true to save and reindex the profile, firing the usual profile update processing

`newMembershipApplicationRequest()`

Returns: MembershipApplicationRequest

Creates an empty membership application request. Set the group, member, custom fields and any new organisation details on it, then pass it to submitMembershipApplicationRequest.

`submitMembershipApplicationRequest(MembershipApplicationRequest mar)`

Returns: GroupMembershipApplication

Saves a membership application from the given request, including any new organisation details serialised onto it, optionally sends the email verification message, records a registration opt-in log entry with the requester's IP address, and fires the pending subscription event.

Parameter	Description
`mar`	the populated membership application request

`onPendingMembership(GroupMembershipApplication gma)`

Returns: void

Fires the pending subscription event for a membership application, which is what triggers any configured notification emails and journeys. Called for you by submitMembershipApplicationRequest.

Parameter	Description
`gma`	the newly submitted membership application

`membershipOrgProperties(GroupMembershipApplication gma)`

Returns: Map<String,Object>

Returns the organisation details carried by a membership application, either the new organisation the applicant asked to create or the existing organisation they applied within. Older applications store just a title, newer ones store title, orgId, address, orgTypeName and orgFields.

Parameter	Description
`gma`	the membership application to read organisation details from

`findUnsubs(Profile p)`

Returns: List<Unsubscribe>

Finds the unsubscribe records in the current account which are linked either to the given profile or to its email address.

Parameter	Description
`p`	the profile to look up unsubscribes for

`findUnsubs(String groupName, SearchProperties searchProperties)`

Returns: List<Unsubscribe>

Finds one page of the unsubscribe records in the current account, optionally limited to unsubscribes from a single group.

Parameter	Description
`groupName`	the group to limit the results to, or blank for all groups
`searchProperties`	paging and sorting for the result

`findUnsubs(SearchProperties searchProperties)`

Returns: List<Unsubscribe>

Finds one page of all the unsubscribe records in the current account.

Parameter	Description
`searchProperties`	paging and sorting for the result

`countUnsubs()`

Returns: long

Counts every unsubscribe record in the current account.

`countUnsubs(String groupName)`

Returns: long

Counts the unsubscribe records in the current account. Note that the group name is currently accepted but not applied, so the result is the account wide count either way.

Parameter	Description
`groupName`	the group name, currently not applied to the count

`findUnsubGroupSummary()`

Returns: List<GroupSignupStat>

Summarises which groups the account's unsubscribed profiles had signed up to, as a count of signups per group. Loads every unsubscribe record in the account, so it is expensive.

`findUnsubProfileIdsByOrg()`

Returns: List<Long>

The internal ids of the profiles which have unsubscribed in the current account, served from a cache which is refreshed at most once a minute. Intended for filtering a send list cheaply.

`findUnsubEmailsByOrg()`

Returns: List<String>

The email addresses which have unsubscribed in the current account, served from a cache which is refreshed at most once a minute. Intended for filtering a send list cheaply.

`hasOrgType(Organisation org, OrgType expectedOrgType)`

Returns: boolean

True if the organisation has been given the specified organisation type. An organisation can hold several types at once.

Parameter	Description
`org`	the organisation to test
`expectedOrgType`	the organisation type to look for

`findProfileAndFields(Group g, String fieldName)`

Returns: List<ProfileAndField>

For the given group and custom field, returns one entry per distinct combination of profile and field value, holding the profile id, username and the stored value. Useful for reporting on or exporting a single custom field across a group.

Parameter	Description
`g`	the group whose memberships are read
`fieldName`	the custom field to read

`fireProfileActiveEvent(Website website, Profile p)`

Returns: void

Fires the profile active event against the website's live branch, which is how apps are told that the profile has just been active on that site. Throws a RuntimeException if no website is given, and does nothing if no profile is given.

Parameter	Description
`website`	the website the activity happened on
`p`	the profile which was active, ignored if null

`getAvailableRoles()`

Returns: Map<String,Role>

The roles offered by the apps currently active for the account, keyed by role name. Use it to present a list of roles an administrator can grant.

`createRulesGroup(String name, String title, String json)`

Returns: Group

Creates a dynamic group whose membership is determined by the given rules rather than by stored membership records. The group is created closed, since members are matched by the rules rather than joining.

Parameter	Description
`name`	the group name, ie its textual identifier
`title`	the group's display title, defaults to the name if blank
`json`	the membership rules as JSON

`createGroup(String name, String title, String groupType, String regoMode)`

Returns: Group

Creates and saves a group with the given name and properties in the current account. An unrecognised group type falls back to primary, and an unrecognised registration mode falls back to closed. Throws a RuntimeException if a group with that name already exists.

Parameter	Description
`name`	the group name, ie its textual identifier
`title`	the group's display title, defaults to the name if blank
`groupType`	P for primary, M for mailing list, R for rules based or S for subscription
`regoMode`	o for open, c for closed or a for admin approval

`deleteGroup(Group group)`

Returns: void

Soft deletes a group. It fires the group deleted event, removes the group from email recipient lists, clears it from any email trigger which joined or removed members from it, then marks it deleted and renames it so the name can be reused. Throws a RuntimeException if the group belongs to another account.

Parameter	Description
`group`	the group to delete

`newConfigMessage(String level, String message)`

Returns: ConfigMessage

Creates a configuration message with no title, for showing a warning or error about an app's configuration on an admin page.

Parameter	Description
`level`	the message severity, eg 'warning' or 'danger'
`message`	the detail text to show

`newConfigMessage(String level, String title, String message)`

Returns: ConfigMessage

Creates a configuration message with a heading, for showing a warning or error about an app's configuration on an admin page.

Parameter	Description
`level`	the message severity, eg 'warning' or 'danger'
`title`	a short heading summarising the issue, eg 'Connected to the wrong type of organisation'
`message`	the full detail text shown beneath the title

`findNonces(Profile profile, Date start, Date finish)`

Returns: List<LoginNonce>

Finds the login nonces created for the profile in the current account between the two dates, ie its remembered logins and login-as sessions over that period.

Parameter	Description
`profile`	the profile to list nonces for
`start`	the earliest creation date to include
`finish`	the latest creation date to include

`findAuditStats(Profile p)`

Returns: Map<Date,Integer>

Counts the recorded changes to the profile by day, over the most recent one thousand audit records. Suitable for drawing an activity chart.

Parameter	Description
`p`	the profile to summarise audit history for

`findAuditItems(Profile p, Integer max)`

Returns: List<AuditItem>

Finds the audit records for changes to the profile in the current account, newest first. The maximum is capped at one thousand, which is also the default when none is given.

Parameter	Description
`p`	the profile to read audit history for
`max`	the largest number of records to return, capped at 1000

`hasCredentials(Profile p)`

Returns: boolean

True if the profile has at least one credential, ie a password or another sign-in credential such as a two factor secret.

Parameter	Description
`p`	the profile to test

`isValidUserName(String value)`

Returns: boolean

True if the value is usable as a username, ie it is not blank and contains none of the characters which are illegal in a username - space, the two slashes, question mark, ampersand and the angle brackets.

Parameter	Description
`value`	the candidate username

`findPasswordReset(Profile profile, Website website, String shortCode)`

Returns: PasswordReset

Looks up a password reset request by the short code the user typed in, requiring it to have been issued to the given profile on the given website. Short codes are the alternative to a reset link, eg for a code sent by text message.

Parameter	Description
`profile`	the profile the reset must belong to
`website`	the website the reset was issued for
`shortCode`	the short code the user entered

`generatePasswordReset(Profile user, Website website, String shortCode)`

Returns: PasswordReset

Creates and saves a password reset request carrying the given short code, so the user can complete the reset by typing the code rather than following a link.

Parameter	Description
`user`	the profile the reset is for
`website`	the website the reset belongs to
`shortCode`	the short code to issue to the user

`subscriptionAction(String action)`

Returns: SubscriptionAction

Converts a string into a subscription action constant, matching case insensitively. Throws an IllegalArgumentException if the name is not a valid action.

Parameter	Description
`action`	the action name, eg 'pending', 'accepted' or 'rejected'

`homeAdminOrgInfo(Profile p)`

Returns: HomeOrgInfo

Returns basic details of the profile's home account - its id, admin domain, path and title - which are otherwise not readable when the home account is a different tenant.

Parameter	Description
`p`	the profile to describe the home account of

`findPrimaryMemberships(Profile p)`

Returns: MembershipList

Returns only the profile's primary group memberships, ie those in groups of the primary type, which are the ones that place a user in an organisation.

Parameter	Description
`p`	the profile to read memberships for

`findPrimaryMembershipsOrgs(Profile p)`

Returns: OrgDataList

Returns the organisations the profile belongs to through its primary memberships, as organisation data beans.

Parameter	Description
`p`	the profile to read memberships for

`findPrimaryMembershipsOrgs(Profile p, boolean nonRoot)`

Returns: OrgDataList

Returns the organisations the profile belongs to through its primary memberships, as organisation data beans, optionally leaving out the account root organisation.

Parameter	Description
`p`	the profile to read memberships for
`nonRoot`	true to exclude the account root organisation from the result

`unsubscribe(Profile profile, Website website)`

Returns: void

Unsubscribes the profile from marketing communications in the current account, recording the website it happened on where one is given.

Parameter	Description
`profile`	the profile to unsubscribe
`website`	the website the unsubscribe was made from, optional

`invalidateNonce(String nonce)`

Returns: void

Invalidates a login nonce so the remembered login or login-as session it backs can no longer be used. Blank nonces, unknown nonces and nonces belonging to another account are logged and ignored.

Parameter	Description
`nonce`	the nonce value to invalidate

`addToGroupWithoutEvent(Profile profile, Group groupToJoin, Organisation orgToJoin)`

Returns: GroupMembership

Adds the profile to the group within the given organisation and writes a signup log, but fires no events and does not reindex the profile. You must call updateUser afterwards so the profile index reflects the new membership.

Parameter	Description
`profile`	the profile to add
`groupToJoin`	the group to join
`orgToJoin`	the organisation the membership sits within

`addToGroup(Profile profile, Group groupToJoin, Organisation orgToJoin)`

Returns: GroupMembership

Adds the profile to the group within the given organisation, writes a signup log and queues the profile for reindexing. When making several group changes to one profile it is cheaper to call addToGroupWithoutEvent for each and then updateUser once at the end.

Parameter	Description
`profile`	the profile to add
`groupToJoin`	the group to join
`orgToJoin`	the organisation the membership sits within

`allMemberships(long userId, Organisation organisation)`

Returns: MembershipList

Returns all of the user's memberships whose group belongs to the given organisation or one within it, which can include memberships outside the user's own home account. Falls back to the current account when the given organisation is not part of it.

Parameter	Description
`userId`	the internal id of the profile to read memberships for
`organisation`	the organisation to filter the memberships by, may be null

`newLoginNonceSearchBuilder()`

Returns: LoginNonceSearchBuilder

Creates a builder for searching login nonces, ie the record of remembered logins and login-as sessions. Set the criteria on the builder and then run the search from it.

To get full access to the Kademi Hub existing customers can login here, or new customers can register here.