forio Toggle navigation

Group API

Groups are collections of users.

The Group API provides create, read, and delete capabilities for groups in the Epicenter platform.

Typically working with the Group API is only needed for Authenticated projects, that is, projects with end users.

The Group API supports the following HTTP methods:

Background: Types of Groups

Groups are collections of users. In Epicenter, there are five different types of groups. When working with the Member API, the type of group is usually included in the URI (endpoint), for example, /member/local/myGroupId.

IMPORTANT: As an Epicenter author, you will probably only ever work directly with members of local groups when working on your project; you have write access only to local groups within your projects. The local group is a collection of end users.

For completeness, the other types of groups are:

  • account type groups are collections of users (team members) that belong to this team.
  • project type groups are collections of users (team members) that can collaborate on this project.
  • local type groups are collections of end users that can play with your project (model or simulation), for example, the students in a class or the participants at an event.
  • personal type groups are special, singleton collections of users: Each individual user of Epicenter belongs to a group whose type is personal and whose only member is that user.
  • There is one global type group, to which Epicenter system administrators belong.

POST: Creating a Group

Use the Group API POST method to create a new group.

Creating a local group

A local group is a collection of end users that can play with your project, for example, the students in a class or the participants at an event.

Method: POST

URI: /v2/group/local

Headers: Content-Type: application/json, Authorization: Bearer{access token}

Body: JSON object with the name, account, and project.

Return Status:

  • 201: Group successfully added

Return Body: The group record (JSON object).

Example:

curl -X POST 'https://api.forio.com/v2/group/local/' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"name": "mgmt-100-seminar", "account": "acme-simulations", "project": "supply-chain-game"}'

Example Response:

{
  "type": "local",
  "created": "2017-01-09T22:33:22.000Z",
  "lastModified": "2017-01-09T22:33:21.000Z",
  "startDate": "2017-01-09T22:42:31.426Z",
  "expirationDate": "2017-07-09T22:42:31.426Z",
  "id": "0000015984e07e3c637540c3aaf060e38195",
  "groupId": "0000015984e07e3c637540c3aaf060e38195",
  "name": "mgmt-100-seminar",
  "account": "acme-simulations",
  "project": "supply-chain-game",
  "userCount": 0
}

Notes:

  • In the header, the access token can be the user access token of a team member or the project access token for this project.
  • In the request body for creating local groups, the following fields are required:
    • name: The author-specified unique identifier for this group (called Group ID in the Epicenter user interface). Can contain lowercase letters, numbers, hyphens, and underscores only.
    • account: The Team ID.
    • project: The Project ID.

  • In the request body for creating local groups, the following fields are optional:

    • organization: The descriptive name of the organization for this group. (In the Epicenter user interface, this is called Organization Name.)
    • event: The descriptive name related to this group. (In the Epicenter user interface, this is called Event Name, and could be your class or training seminar, for example.)
    • startDate: When the group becomes valid, that is, when the end users are able to play with this project. Must be ISO 8601 format; time is optional (e.g. 2014-04-27, 2014-04-27T00:00:00.00Z, and 2014-04-27T00:00:00.000-08:00 are all acceptable).
    • expirationDate: When the group expires, that is, when the end users are no longer able to play with this project. Must be ISO 8601 format; time is optional (e.g. 2014-04-27, 2014-04-27T00:00:00.00Z, and 2014-04-27T00:00:00.000-08:00 are all acceptable).
    • maxUsers: The number of end users that can be part of this group at once.
    • runLimitDefault: The number of runs for each end user.

  • In the response body, the userCount is a read-only field displaying the number of members currently in this group. (Epicenter automatically updates this when members are added to or removed from the group.)

GET: Viewing Details about Groups

You can retrieve details about any group using the Group API GET method.

Retrieving Details about One Local Group

Method: GET

URI: /v2/group/local/{group id}

Headers: Authorization: Bearer{access token}

Return Status: 200 (successful response)

Return Body: The group record (JSON object)

Example:

