User management

Overview

This section provides examples for the common scenerio of synchronizing users between two systems using the Administration GraphQL apis.

The platform has two top level entities: users and organizations (orgs). A user can belong to one or more orgs. The org only controls the user to the extent of the org.

Managing users

Steps for adding users to an org; all examples use the admin schema.

Find user

findUserBy(
    email: String, 
    externalId: String, 
    mobile: String, 
    name: String): [UserSearch!]!

Parameters

• email - this will be globally unique in the system
• externalId - this is an arbitrary value that can be set on a membership within an org; it is not guaranteed to be unique and since it can be any value it could return unexpected users.
• mobile - the users phone number, fully matched. At present the data is stored "as is" and false negatives are possible due to formatting differences.
• name - search by name; at least 3 characters must be supplied The maximum number of rows returned is 10

Example

query  {
  findUserBy(externalId: "someUniqueId") {
        id
        email
        name
        timezone
    }}

Create user

createUser(
    org: Uuid!,
    email: String!,
    first: String!,
    last: String!,
    mobile: String,
    name: String,
    groupId: Uuid,
    externalId: String): MutationResult!

This method will create the user, create their profile, add them to the specified org and optionally add them to the specified group.

Parameters

• org, email, first, last - required fields
• name - optional; this is the display name of the user, if left out it will be the first name + the last name
• groupId - optional; the user will be added to this group
• externalId - optional; see discussion above

mutation  { 
    createUser(
        email: "testuser@somedomain.com",
        first: "Test",
        last: "User",
        externalId: "some-unique-id",
        org: "..valid org id.."){
            id
            result
            records
            error
    }}

Add user to org

addOrgMember(
  org: Uuid!,
  orgId: Uuid,
  userId: Uuid!,
  role: String!,
  externalId: String): MutationResult!

Parameters

• org and userId - requiredFields
• role - optional; "user" or "admin"

mutation  { 
    addUserToOrg(
        userId: ".. valid user id..",
        org: "..valid org id.."){
        id
        result
        records
        error
    }}

Remove user from org OR

update user details

updateMember(
    org: Uuid!,
    userId: Uuid!,
    status: String!,
    role: String!,
    externalId: String): MutationResult!

To disable a user set the status to "retired".

Parameters

• org: org uuid
• userId: user uuid
• status: "active" | "retired"
• role: "user" | "admin"
• externalId: any value; this should be universally unique

mutation  { 
    updateMember(
        userId: ".. valid user id..",
        org: "..valid org id.."){
            id
            result
            records
            error
        }}

Add user to group

addGroupMembership(org: Uuid!, userId: Uuid!, groupId: Uuid!): MutationResult!

Parameters

• org: org uuid
• userId: user uuid
• groupId: group uuid

mutation  { 
    addGroupMembership(
        userId: ".. valid user id..",
        org: "..valid org id.."
        groupId: ".. valid group id.."){
            id
            result
            records
            error
        }}

Remove user from group

removeGroupMembership(
    org: Uuid!,
    userId: Uuid!,
    groupId: Uuid!): MutationResult!

Parameters

• org, userId, groupId - required

mutation  { 
    removeGroupMembership(
        userId: ".. valid user id..",
        org: "..valid org id.."
        groupId: ".. valid group id.."){
            id
            result
            records
            error
        }}

List users in a group

Returns the list of user, group id combinations. Note that if neither group nor user is provided the request returns a maximum of 500 entries.

groupUsers(org: Uuid!, groupId: Uuid, userId: Uuid): [GroupUser!]!

Parameters

• org - required
• userId - optional scope
• groupId - optional scope

query  {
    groupUsers(
        org:"..valid org id..",
        groupId: "..valid group id..") {
            userId
            groupId
            status
            userName
        }}