User Related Queries

The following queries are SAMPLES. As a consumer of the Scope GraphQL API, you can design and use any properly formed query to retrieve the data that you require.

For more information, see “Introduction to the Scope GraphQL API“.

Here are common use-cases for various User operations like creating, finding, updating or deleting a user.

Creating a User

The mutation query below can be used to create a new user. For reference, you can look at the CreateUserMutation schema.

Arguments

There are some argument considerations

requestedOriginGroup - The origin group to request. Must be a valid group name UPPERCASED.
requestedLicenses - The licenses to request. Must be an array of LicenseType.ENUM values.
requestedGroups - The groups to request. Must be an array of UPPERCASE strings, ie. [DEFAULT, GROUP1, GROUP2]

To receive error messages when creating a user, make sure to add the errors in the return object as seen below in the query example.

Example

mutation {
  createUser(
    input: {
      user: {
        firstName: "Luke",
        lastName: "Skywalker",
        credentials: {
          username: "luke_skywalker",
          password: "womprats!1977"
        },
        email: "luke.skywalker@jedi.org"
        },
      requestedOriginGroup: "DEFAULT"
      requestedLicenses: [VIEWER],
      requestedGroups: ["DEFAULT", "JEDI"]
      ) {
    errors {
      path
      message
      fullMessage
    }
    user {
      id
      username
      email
    }
  }
}

Finding Users By Email Addresses

This query can be used to find a user(s) based on their email address. Multiple users can be returned if the email address is similar. Additional input arguments can be included to make selection more specific.

Example 1:

This query “digs” through the viewer’s current organization and returns the members.

Variables

{
  "first": 1,
  "fullText": "luke@jedi.org"
}

Query

query FetchMembers($fullText: String, $first: Int!) {
  viewer {
    currentOrganization {
      members(fullText: $fullText, first: $first)
        {
        nodes {
          firstName
          lastName
          username
          email
        }
      }              
    }
  }
}

Example 2:

This query uses the users query field, which is available on v2.28.1 and above.

Query

{
  users(
      fullText: "luke@jedi.org"
      first: 1
  )
   {
    errors {
      fullMessage
    }
    nodes {
      id
      firstName
      lastName
      username
      email
    }
    totalCount
  }
}

Updating a User

When updating a user, the ID retrieved earlier is required. The groups, and origin group use the group name. The licenses need a value from the LicenseTypeEnum.

Variables

{
  "input": {
    "id": <STRING>,
    "requestedGroups": Array<STRING>,
    "requestedLicenses": Array<STRING>,
    "requestedOriginGroup": <STRING>,
    "user": {
      "email": <STRING>,
      "firstName": <STRING>,
      "lastName": <STRING>,
      "phone": <STRING>,
      "jobTitle": <STRING>
    }
  }
}

Query

mutation updateUser($input: UpdateUserMutationInput!) {
  updateUser(input: $input) {
    user {
      id
      email
      firstName
      lastName
      phone
      jobTitle
      licenses {
        nodes {
          licenseType
        }
      }
      groups {
        nodes {
          name
        }
      }
    }
    errors {
      fullMessage
    }
    success
  }
}

Deleting Users

Multiple users can be removed at the same time by using the ids provided by the User queries. There are some exceptions and considerations to this operation:

A user cannot remove themselves
Invalid IDs will be skipped and valid IDs will be used to delete users. Errors of these invalid IDs will be returned.
It does not delete the last company admin. A single company admin must remain in the system.
It does not delete Scope/Support admin users. This will allow the support team to assist.

Variables

{"input": {"ids": Array<String> } }

Query

 mutation deleteUsers($input: DeleteUsersMutationInput!) {
  deleteUsers(input: $input) {
    errors {
      fullMessage
    }
    success
    undeletedItems {
      id
      name
    }
  }
}