Group

Groups Group

Methods Supported:

• GET – read a list of all Groups

• POST – create a new root Group

• DELETE – remove a Group

Filters supported:

• ID – primary key

• Name – filtering by group name

• RootGroupID – filtering by the top-level group (expected in 2018.02)

Expansions supported:

• Administrators – the administrators responsible for the group

• Participants – the participant members of the group

• SubGroups – the optional list of sub-groups

• ParentGroup – the optional parent group (see warning)

• PrintBatches – the optional list of associated PrintBatches

The Groups feed contains data about groups of participants. Entries are defined by the Group type.

You can create a Group hierarchy in a single call by including SubGroups in a POST call:

POST <service root>/Groups
Content-Type: application/json

{
    "Name": "G1",
    "Description": "The Root Group",
    "SubGroups": [
        {
            "Name": "G1.1",
            "Description": "G1.1 child of G1",
            "SubGroups": [
                {
                    "Name": "G1.1.1",
                    "Description": "G1.1.1 child of G1.1"
                },
                {
                    "Name": "G1.1.2",
                    "Description": "G1.1.2 child of G1.1"
                }
            ]
        },
        {
            "Name": "G1.2",
            "Description": "G1.2 child of G1",
            "SubGroups": [
                {
                    "Name": "G1.2.1",
                    "Description": "G1.2.1 child of G1.2"
                },
                {
                    "Name": "G1.2.2",
                    "Description": "G1.2.2 child of G1.2"
                }
            ]
        },
        {
            "Name": "G1.3",
            "Description": "G1.3 child of G1"
        }
    ]
}

EntityType: Group

Entity Key: ID Edm.Int32 NOT NULL

The numeric ID of the Group.

Name Edm.String

The name of the Group.

Description Edm.String

The optional description of the Group.

RootGroupID Edm.Int32 NOT NULL

New in version 2017.11.

The numeric ID of the Group’s top-level parent. The group hierarchy does not have a single root node but instead supports multiple root groups that may have sub-groups (see SubGroups). For any group you can obtain the ID of the top-level group that contains this one using the RootGroupID. For root groups themselves this value will be the same as ID.

DefaultTestCenterId Edm.Int32

New in version 2021.09.

The ID of the default TestCenter (see below navigation property).

Participants Participant Collection

Navigation property to the participants that are in the group.

Administrators Administrator Collection

Navigation property to the administrators associated with the group (sometime referred as group owners though role-based permissions are out of scope for this API)

SubGroups Group Collection

Navigation property to the sub-groups of each group. Can also be used to create individual SubGroups using the POST method:

POST <service root>/Groups(<id>)/SubGroups
Content-Type: application/json

{
    "Name": "G1.4",
    "Description": "G1.4 child of G1",
}

Note that there is no $links function for linking existing Groups as the hierarchy is determined at the time a Group is created and Groups cannot be moved within the existing hierarchy.

ParentGroup Group

For sub-groups, the optional parent group.

Warning

due to a known issue in the implementation of this property it must only be expanded when the Group being queried is known to be a sub-group. Do not use it in general collections:

<service root>/Groups?$expand=ParentGroup

AncestorGroups Group Collection

New in version 2018.05.

Navigation property to all ancestors of this group including the group itself. A group is in the collection of ancestors if it is the group itself or if it is a parent of a member of the collection. This recursive definition ensures that all groups up to the root group are in the collection.

DescendantGroups Group Collection

New in version 2018.05.

Navigation property to all descendants of this group including the group itself. A group is in the collection of descendents if it is the group itself or if it is a subgroup of a member of the collection. This recursive definition ensures that all subgroups possible by repeated expansion are included in a single filterable collection.

SchedulableAssessments Assessment Collection

New in version 2017.11.

All the assessments that have had scheduling permissions associated with this Group. See Assessment.Groups for more information.

PrintBatches PrintBatch Collection

Navigation property to any PrintBatches associated with this Group.

DefaultTestCenter TestCenter

New in version 2021.09.

Navigation property to the default TestCenter for the group (optional).