curl -G \
    'https://api.forio.com/v2/group/local/0000015984e07e3c637540c3aaf060e38195' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9'

Example Response:

{
  "type": "local",
  "created": "2017-01-09T22:33:22.000Z",
  "lastModified": "2017-01-09T22:33:21.000Z",
  "startDate": "2017-01-09T22:42:31.426Z",
  "expirationDate": "2017-07-09T22:42:31.426Z",
  "id": "0000015984e07e3c637540c3aaf060e38195",
  "groupId": "0000015984e07e3c637540c3aaf060e38195",
  "name": "mgmt-100-seminar",
  "account": "acme-simulations",
  "project": "supply-chain-game",
  "userCount": 0
}

Notes:

  • In the header, the access token can be the user access token of a team member or the project access token for this project.
  • In the URI, the group id is the system-generated unique identifier for this group.
    • It is returned in the id field and the groupId field when you create a group.
    • You can find this identifier from the URL within the Epicenter user interface:
      • From your project home page (Dashboard > [Team Name] > [Project Name]), select Groups from the left.
      • Select a group name to see a list of end users in the group.
      • Check the URL for this page. It has the pattern: https://forio.com/epicenter/{team id}/{project id}/groups/{group id}.

Retrieving Details about Multiple Local Groups

Method: GET

URI: /v2/group/local/?{ampersand-separated query parameters}

Headers: Authorization: Bearer{access token}

Return Status: 200 (successful response)

Return Body: An array of group records (JSON objects).

Example:

curl -G \
    'https://api.forio.com/v2/group/local?account=acme-simulations&q=mgmt' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9'

Example Response:

[
    {
      "type": "local",
      "created": "2017-01-09T22:33:22.000Z",
      "lastModified": "2017-01-09T22:33:21.000Z",
      "startDate": "2017-01-09T22:42:31.426Z",
      "expirationDate": "2017-07-09T22:42:31.426Z",
      "id": "0000015984e07e3c637540c3aaf060e38195",
      "groupId": "0000015984e07e3c637540c3aaf060e38195",
      "name": "mgmt-100-seminar",
      "account": "acme-simulations",
      "project": "supply-chain-game",
      "userCount": 0
    },
    // other matching group records, if any
]

Notes:

  • In the header, the access token can be the user access token of a team member or the project access token for this project.
  • In the URI, you can query within local groups by:
    • account (Team ID)
    • or by account and project (Team ID and Project ID)
    • or by account and project and name (Team ID and Project ID and Group Name)
    • or by account and the query paramter q, asking for a partial match for name, organization, and event. For example, /v2/group/local?account=acme-simulations&q=mgmt.
  • In the URI, you can SORT the results in the array returned by including the query parameters sort and direction (ASC or DESC).
    • For example: /v2/group/local/?account=acme-simulations&q=mgmt&sort=name&direction=ASC.
    • Available sort fields are: userCount, lastModified, created, account, project, runLimitDefault, maxUsers, name, event, organization.

Paging: Retrieving Many Records at Once

When you use the GET method for an API, your request may return many records at once.

The default page size is 100 (for most APIs) or 1000 (for the Data API). You can limit the number of records returned by adding the Range header.

Method: GET

URI: Any Epicenter API call

Headers: Range: records {i}-{j}

Return Status:

  • 200: Successfully retrieved all records
  • 206: Successfully retrieved the partially complete response, for example if you request records 0-20 and there are 35 records
  • 416: No records are found in a given search range (e.g. Range: records 10-15 when there are only 8 records)

Response Headers:

Whether or not you add the Range header to your request, the response header contains:

Content-Range: records i-j/k

where

  • i is the index of the first record returned
  • j is the index of the last record returned
  • k is the total number of records in the result set, or * if that number is computationally infeasible (for example, because you are querying across multiple projects)

