| | 396 | |
| | 397 | The `REALIZE_EXPERIMENT` permission means that a user can carry out an experiment under this circle. This means members of the circle will: |
| | 398 | |
| | 399 | * have access to the running experiment - e.g., accounts on computers, permissions to connect to orchestration software, etc. |
| | 400 | * have access to data collected from the experiment |
| | 401 | |
| | 402 | ==== Creating A Circle ==== |
| | 403 | |
| | 404 | A user creates a circle using the `createCircle` operation on the `Circless` [wiki:SPIDocs#Services service]. Mechanically, the procedure to create a project is very similar to [wiki:SPIDocs#CreatingNewUsers creating a user] or [wiki:SPIDocs#CreatingAProject project]. An application will: |
| | 405 | |
| | 406 | * User the `getProfileDescription` operation on the `Circles` service to get an empty circle profile |
| | 407 | * Gather data from the user to fill in the project description, including non-optional fields and proper formatting |
| | 408 | * Call the `createCircle` with a project name from the user and that user as the project's owner. (Administrators can create projects owned by other users). |
| | 409 | |
| | 410 | Unlike when a user creates a project, when `createCircle` completes successfully, the circle is ready for use. |
| | 411 | |
| | 412 | |
| | 413 | ==== Adding Users To A Circle ==== |
| | 414 | |
| | 415 | As with projects, users can become members of a circle by requesting to join or or by being invited to join. Because joining a circle changes the rights of a user, either of these routes must be endorsed by both the user and someone with relevant permissions in the circle. The difference is only the order in which the endorsements are gathered. |
| | 416 | |
| | 417 | When a user finds a circle the would like to join, usually through some out of band mechanism, they call the `joinCircle` operation on the `Circles` [wiki:SPIDocs#Services service]. This registers the user's intention to join and sends a [wiki:SPIDocs#Notifications notification] to members of the circle who have the right to add users to it. This notification includes a challenge that is similar in format to the [wiki:SPIDocs#ADdingUsersToAProject addUsers] challenge for projects. As with that operation, an application can include a URL prefix that will be prepended to the challenge in the notification. |
| | 418 | |
| | 419 | One of the users receiving the notification can then call `joinCircleConfirm` with the challenge and a list of [wiki:SPIDocs#CirclePermissions permissions] that the user will be assigned. When that operation completes, the user is a member of the circle with the associated permissions. The user calling `joinCircleConfirm` must have the `ADD_USER` right and similarly cannot confer more rights than they have. |
| | 420 | |
| | 421 | When a user with the `ADD_USER` permission wants to invite another user to join the project, the inviting user calls the `addUsers` operation with the circleid, a list of users, proposed permissions, and an a URL prefix that serves the same purpose as the prefix on `joinCircle`. When the operation succeeds, each invited user receives a [wiki:SPIDocs#Notifications notification] containing a challenge (and descriptive text about the circle). If the invited user does wish to join, they call the `addUserConfirm` operation with the challenge. When that operation succeeds, they are a member of the circle. |
| | 422 | |
| | 423 | A user with the `REMOVE_USER` permission can unilaterally remove other users from the circle by calling the `removeUsers` operation. The owner of a circle cannot be so removed. |
| | 424 | |
| | 425 | ==== Circle Ownership ==== |
| | 426 | |
| | 427 | When a circle is created, an owner for that circle is designated. It is generally the user who successfully called `createCircle`, though ownership may be designated for projects created by administrators. Ownership primarily means that the owner cannot be removed from the circle and controls the [wiki:SPIDocs#CircleProfileManagement profile contents]. |
| | 428 | |
| | 429 | The owner (and administrators) can change the owner of a circle by calling the `setOwner` operation in the `Circles` service. |
| | 430 | |
| | 431 | ==== Changing Circle Permissions ==== |
| | 432 | |
| | 433 | A user that has both `ADD_USER` and `REMOVE_USER` permissions to a circle can change the permissions granted to a user in the circle. The `changePermissions` operation in the `Circles` service is used to do this. It takes a circleid, a list of users, and a new set of permissions. It returns an array of results indicating the outcome of each requested change. |
| | 434 | |
| | 435 | ==== Project Profile Management ==== |
| | 436 | |
| | 437 | The `Circles` [wiki:SPIDocs#Services service] supports the operations described in the [wiki:SPIDocs#Profiles profiles] description to allow applications to manipulate project profiles. Only the owner of a circle can change the contents of its profile. |
| | 438 | |
| | 439 | ==== Administrative Operations ==== |
| | 440 | |
| | 441 | There are a few more operations that are restricted to administrators. |
| | 442 | |
| | 443 | There are [wiki:SPIDocs#Profiles profile] operations to add, remove and change attributes to the circle profile schema. |
| | 444 | |
| | 445 | There is an operation, `addUsersNoConfirm` to add users to a circle without requiring the users being added to confirm the change. |
| | 446 | |
| | 447 | These are documented below. |
