Changes between Version 27 and Version 28 of SPIDocs


Ignore:
Timestamp:
Sep 30, 2014 11:04:15 AM (7 years ago)
Author:
faber
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • SPIDocs

    v27 v28  
    392392That scoping serves 2 purposes: disambiguating common names and providing a way to distinguish certain names.  We expect that many users will set up circles with local names like `test`, `students`, `assistants` and the like.  The user interfaces built on the SPI can scope such names by the userid creating them and hide the prefix unless it is necessary to disambiguate.
    393393
    394 When a user creates a name in scoped by a project name, it is functionally equivalent to a userid-scpoed name, but applications may choose to distinguish them.  One can easily imagine that `some_user:students` and `some_project:students` refer to different sets of users and that the project-prefixed circle is administered more carefully and used more widely.
     394When a user creates a name in scoped by a project name, it is functionally equivalent to a userid-scoped name, but applications may choose to distinguish them.  One can easily imagine that `some_user:students` and `some_project:students` refer to different sets of users and that the project-prefixed circle is administered more carefully and used more widely.
    395395The right to create a circle in a project's name space - prefixed by the projectid - is controlled by [wiki:SPIDocs#ProjectPermissions project permissions].
    396396
     
    415415 * Call the `getProfileDescription` operation on the `Circles` service to get an empty circle profile
    416416 * Gather data from the user to fill in the circle profile, including non-optional fields and proper formatting
    417  * 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).
     417 * Call the `createCircle` with the profile, a circle name from the user, and that user as the project's owner.  (Administrators can create projects owned by other users).
    418418
    419419Unlike when a user creates a project, when `createCircle` completes successfully, the circle is ready for use.
     
    474474We present a worked example of the [LayoutAspect layout aspect] that illustrates this.
    475475
    476 Experiments also have [wiki:SPIDocs#Profiles profiles] attached to them so that other users can understand the purpose and goals of a project without investigating the aspects in detail.
     476Experiments also have [wiki:SPIDocs#Profiles profiles] attached to them so that other users can understand the purpose and goals of an experiment without investigating the aspects in detail.
    477477
    478478==== Aspects ====
     
    559559==== Experiment Ownership ====
    560560
    561 When an experiment is created, an owner for that experiment is designated.  It is generally the user who successfully called `createExperiment`, though ownership may be designated for experiments created by administrators. An owner retains all permissions to manipulate the experiment regardless of ACLs and  controls the [wiki:SPIDocs#CircleProfileManagement profile contents].
     561When an experiment is created, an owner for that experiment is designated.  It is generally the user who successfully called `createExperiment`, though ownership may be designated for experiments created by administrators. An owner retains all permissions to manipulate the experiment regardless of ACLs and  controls the [wiki:SPIDocs#ExperimentProfileManagement profile contents].
    562562
    563563The owner (and administrators) can change the owner of a experiment by calling the `setOwner` operation in the `Experiments` service.
     
    565565==== Experiment Profile Management ====
    566566
    567 The `Experiment` [wiki:SPIDocs#Services service] supports the operations described in the [wiki:SPIDocs#Profiles profiles] description to allow applications to manipulate experiment profiles.  Only the owner of an experiment can change the contents of its profile.
     567The `Experiments` [wiki:SPIDocs#Services service] supports the operations described in the [wiki:SPIDocs#Profiles profiles] description to allow applications to manipulate experiment profiles.  Only the owner of an experiment can change the contents of its profile.
    568568
    569569==== Viewing Experiments ====
    570570
    571 A user can always view circles that they can read.  The `viewExperiments` operation on the `Experiments` [wiki:SPIDocs#Services service] returns descriptions of the various experiments.  Experiment descriptions contain more information than the descriptions of circles.  Specifically aspects and ACLs can be selected individually to be shown for each experiment returned.
     571A user can always view experiments that they can read.  The `viewExperiments` operation on the `Experiments` [wiki:SPIDocs#Services service] returns descriptions of the various experiments.  Experiment descriptions contain more information than the descriptions of circles.  Specifically aspects and ACLs can be selected individually to be shown for each experiment returned.
    572572
    573573The `viewExperiments` operation takes the following parameters:
     
    598598
    599599These are documented below.
     600
     601=== Libraries ===
     602
     603Libraries are groups of experiments used to collect related experiments.  For example, a testbed may have a library of experiments for new users to realize and study in learning to use the testbed.  A research group might collect a set of regression tests into a library.
     604
     605As with experiments, access to the library is controlled by circles.  A library if beginner experiments might be readable by the world circle while a specific research group would protect their libraries using project circles or smaller.
     606
     607Libraries also have [wiki:SPIDocs#Profiles profiles] attached to them so that other users can understand the purpose and goals of the library.
     608
     609
     610==== Library Names ====
     611
     612Every circle has a unique ''libraryid'' that names it in the testbed.  Library names are scoped by either userids or projectids.  A libraryid has the form of either:
     613
     614 * userid:local_name
     615 * projectid:local_name
     616
     617So there may be libraries named `some_user:experiments` and `some_project:experiments`.  They are distinct.
     618
     619That scoping serves 2 purposes: disambiguating common names and providing a way to distinguish certain names.  We expect that many users will set up libraries with local names like `test`, `development`, `paper_results` and the like.  The user interfaces built on the SPI can scope such names by the userid creating them and hide the prefix unless it is necessary to disambiguate.
     620
     621When a user creates a name in scoped by a project name, it is functionally equivalent to a userid-scoped name, but applications may choose to distinguish them.  One can easily imagine that `some_user:development` and `some_project:development` refer to different sets of experiments and that the project-prefixed library is administered more carefully and used more widely.
     622The right to create a library in a project's name space - prefixed by the projectid - is controlled by [wiki:SPIDocs#ProjectPermissions project permissions].
     623
     624==== Library Permissions ====
     625
     626As with other abstractions, access to libraries is controlled by permissions.  These permissions are assigned to circles rather than individual users.  Because each user is the sole member of an immutable circle named ''userid'':''userid'' permissions can be assigned per-user by assigning to that circle.  Similarly, assigning to the ''projectid'':''projectid'' circle assigns permissions to all members of a project.
     627
     628The permissions relevant to project are:
     629
     630||= Permission Name =||= Meaning ||
     631|| ADD_EXPERIMENT || Circle members can add experiments to a library ||
     632|| MODIFY_LIBRARY_ACCESS || Circle members can change the permissions of other circles ||
     633|| READ_LIBRARY || Circle members can read experiment names and information bout access control from the library ||
     634|| REMOVE_EXPERIMENT || Circle members can remove experiments from the library ||
     635
     636A library is little more than a list of experiments.  The rights to inspect, modify, or realize experiments in a library are completely controlled by the [wiki:SPIDocs#ExperimentPermissions permissions] that a user has to the experiment.  Libraries provide a way to let users know that experiments exist and are related, not to control the experiments.
     637
     638
     639==== Creating A Library ====
     640
     641A user creates a library using the `createLibrary` operation on the `Libraries` [wiki:SPIDocs#Services service].  Mechanically, the procedure to create a library is very similar to [wiki:SPIDocs#CreatingNewUsers creating a user] or [wiki:SPIDocs#CreatingAProject project].  An application will:
     642
     643 * Call the `getProfileDescription` operation on the `Libraries` service to get an empty library profile
     644 * Gather data from the user to fill in the library profile, including non-optional fields and proper formatting
     645 * Call the `createLibrary` with the profile, a libraryid name from the user, and that user as the library's owner.  (Administrators can create projects owned by other users).  Other parameters include an initial list of experimentids in the library and initial access control lists.
     646
     647When `createLibrary` completes successfully, the library is ready for use.
     648
     649
     650==== Adding Experiments To A Library and Removing Them ====
     651
     652The operations to add and remove experimentids from a library are pretty straightforward: `addLibraryExperiments` adds new ones and `removeLibraryExperiments` (both in the `Libraries` [wiki:SPIDocs#Services service]) do the obvious things.  Both take a list of experimentids and return a result for each addition or removal.  `addLibraryExperiments` requires the user to have the `ADD_EXPERIMENT` permission; `removeLibraryExperiments` requires `REMOVE_EXPERIMENT`.
     653
     654==== Adding and Changing Library Access Control Lists ====
     655
     656All library permissions are controlled by access control lists (ACL) that map circles to library permissions.  The only exception to this is the owner of the library who always has all permissions.  Any user who has `MODIFY_LIBRARY_ACCESS` permissions to an library can change its ACLs.
     657
     658A user can set the ACLs on `createLibrary` by providing a list of (circle, permissions) pairs, where permissions is itself a list of permissions.  Any errors in specifying the ACLs will cause the creation to fail.
     659
     660A user can call `changeLibraryACL` with a list in the same format.  New entries will be added, existing entries will be overwritten, and entries with an empty permission list will be removed.  A partial success is possible and the result of each change is returned.
     661
     662==== Library Ownership ====
     663
     664When an library is created, an owner for that library is designated.  It is generally the user who successfully called `createLibrary`, though ownership may be designated for libraries created by administrators. An owner retains all permissions to manipulate the library regardless of ACLs and  controls the [wiki:SPIDocs#LibraryProfileManagement profile contents].
     665
     666The owner (and administrators) can change the owner of a experiment by calling the `setOwner` operation in the `Libraries` service.
     667
     668==== Library Profile Management ====
     669
     670The `Libraries` [wiki:SPIDocs#Services service] supports the operations described in the [wiki:SPIDocs#Profiles profiles] description to allow applications to manipulate library profiles.  Only the owner of an library can change the contents of its profile.
     671
     672==== Viewing Libraries ====
     673
     674A user can always view libraries that they can read.  The `viewLibraries` operation on the `Libraries` [wiki:SPIDocs#Services service] returns descriptions of the various libraries.  Library descriptions contain experimentid lists and ACLs.
     675
     676The `viewLibraries` operation takes the following parameters:
     677
     678||= Parameter =||= Meaning =||
     679|| uid || Return libraries this user can read. Admins may successfully view libraries as another user, but most users can only specify their own userid here. ||
     680|| regex || Restrict returned libraries to those that have a libraryid that matches the given [http://en.wikipedia.org/wiki/Regular_expression regular expression] ||
     681|| offset || Begin returning library descriptions at this position of a global list of matching libraries, ordered by creation time.  This allows incremental retrieval of library lists ||
     682|| count || Return only this many library descriptions ||
     683
     684Each description contains the following information.
     685
     686||= Parameter =||= Meaning =||
     687|| library ID || The unique library identifier ||
     688|| owner || The userid of the owner ||
     689|| perms || The permissions that the uid can exert on the library.  This allows an application to report the permissions without calculating them from the circles in the ACL ||
     690|| ACL || The access control list as a list of (circle, (permissions,...) ) pairs.  Permissions is a list of permissions. ||
     691|| Experiments || The experimentids in the library ||
     692
     693
     694==== Administrative Operations ====
     695
     696There are a few more operations that are restricted to administrators.
     697
     698There are [wiki:SPIDocs#Profiles profile] operations to add, remove and change attributes to the circle profile schema.
     699
     700These are documented below.