OpenCoral Fab Administration Guide
This section of the guide includes a number of items that may be of interest to staff members who will use Coral on a daily basis. In particular, it will introduce and discuss many of the issued that are related to setting up members, projects, and accounts in Coral. It will also discuss a number of the elements related to assigning special roles and privileges to those members.
Understanding the Resource Manager and Resource Client
It is important that lab managers and lab accounting and administration personnel understand the Coral elements that are under the control of the resource client and the resoure manager. Those elements include:
- Members: Members are the people affiliated with each facility. They will include all of the people that use and work in your laboratory. To be a valid member (that is, someone that can start and run Coral), they must be an "active" member and be allowed to work on at least one active project (which, in turn, must be able to charge to at least one active account. Member names must be unique. Members may also be assigned "roles" that will grant then additional priivileges in Coral. Roles may be equipment-specific roles such as "user", "instructor", or "engineer" that will grant them different privileges on a specific tool. Roles may also be lab-wide such as "staff" or "admin" that will grant them extra privileges in an entire laboratory. In general, most members will only be allowed to work on one project at a time.
- Projects: Projects are most easily thought of as an alias for an account name. In most universities, account names (or numbers) are long, alphanumeric strings that have all of the decipherability of a car's VIN number. Just as most of us wouldn't recognize 1XVG38503AC1437 as the 2011 Blue Toyota Camry that belongs to John Smith, most of us would have a hard time "decoding" different univeristy account numbers into something meaningful. Project names must also be unique. In particular, there can only be one project named "NSF Project" for an entire Coral instance, but there could be "(smith) NSF Project", "(jones) NSF Project", and "(jones) DARPA Project" where smith and jones might be the names of the PI, for example. To be fully valid, a project must be allowed to charge to at least one active account. IN general, it is our believe that a project should only be able to charge to one account at a time. Also, to avoid confusion, most accounts should only have one project that is allowd to charge to that account. A reasonable exception to this last rule may be a situation where your staff members may be assigned to work on multiple projects named "Calibration", "Preventive Maintenance" and "Unscheduled Breakdown" that all charge to a single account number.
- Accounts: Accounts will typically be the alphanumeric string that represents an account number in your university accounting system. Typically charges for laboratory usage will be calculated on a cost recovery algorithm and applicable rates. This will generate a monthly set of charges which can be used to generate a report. This report should be able to be entered or uploaded into the main university accounting system to charge appropriate accounts for a lab member's usage of the facility.
- Roles: Roles may be assigned to lab members to control the privileges that they have if a particular Coral instance. A member's roles (coupled with the policies that make use of those roles) may be used to limit privileges of some users relative to others or, alternatively, to grant extra privileges to lab members holding those roles. Coral comes with a default set of roles that are believed to represent a reasonably starting point for many laboratories. Those policies, however, may be customized to meet more site-specific requirements. Typically, lab-wide roles such as "staff" or "admin" can and should be granted in the Resource Client. Equipment-specific roles such as "user", "instructor", or "engineer" should be granted in the equipment client.
- Services> Services are a specialized object that are likely only used in a small number of Coral instances. They are typically "things" for which a monthly uage fee should be generated. A "subscription" is used to indicate that a particular lab member (and associated project and account) will be charged for that service on a monthly basis for as long as that subscription is active. For exmaple, some laboratories change a monthly fee for an access card. In this case, creating a service named "Access Card" and then each member to that service would be one way of both charging each member for that access as long as their subscription remained active. Other labs have used a service named "Clean Room Rental" as a means of charging someone to host a private piece of equipment in their shared laboratory. For example, if a facility wished to charge someone based on the square footage of space that a machine used, they might set a rate of $10 per square foot per month. If someone wished to install a piece of equipment that covered 10 ft x 5 ft of clean room, then they could be subscribe to 50 "units" of "Clean Room Rental". At that rate, a monthly charge of $500 would be generated for as long as that subscription was active.
There is a reasonably flexible and, as a result, reasonably complex set of relationships that must be satisfied for a member to successfully run Coral and use resources in a laboratory. There are five conditions that must be satisfied in order for someone to be considered a valid member in Coral. Those conditiions are:
- The member must be active. That is, the "Active" box in the Member Information Panel of the resource client should be checked.
- The member must be currently allowed to work on at least one project. That is, the "Projects for Member X" panel should have at least one currently active project. Moreover, the default project (the "Project" field in the Member Information Panel) needs to be active in the "Projects for Member X" panel.
- The project itself needs to be active. That is, the "Active" box in the Project Information Panel should be checked.
- The project must currently be allowed to charge to at least one account. That is, the "Accounts for Project Y" panel should have at least one currently active account. Moreover, the default account (the "Account" field in the Project Information Panel) needs to be active in the "Accounts for Project Y" panel.
- The account itself needs to be active. That is, the "Active" box in the Account Information Panel should be checked.
In summary, there are three things (member, project, and account) that each need to be active. There are also two relationships that specify which member is allowed to work on which project and, similarly, which project is alloed to charge to each account that must also need to be active. Making any one of these things or relationships inactive will prevent someone from successfully starting Coral, but each will have a different impact on others. Let us review that from a "bottom up" perspective:
- Making an account inactive will prevent all projects that are currently allowe to charge to that account from actually using that account. This, in turn, will prvent all lab members who currently work on projects that charge to that acocunt from using that particular account. Typically, when a research contract expires, making the account "inactive" is the best way to insure that it will not be used beyond it's expiration date. Note: there is a Coral configuration parameter that specifies whether inactivation of an account will also inactivate all of the "charges to" relationships that allow different projects to charge to that particular account. In general, selecting the "Allow in-activate cascade up?" option on the General confiugration panel helps to keep the relationship tables a bit cleaner and more consistent. If Account A is inactive, then it probably has no valid purpose to still allow Project P to charge to Account A.
- Removing an account from the "Accounts for Project Y" prevents project Y from charging to account, but it does not prevent any other projects that may also be charging to that account from continuing to do so and it does not make the acoount itself inactive. This is probably the thing to do if there may be other projects that will continue to a particular account. There is an alternative means of doing this using the "Projects for Account Z" panel.
- Making a project inactive will prevent all members that are currently allowed to work on that project from actually using that project. If the "Allow in-activate cascade up?" option is selected, inactivating a project will also inactivate the appropriate works on relationships that allow various members to work on that particular projects.
- Removing a project from the "Projects for Member X" panel (or, conversely, removing a member from the "Members for Project P" panel) removes the ability for a member to continue to work on a particular project, but does not prevent other members from continuing to work on that project.
- Finally, a member may be inactivated.
When adding new members, projects, and accounts to Coral, it seems most natural to add the members first, then the projects, and finally the accounts. While this may seem most natural, it will not work. Why? When creating a new member, you will be prompted for the defualt project for that member. If that project does not exist, you will get an error. Similarly, when you add a project, you will be prompted for the default account for that project. If that account does not exist, you will get an error. As a result, it is always safest to add members, projects, and acocunts in a "bottom up" fashion: First add an account. Next, add a project that will charge to that newly added account as it's default account. Finally, add a member that will work on that newly added project. Of course, if the default account to which a project will charge already exists, it does not need to be added first. Similarly, if the default project on which a new member will work already exists it does not need to be added first.