Changes between Version 20 and Version 21 of SPIDocs


Ignore:
Timestamp:
Sep 22, 2014 5:20:00 PM (7 years ago)
Author:
faber
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • SPIDocs

    v20 v21  
    326326Users can become members of a project by requesting to join or or by being invited to join. Because joining a project adds a user to the project's circle, that changes the rights of a user, so either of these routes must be endorsed by both the user and someone with relevant permissions in the project.  The difference is only the order in which the endorsements are gathered.
    327327
    328 When a user finds a project the would like to join, usually through some out of band mechanism, they call the `joinProject` operation on the `Projects [wiki:SPIDocs#Services service].  This registers the user's intention to join and sends a [wiki:SPIDocs#Notifications notification] to members of the project who have the right to add users to the group.  This notification includes a challenge that is similar in format to the [wiki:SPIDocs#PasswordManagement requestPasswordChange] challenge.  As with that operation, an application can include a URL prefix that will be prepended to the challenge in the notification.
     328When a user finds a project the would like to join, usually through some out of band mechanism, they call the `joinProject` operation on the `Projects` [wiki:SPIDocs#Services service].  This registers the user's intention to join and sends a [wiki:SPIDocs#Notifications notification] to members of the project who have the right to add users to it.  This notification includes a challenge that is similar in format to the [wiki:SPIDocs#PasswordManagement requestPasswordChange] challenge.  As with that operation, an application can include a URL prefix that will be prepended to the challenge in the notification.
    329329
    330330One of the users receiving the notification can then call `joinProjectConfirm` with the challenge and a list of [wiki:SPIDocs#ProjectPermissions permissions] that the user will be assigned.  When that operation completes, the user is a member of the project with the associated rights.  The user calling `joinProjectConfirm` must have the `ADD_USER` right and similarly cannot confer more rights than they have.
     
    344344==== Changing Project Permissions ====
    345345
    346 A user that has both `ADD_USER` and `REMOVE_USER` permissions to a group can change the permissions granted to a user in the group.  The `changePermissions` operation in the `Projects` service is used to do this.  It takes a projectid, a list of users, and a new set of permissions.  It returns an array of results indicating the outcome of each requested change.
     346A user that has both `ADD_USER` and `REMOVE_USER` permissions to a project can change the permissions granted to a user in the project.  The `changePermissions` operation in the `Projects` service is used to do this.  It takes a projectid, a list of users, and a new set of permissions.  It returns an array of results indicating the outcome of each requested change.
    347347
    348348==== Project Profile Management ====
    349349
    350 The `Projects` [wiki:SPIDocs#Services service] supports the operations described in the [wiki:SPIDocs#Profiles profiles] description to allow applications to manipulate project profiles.
     350The `Projects` [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 project can change the contents of its profile.
    351351
    352352==== Administrative Operations ====
     
    394394|| REALIZE_EXPERIMENT ||Allocate resources to an experiment and carry it out so that it is accessible to the members of this circle ||
    395395|| REMOVE_USER || Remove a user from the project.  Any objects they have created in the project's namespace remain ||
     396
     397The `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
     404A 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
     410Unlike 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
     415As 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
     417When 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
     419One 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
     421When 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
     423A 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
     427When 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
     429The 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
     433A 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
     437The `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
     441There are a few more operations that are restricted to administrators.
     442
     443There are [wiki:SPIDocs#Profiles profile] operations to add, remove and change attributes to the circle profile schema.
     444
     445There is an operation, `addUsersNoConfirm` to add users to a circle without requiring the users being added to confirm the change.
     446
     447These are documented below.