For example, Content-Range: records 0-9/57 or Content-Range: records 20-29/*.

Response Body: An array of records. The array includes only those records indicated in the Content-Range header.

Example:

curl -G \
    'https://api.forio.com/v2/EpicenterAPI' \
    --header 'Range: records i-j'

Notes:

  • If no records are returned, the response body is empty.

  • If you leave off the start index, this is considered an implied start index of 0 rather than an invalid range. The response header includes status code of 200 or 206 depending on the ending index.

  • This use of the Range header is part of the RFC 2616 (see details in Section 14.16 and 14.35).

PATCH: Partially Updating a Group

You can partially update an existing group record (that is, replace one or more fields) using the Group API PATCH method.

Updating a Local Group

Method: PATCH

URI: /v2/group/local/{group id}

Headers: Content-Type: application/json, Authorization: Bearer{access token}

Body: JSON object with name-value pairs of the fields to update and the values with which to update them. Fields available to change include:

  • organization: The descriptive name of the organization for this group. (In the Epicenter user interface, this is called Organization Name.)
  • event: The descriptive name related to this group. (In the Epicenter user interface, this is called Event Name, and could be your class or training seminar, for example.)
  • startDate: When the group becomes valid, that is, when the end users are able to play with this project. Must be ISO 8601 format; time is optional (e.g. 2014-04-27, 2014-04-27T00:00:00.00Z, and 2014-04-27T00:00:00.000-08:00 are all acceptable).
  • expirationDate: When the group expires, that is, when the end users are no longer able to play with this project. Must be ISO 8601 format; time is optional (e.g. 2014-04-27, 2014-04-27T00:00:00.00Z, and 2014-04-27T00:00:00.000-08:00 are all acceptable).
  • maxUsers: The number of end users that can be part of this group at once.
  • runLimitDefault: The number of runs for each end user.

Return Status:

  • 200: Successfully updated group

Return Body: A JSON object with the group record just updated.

Example:

curl -X PATCH 'https://api.forio.com/v2/group/local/0000015984e07e3c637540c3aaf060e3822c' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"maxUsers": 40}'

Example Response:

{
  "type": "local",
  "created": "2017-01-09T23:24:55.000Z",
  "lastModified": "2017-01-09T23:24:54.000Z",
  "startDate": "2017-01-09T00:00:00.000Z",
  "expirationDate": "2017-07-09T00:00:00.000Z",
  "id": "0000015984e07e3c637540c3aaf060e3822c",
  "groupId": "0000015984e07e3c637540c3aaf060e3822c",
  "name": "mgmt-300-seminar",
  "account": "acme-simulations",
  "project": "supply-chain-game",
  "userCount": 0,
  "maxUsers": 40
}

Notes:

DELETE: Removing a Group

You can remove a group using the Group API DELETE method.

Removing a Local Group

Method: DELETE

URI: /v2/group/local/{group id}

Headers: Authorization: Bearer{access token}

Body: none

Return Status:

  • 200: Group successfully deleted

Return Body: The group record (JSON object) just deleted.

Example:

curl -X DELETE 'https://api.forio.com/v2/group/local/0000015984e07e3c637540c3aaf060e38232' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

{
  "type": "local",
  "created": "2017-01-09T23:27:38.000Z",
  "lastModified": "2017-01-09T23:27:37.000Z",
  "startDate": "2017-01-09T23:28:15.702Z",
  "expirationDate": "2017-07-09T23:28:15.702Z",
  "id": "0000015984e07e3c637540c3aaf060e38232",
  "groupId": "0000015984e07e3c637540c3aaf060e38232",
  "name": "mgmt-400-seminar",
  "account": "acme-simulations",
  "project": "supply-chain-game",
  "userCount": 0
}

Notes:

  • In the URI, the group id is the system-generated unique identifier for this group.
    • It is returned in the id field when you create a group.
    • You can find the group id from the URL within the Epicenter user interface:
      • From your project home page (Dashboard > [Team Name] > [Project Name]), select Groups from the left.
      • Select a group name to see a list of end users in the group.
      • Check the URL for this page. It has the pattern: https://forio.com/epicenter/{team id}/{project id}/groups/{group id}.
  • In the header, the access token can be the user access token of a team member or the project access token for this project.
  • Deleting an account also automatically deletes any groups under that account.