Skip to content

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
        }}