Group GraphQL Examples

These examples show how to query, create, and update groups through the GraphQL API, and how to use groups to grant, inherit, and revoke permissions on objects like programs and controls.

Query Groups

query GetGroups($first: Int, $where: GroupWhereInput) {
  groups(first: $first, where: $where) {
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
    edges {
      node {
        id
        name
        displayID
        description
        settings {
          visibility
          joinPolicy
        }
        members {
          edges {
            node {
              id
              user {
                id
                firstName
                lastName
                email
              }
              role
            }
          }
        }
      }
    }
  }
}

Creating Groups

Groups can be created in several ways:

• Basic Creation: Using the createGroup mutation.
• With Members: Using the createGroupWithMembers mutation, which allows specifying members at the time of creation.
• By Cloning: Using the createGroupByClone mutation, which allows creating a new group by cloning the permissions and/or members of an existing group.

Basic Group Creation Mutation

mutation CreateGroup($input: CreateGroupInput!) {
  createGroup(input: $input) {
    group {
      id
      name
      displayName
      owner {
        id
        displayName
      }
      setting {
        id
        joinPolicy
        syncToGithub
        syncToSlack
        visibility
      }
      permissions {
        id
        objectType
        permissions
      }
      members {
        id
        role
        user {
          id
          firstName
          lastName
        }
      }
    }
  }
}

Add Group Member

mutation CreateGroupMembership($input: CreateGroupMembershipInput!) {
  createGroupMembership(input: $input) {
    groupMembership {
      id
      role
      user {
        id
        firstName
        lastName
        email
      }
      group {
        id
        name
        displayID
      }
    }
  }
}

Updating Groups

Groups can be updated using the updateGroup mutation. This mutation allows modifying various attributes of the group, including its name, description, and settings. Additionally, it supports adding or removing members and inheriting permissions from another group.

Update Group Mutation

mutation UpdateGroup($id: ID!, $input: UpdateGroupInput!) {
  updateGroup(id: $id, input: $input) {
    group {
      id
      name
      displayName
      description
      setting {
        id
        joinPolicy
        syncToGithub
        syncToSlack
        visibility
      }
      permissions {
        id
        objectType
        permissions
      }
      members {
        id
        role
        user {
          id
          firstName
          lastName
        }
      }
    }
  }
}

Permissions Management

Use Case: Create a Program where the user can view the program only but edit controls

To set this up:

1. Create a program object and a control object
2. Add the member to the program with a role of member (viewer)
3. Assign the user to groups as an editor or owner of the control

Create a Program

mutation CreateProgram($input: CreateProgramInput!) {
  createProgram(input: $input) {
    program {
      id
      name
      description
      status
      framework
      owner {
        id
        displayName
      }
    }
  }
}

Create a Control

mutation CreateControl($input: CreateControlInput!) {
  createControl(input: $input) {
    control {
      id
      name
      description
      status
      owner {
        id
        displayName
      }
    }
  }
}

Assign Permissions

Add user as viewer of the program:

mutation AssignViewerToProgram {
  updateProgram(id: "program1-id", input: {
    viewers: ["group-id"]
  }) {
    program {
      id
      name
      viewers {
        id
        name
      }
    }
  }
}

Add user as editor of control:

mutation AssignEditorToControl {
  updateControl(id: "control1-id", input: {
    editors: ["group-id"]
  }) {
    control {
      id
      name
      editors {
        id
        name
      }
    }
  }
}

Permission Inheritance

1. Group Membership:
   • A user is added as a member of a group
   • The group has editor permissions of a program
2. Inherited Permissions:
   • The user inherits editor permissions for the program through their membership in the group.

Example

Create a group:

mutation CreateGroup {
  createGroup(input: {
    name: "Group1",
    description: "A sample group"
  }) {
    group {
      id
      name
    }
  }
}

Add user to group:

mutation AddUserToGroup {
  updateGroup(id: "group1-id", input: {
    members: ["user1-id"]
  }) {
    group {
      id
      name
      members {
        id
        name
      }
    }
  }
}

Assign group as editor of the program:

mutation AssignEditorToProgram {
  updateProgram(id: "program1-id", input: {
    editors: ["group1-id"]
  }) {
    program {
      id
      name
      editors {
        id
        name
      }
    }
  }
}

Permission Overlap

When a user is in multiple groups with different permissions for the same object, the most permissive set of permissions applies.

Example Scenario: User1 is a member of both groups.

Group	Permission on Program1
Group A	Editor
Group B	Viewer

The more permissive grant wins: User1 has editor access to Program1.

Example

Create groups:

mutation CreateGroups {
  createGroup(input: {
    name: "GroupA",
    description: "Group with editor permissions"
  }) {
    group {
      id
      name
    }
  }
  createGroup(input: {
    name: "GroupB",
    description: "Group with viewer permissions"
  }) {
    group {
      id
      name
    }
  }
}

Add user to groups:

mutation AddUserToGroups {
  updateGroup(id: "groupa-id", input: {
    members: ["user1-id"]
  }) {
    group {
      id
      name
      members {
        id
        name
      }
    }
  }
  updateGroup(id: "groupb-id", input: {
    members: ["user1-id"]
  }) {
    group {
      id
      name
      members {
        id
        name
      }
    }
  }
}

Assign permissions to groups:

mutation AssignPermissionsToGroups {
  updateProgram(id: "program1-id", input: {
    editors: ["groupa-id"],
    viewers: ["groupb-id"]
  }) {
    program {
      id
      name
      editors {
        id
        name
      }
      viewers {
        id
        name
      }
    }
  }
}

Revoking Permissions

To revoke specific permissions from a user or group, you can use GraphQL mutations to update the permissions of the relevant objects. This involves removing the user or group from the list of entities that have the specified permissions.

Examples

Remove user from the list of editors for a control:

mutation RemoveEditorFromControl {
  updateControl(id: "control1-id", input: {
    editors: []
  }) {
    control {
      id
      name
      editors {
        id
        name
      }
    }
  }
}

Remove group from the list of viewers for a program:

mutation RemoveViewerFromProgram {
  updateProgram(id: "program1-id", input: {
    viewers: []
  }) {
    program {
      id
      name
      viewers {
        id
        name
      }
    }
  }
}