LP#1673857: stamp schema update
[working/Evergreen.git] / docs / admin_initial_setup / describing_your_people.adoc
1 Describing your people
2 ======================
3
4 Many different members of your staff will use your Evergreen system to perform
5 the wide variety of tasks required of the library.
6
7 When the Evergreen installation was completed, a number of permission groups
8 should have been automatically created. These permission groups are:
9
10 * Users
11 * Patrons
12 * Staff
13 * Catalogers
14 * Circulators
15 * Acquisitions
16 * Acquisitions Administrator
17 * Cataloging Administrator
18 * Circulation Administrator
19 * Local Administrator
20 * Serials
21 * System Administrator
22 * Global Administrator
23 * Data Review
24 * Volunteers
25
26 Each of these permission groups has a different set of permissions connected to
27 them that allow them to do different things with the Evergreen system. Some of
28 the permissions are the same between groups; some are different. These
29 permissions are typically tied to one or more working location (sometimes
30 referred to as a working organizational unit or work OU) which affects where a
31 particular user can exercise the permissions they have been granted.
32
33 Setting the staff user's working location
34 -----------------------------------------
35 To grant a working location to a staff user in the staff client:
36
37 . Search for the patron. Select *Search > Search for Patrons* from the top menu.
38 . When you retrieve the correct patron record, select *Other > User Permission
39   Editor* from the upper right corner. The permissions associated with this
40   account appear in the right side of the client, with the *Working Location*
41   list at the top of the screen.
42 . The *Working Location* list displays the Organizational Units in your
43   consortium. Select the check box for each Organization Unit where this user
44   needs working permissions. Clear any other check boxes for Organization Units
45   where the user no longer requires working permissions.
46 . Scroll all the way to the bottom of the page and click *Save*. This user
47   account is now ready to be used at your library.
48
49 As you scroll down the page you will come to the *Permissions* list. These are
50 the permissions that are given through the *Permission Group* that you assigned
51 to this user. Depending on your own permissions, you may also have the ability
52 to grant individual permissions directly to this user.
53
54 Comparing approaches for managing permissions
55 ---------------------------------------------
56 The Evergreen community uses two different approaches to deal with managing
57 permissions for users:
58
59 * *Staff Client*
60 +
61 Evergreen libraries that are most comfortable using the staff client tend to
62 manage permissions by creating different profiles for each type of user. When
63 you create a new user, the profile you assign to the user determines their
64 basic set of permissions. This approach requires many permission groups that
65 contain overlapping sets of permissions: for example, you might need to create
66 a _Student Circulator_ group and a _Student Cataloger_ group. Then if a new
67 employee needs to perform both of these roles, you need to create a third
68 _Student Cataloger / Circulator_ group representing the set of all of the
69 permissions of the first two groups.
70 +
71 The advantage to this approach is that you can maintain the permissions
72 entirely within the staff client; a drawback to this approach is that it can be
73 challenging to remember to add a new permission to all of the groups. Another
74 drawback of this approach is that the user profile is also used to determine
75 circulation and hold rules, so the complexity of your circulation and hold
76 rules might increase significantly.
77 +
78 * *Database Access*
79 +
80 Evergreen libraries that are comfortable manipulating the database directly
81 tend to manage permissions by creating permission groups that reflect discrete
82 roles within a library. At the database level, you can make a user belong to
83 many different permission groups, and that can simplify your permission
84 management efforts. For example, if you create a _Student Circulator_ group and
85 a _Student Cataloger_ group, and a new employee needs to perform both of these
86 roles, you can simply assign them to both of the groups; you do not need to
87 create an entirely new permission group in this case. An advantage of this
88 approach is that the user profile can represent only the user's borrowing
89 category and requires only the basic _Patrons_ permissions, which can simplify
90 your circulation and hold rules.
91
92 Permissions and profiles are not carved in stone. As the system administrator,
93 you can change them as needed. You may set and alter the permissions for each
94 permission group in line with what your library, or possibly your consortium,
95 defines as the appropriate needs for each function in the library.
96
97 Managing permissions in the staff client
98 ----------------------------------------
99 In this section, we'll show you in the staff client:
100
101 * where to find the available permissions
102 * where to find the existing permission groups
103 * how to see the permissions associated with each group
104 * how to add or remove permissions from a group
105
106 We also provide an appendix with a listing of suggested minimum permissions for
107 some essential groups. You can compare the existing permissions with these
108 suggested permissions and, if any are missing, you will know how to add them.
109
110 Where to find existing permissions and what they mean
111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112 In the staff client, in the upper right corner of the screen, click on
113 *Administration > Server Administration > Permissions*.
114
115 The list of available permissions will appear on screen and you can scroll down
116 through them to see permissions that are already available in your default
117 installation of Evergreen.
118
119 There are over 500 permissions in the permission list. They appear in two
120 columns: *Code* and *Description*. Code is the name of the permission as it
121 appear in the Evergreen database. Description is a brief note on what the
122 permission allows. All of the most common permissions have easily
123 understandable descriptions.
124
125 Where to find existing Permission Groups
126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
127 In the staff client, in the upper right corner of the screen, navigate to
128 *Administration > Server Administration > Permission Groups*.
129
130 Two panes will open on your screen. The left pane provides a tree view of
131 existing Permission Groups. The right pane contains two tabs: Group
132 Configuration and Group Permissions.
133
134 In the left pane, you will find a listing of the existing Permission Groups
135 which were installed by default. Click on the + sign next to any folder to
136 expand the tree and see the groups underneath it. You should see the Permission
137 Groups that were listed at the beginning of this chapter. If you do not and you
138 need them, you will have to create them.
139
140 Adding or removing permissions from a Permission Group
141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
142 First, we will remove a permission from the Staff group.
143
144 . From the list of Permission Groups, click on *Staff*.
145 . In the right pane, click on the *Group Permissions* tab. You will now see a
146   list of permissions that this group has.
147 . From the list, choose *CREATE_CONTAINER*. This will now be highlighted.
148 . Click the *Delete Selected* button. CREATE_CONTAINER will be deleted from the
149   list. The system will not ask for a confirmation. If you delete something by
150   accident, you will have to add it back.
151 . Click the *Save Changes* button.
152
153 You can select a group of individual items by holding down the _Ctrl_ key and
154 clicking on them. You can select a list of items by clicking on the first item,
155 holding down the _Shift_ key, and clicking on the last item in the list that
156 you want to select.
157
158 Now, we will add the permission we just removed back to the Staff group.
159
160 . From the list of Permission Groups, click on *Staff*.
161 . In the right pane, click on the *Group Permissions* tab.
162 . Click on the *New Mapping* button. The permission mapping dialog box will
163   appear.
164 . From the Permission drop down list, choose *CREATE_CONTAINER*.
165 . From the Depth drop down list, choose *Consortium*.
166 . Click the checkbox for *Grantable*.
167 . Click the *Add Mapping* button. The new permission will now appear in the
168   Group Permissions window.
169 . Click the *Save Changes* button.
170
171 If you have saved your changes and you don't see them, you may have to click
172 the Reload button in the upper left side of the staff client screen.
173
174 Managing role-based permission groups in the staff client
175 ---------------------------------------------------------
176
177 Main permission groups are granted in the staff client through Edit in the patron record using the Main (Profile) Permission Group field.  Additional permission
178 groups can be granted using secondary permission groups.
179
180 [[secondaryperms]]
181 Secondary Group Permissions
182 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
183
184 The _Secondary Groups_ button functionality enables supplemental permission
185 groups to be added to staff accounts. The *CREATE_USER_GROUP_LINK* and
186 *REMOVE_USER_GROUP_LINK* permissions are required to display and use this
187 feature.
188
189 In general when creating a secondary permission group do not grant the
190 permission to login to Evergreen.
191
192 Granting Secondary Permissions Groups
193 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
194
195
196 . Open the account of the user you wish to grant secondary permission group to.
197 . Click _Edit_.
198 . Click _Secondary Groups_, located to the right of the _Main (Profile) Permission Group_.
199 +
200 image::media/sup-permissions-1_web_client.png[Secondary Permissions Group]
201 +
202 . From the dropdown menu select one of the secondary permission groups.
203 +
204 image::media/sup-permissions-2_web_client.png[Secondary Permission Group List]
205 +
206 . Click _Add_.
207 . Click _Apply Changes_.
208 +
209 image::media/sup-permissions-3.png[Secondary Permission Group Save]
210 +
211 . Click _Save_ in the top right hand corner of the _Edit Screen_ to save the user's account.
212
213
214 Removing Secondary Group Permissions
215 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
216 . Open the account of the user you wish to remove the secondary permission group from.
217 . Click _Edit_.
218 . Click _Secondary Groups_, located to the right of the _Main (Profile) Permission Group_.
219 +
220 image::media/sup-permissions-1_web_client.png[Secondary Permissions Group]
221 +
222 . Click _Delete_ beside the permission group you would like to remove.
223 +
224 image::media/sup-permissions-4_web_client.png[Secondary Permissions Group Delete]
225 +
226 . Click _Apply Changes_.
227 +
228 image::media/sup-permissions-5_web_client.png[Secondary Permissions Group Save]
229 +
230 . Click _Save_ in the top right hand corner of the _Edit Screen_ to save the user's account.
231
232 Managing role-based permission groups in the database
233 -----------------------------------------------------
234 While the ability to assign a user to multiple permission groups has existed in
235 Evergreen for years, a staff client interface is not currently available to
236 facilitate the work of the Evergreen administrator. However, if you or members
237 of your team are comfortable working directly with the Evergreen database, you
238 can use this approach to separate the borrowing profile of your users from the
239 permissions that you grant to staff, while minimizing the amount of overlapping
240 permissions that you need to manage for a set of permission groups that would
241 otherwise multiply exponentially to represent all possible combinations of
242 staff roles.
243
244 In the following example, we create three new groups:
245
246 * a _Student_ group used to determine borrowing privileges
247 * a _Student Cataloger_ group representing a limited set of cataloging
248   permissions appropriate for students
249 * a _Student Circulator_ group representing a limited set of circulation
250   permissions appropriate for students
251
252 Then we add three new users to our system: one who needs to perform some
253 cataloging duties as a student; one who needs perform some circulation duties
254 as a student; and one who needs to perform both cataloging and circulation
255 duties. This section demonstrates how to add these permissions to the users at
256 the database level.
257
258 To create the Student group, add a new row to the _permission.grp_tree_ table
259 as a child of the _Patrons_ group:
260
261 [source,sql]
262 ------------------------------------------------------------------------------
263 INSERT INTO permission.grp_tree (name, parent, usergroup, description, application_perm)
264 SELECT 'Students', pgt.id, TRUE, 'Student borrowers', 'group_application.user.patron.student'
265 FROM permission.grp_tree pgt
266  WHERE name = 'Patrons';
267 ------------------------------------------------------------------------------
268
269 To create the Student Cataloger group, add a new row to the
270 _permission.grp_tree_ table as a child of the _Staff_ group:
271
272 [source,sql]
273 ------------------------------------------------------------------------------
274 INSERT INTO permission.grp_tree (name, parent, usergroup, description, application_perm)
275 SELECT 'Student Catalogers', pgt.id, TRUE, 'Student catalogers', 'group_application.user.staff.student_cataloger'
276 FROM permission.grp_tree pgt
277 WHERE name = 'Staff';
278 ------------------------------------------------------------------------------
279
280 To create the Student Circulator group, add a new row to the
281 _permission.grp_tree_ table as a child of the _Staff_ group:
282
283 [source,sql]
284 ------------------------------------------------------------------------------
285 INSERT INTO permission.grp_tree (name, parent, usergroup, description, application_perm)
286 SELECT 'Student Circulators', pgt.id, TRUE, 'Student circulators', 'group_application.user.staff.student_circulator'
287 FROM permission.grp_tree pgt
288 WHERE name = 'Staff';
289 ------------------------------------------------------------------------------
290
291 We want to give the Student Catalogers group the ability to work with MARC
292 records at the consortial level, so we assign the UPDATE_MARC, CREATE_MARC, and
293 IMPORT_MARC permissions at depth 0:
294
295 [source,sql]
296 ------------------------------------------------------------------------------
297 WITH pgt AS (
298   SELECT id
299   FROM permission.grp_tree
300   WHERE name = 'Student Catalogers'
301 )
302 INSERT INTO permission.grp_perm_map (grp, perm, depth)
303 SELECT pgt.id, ppl.id, 0
304 FROM permission.perm_list ppl, pgt
305 WHERE ppl.code IN ('UPDATE_MARC', 'CREATE_MARC', 'IMPORT_MARC');
306 ------------------------------------------------------------------------------
307
308 Similarly, we want to give the Student Circulators group the ability to check
309 out copies and record in-house uses at the system level, so we assign the
310 COPY_CHECKOUT and CREATE_IN_HOUSE_USE permissions at depth 1 (overriding the
311 same _Staff_ permissions that were granted only at depth 2):
312
313 [source,sql]
314 ------------------------------------------------------------------------------
315 WITH pgt AS (
316   SELECT id
317   FROM permission.grp_tree
318   WHERE name = 'Student Circulators'
319 ) INSERT INTO permission.grp_perm_map (grp, perm, depth)
320 SELECT pgt.id, ppl.id, 1
321 FROM permission.perm_list ppl, pgt
322 WHERE ppl.code IN ('COPY_CHECKOUT', 'CREATE_IN_HOUSE_USE');
323 ------------------------------------------------------------------------------
324
325 Finally, we want to add our students to the groups. The request may arrive in
326 your inbox from the library along the lines of "Please add Mint Julep as a
327 Student Cataloger, Bloody Caesar as a Student Circulator, and Grass Hopper as a
328 Student Cataloguer / Circulator; I've already created their accounts and given
329 them a work organizational unit." You can translate that into the following SQL
330 to add the users to the pertinent permission groups, adjusting for the
331 inevitable typos in the names of the users.
332
333 First, add our Student Cataloger:
334
335 [source,sql]
336 ------------------------------------------------------------------------------
337 WITH pgt AS (
338   SELECT id FROM permission.grp_tree
339   WHERE name = 'Student Catalogers'
340 )
341 INSERT INTO permission.usr_grp_map (usr, grp)
342 SELECT au.id, pgt.id
343 FROM actor.usr au, pgt
344 WHERE first_given_name = 'Mint' AND family_name = 'Julep';
345 ------------------------------------------------------------------------------
346
347 Next, add the Student Circulator:
348
349 [source,sql]
350 ------------------------------------------------------------------------------
351 WITH pgt AS (
352   SELECT id FROM permission.grp_tree
353   WHERE name = 'Student Circulators'
354 )
355 INSERT INTO permission.usr_grp_map (usr, grp)
356 SELECT au.id, pgt.id
357 FROM actor.usr au, pgt
358 WHERE first_given_name = 'Bloody' AND family_name = 'Caesar';
359 ------------------------------------------------------------------------------
360
361 Finally, add the all-powerful Student Cataloger / Student Circulator:
362
363 [source,sql]
364 ------------------------------------------------------------------------------
365  WITH pgt AS (
366   SELECT id FROM permission.grp_tree
367   WHERE name IN ('Student Catalogers', 'Student Circulators')
368 )
369 INSERT INTO permission.usr_grp_map (usr, grp)
370 SELECT au.id, pgt.id
371 FROM actor.usr au, pgt
372 WHERE first_given_name = 'Grass' AND family_name = 'Hopper';
373 ------------------------------------------------------------------------------
374
375 While adopting this role-based approach might seem labour-intensive when
376 applied to a handful of students in this example, over time it can help keep
377 the permission profiles of your system relatively simple in comparison to the
378 alternative approach of rapidly reproducing permission groups, overlapping
379 permissions, and permissions granted on a one-by-one basis to individual users.