iris-for-allocation-managers.md 14.7 KB
Newer Older
wyang's avatar
wyang committed
1 2 3 4 5 6 7 8 9 10 11 12 13
# ERCAP and Iris Guide for Allocation Managers

## ERCAP Reviewing, Approving, and Awarding

### Accessing the ERCAP Requests

When a PI submits an ERCAP request to NERSC, the NERSC Allocations
group will first review it for completeness. Once we have vetted
the request, we will assign it to DOE for Review. The DOE Allocation
managers will be notified via email that they have an ERCAP request
to be reviewed. The email will look similar to this:

![DOE Review Notification email](images/DEV-DOE-Review-Notification-email.png)
14
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
15 16 17

The email will contain the ERCAP Request number, the title of the
project, the name of the PI and their organization, and the status
18
of the request which will be 'Submitted for DOE Review.' There will
wyang's avatar
wyang committed
19 20 21 22 23
also be a link in the email that will take you to the NERSC
Helpdesk/ERCAP system to review the request. When you click on the
link (see above), you will be taken to a page that looks like this:

![DOE Approval link view](images/DEV-DOE-Approval-link-view.png)
24
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
25 26 27 28 29

You can log directly into the ERCAP system with the URL:
https://ercap.nersc.gov where you will be asked for your NERSC
username and password.

30
![ERCAP SHIB login screen](images/nersclogin.png){: height="288"}
wyang's avatar
wyang committed
31
{: align="center"}
wyang's avatar
wyang committed
32 33 34

You can find all of the requests assigned to you waiting to be
reviewed by clicking on the link in the left menu column titled
35
'ERCAP Requests for Review.'
wyang's avatar
wyang committed
36 37

![DOE ERCAP Requests for Review](images/DEV-DOE-ERCAP-Requests-for-Review.png)
38
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
39 40 41

Click on the ERCAP Number to take you into the request to review,
print, etc. You can also filter this list by right-clicking in the
42
white-space next to a text in a column and select 'Show Matching'
wyang's avatar
wyang committed
43 44 45 46 47 48
to find only the certain requests (such as Show all the requests
for a particular PI)

![Filtering on PI name](images/Filtering-on-PI-name.png)
{: align="center"}

49
or 'Filter Out' to remove all the requests that match the criteria
wyang's avatar
wyang committed
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
(such as Filter Out all PIs from NERSC).

![Filter Out Organization](images/Filter-Out-Organization.png)
{: align="center"}

There are three tasks that you will need to perform:

1.  Review the request.
2.  Approve or reject the request.
3.  Enter a computing time allocation award.

Instructions for completing each task are provided below.

### (1) Review the request

65 66
1.  You can scroll down the page to review the request online in
    your browser.
wyang's avatar
wyang committed
67 68

    Or you can print a PDF copy of the request by clicking on the
69
    'Print ERCAP' button at the top right and lower left of the
wyang's avatar
wyang committed
70 71 72
    page. (Printing works best from a Chrome browser.)

    ![ERCAP Print button](images/ERCAP-Print-button.png)
73
    {: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
74 75 76 77 78 79

2.  If there are any Attachments to the request, you will see them
    just above the Status bar. They will not be printed with the
    request, so you will need to download and print them separately.

    ![ERCAP Attachment link](images/ERCAP-Attachment-link.png)
80
    {: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
81 82

3.  When you are reviewing a request, please be sure to note the
83
    'Project Class' at # 6. If this is a Startup/Exploratory request,
wyang's avatar
wyang committed
84 85 86 87
    you will still need to make the allocation award entry, but the
    time will come from NERSC's allocation reserve and not yours.

    ![Project Class DOE Production](images/Project-Class-DOE-Production.png)
88
    {: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
89 90

    ![Project Class Exploratory](images/Project-Class-Exploratory.png)
91
    {: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
92 93 94 95 96 97 98 99 100 101 102

### (2) Approve or Reject the Request

1.  You can click on the 'Approve' or 'Reject' buton at the top
    right of the page. When you reject a request, type your reason
    for rejecting the request in the 'Comments' box and they will
    be sent to the PI with the rejection notification.

    ![DOE Review Link Reject](images/DEV-DOE-Review-Link-Reject.png)
    {: align="center"}

103
2.  If you select a request from the 'ERCAP Requests for Review'
wyang's avatar
wyang committed
104 105 106 107 108 109 110 111 112 113 114
    list, you can Approve/Reject it from the Approval tab at the
    bottom of the page.

    ![DOE Approvers tab approval](images/DOE-Approvers-tab-approval.png)
    {: align="center"}

### (3) Enter a Computing time allocation award.

#### Enter an award for a single request

1.  To enter an allocation award for a single ERCAP request, you
115
    will need to click on the 'ERCAP Requests for Review' link and
wyang's avatar
wyang committed
116 117 118
    select the request from the list by clicking on the request number
    link.

119
2.  Scroll down to the bottom of the page and click on the 'Allocations'
wyang's avatar
wyang committed
120
    tab. You may need to scroll over to the right until you find
121
    the 'Award' column.
wyang's avatar
wyang committed
122 123 124

3.  Double-click on the space in the Award column and it will turn
    into an edit box. Enter the number of hours you want to award
125
    this project. Then click on the green 'Check mark' or press the
wyang's avatar
wyang committed
126 127 128
    Enter key to save your award entry.

    ![DOE Allocation Award entry box](images/DOE-Allocation-Award-entry-box.png)
129
    {: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
130 131 132 133

#### Entering awards for multiple requests

1.  You can enter allocation awards for multiple requests at once
134
    by clicking on the 'ERCAP Awards Review' link.
wyang's avatar
wyang committed
135 136 137

2.  You can view and make awards for all of your projects by clicking
    on a blank cell in the Award column and entering the award
138
    amount in hours, then click on the green 'Check mark' or press
wyang's avatar
wyang committed
139 140 141 142 143 144 145 146 147 148 149 150
    the Enter key to save the award (same as above). You will need
    to make an entry for each repo.

3.  If a row does not have a reponame or usage data, then it is
    most likely a new request for a new project.

4.  When you enter awards in this way, the amount of time that you
    award will be summed up at the bottom of the Award column. This
    sum is only for the requests that you are working with at that
    time.

![DEV DOE Awards Review](images/DEV-DOE-Awards-Review.png)
151
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
152 153 154 155 156 157 158 159 160
 
#### Exporting Usage and Award data

From this list, you can export all of the project usage and hours
requested data to put them in a spreadsheet for your own analysis.
Right-click on any white-space in the header bar and select Export
and then the format that you want to export to.

![Export to file](images/Export-to-file.png)
161
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
162 163 164 165 166 167 168 169 170 171 172 173

After you have completed these steps, the request will automatically
be assigned back to NERSC for final approval and provisioning.

![Approved request goes back to NERSC](images/Approved-request-goes-back-to-NERSC.png)
{: align="center"}
 

---

## Using Iris, NERSC's Identity and Access Management Tool

174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236
### Navigating Around Iris

This section is to provide quick information on the top level Iris
menus only.  More detailed information on how to navigate or use
various utilities in Iris can be found in the [Iris Guide for
Users](iris-for-users.md).

#### Menu Bar

The menu bar at the top of the page has several menus, allowing you
to access different parts of Iris.

![Iris menu bars](images/iris_rjoseph_menubars.png)
{: align="center" style="border:1px solid black"}

-   The **Iris** icon in the top left corner is clickable and serves
    as the Home button. When clicked, it brings you back to the
    "Homepage" which displays the current usage of the projects
    under your Office and Program.

-   The **Projects** pull-down lists the projects that the logged-in
    user has access to and allows the user to see usage info for
    each. For allocation managers, the pull-down list will be
    normally empty.

-   The **Reports** pull-down provides various usage report options.

-   The **Tools** pull-down provides tools for transferring
    allocations, viewing info for user organizations, etc.

-   The **search box** allows you to quickly get the information
    you need about individual users or projects.

-   The account pull-down under your account name in the top right
    corner contains menu for displaying what your Iris roles are
    (e.g., User, PI, DOE Admin, ...) and what permissions you have
    in Iris.  Someone in a project group whose role is the PI, a
    PI proxy or a Project Resource Manager can edit in Iris how
    much compute time a user in the group is allowed to use.

    To logout from Iris, select the **Logout** menu item.

For certain menu items, there is also a sub menu bar under the top
menu bar, consisting of tabs for different menu items. When this
bar appears, the first value on the left refers to the context for
the page displayed. For example, if the sub menu is about your
account itself (that is, when the Iris icon is selected), the label
will be your full name, as shown in the above figure. If the sub
menu is about an allocation account, it will display the allocation
account name.

These menu bars are always available to you, and do not scroll when
you scroll down the screen.

#### Sorting the Display Data

Displayed data can be sorted by a column by clicking on the column
heading.  By default data is sorted in the ascending order. Clicking
on the heading again, you can toggle the sorting order.

The column selected for data sorting has its column heading marked
as chosen.

wyang's avatar
wyang committed
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255
### Iris Homepage Usage Report 

You can review the current usage of the projects under your Office
and Program through the Iris website,
[https://iris.nersc.gov](https://iris.nersc.gov).

When you first log into Iris, you should see a display of all the
projects assigned to your Office/Program and their current allocations
and usage. The list is sorted by project name in the ascending
order. You can re-sort the list by clicking on a column header. You
can toggle the sorting order by clicking on the header again. You
should see a bar chart of the top 5 usage repos. You can also see
the top 5 repos nearest to overcharging their allocation and the
top 5 repos by [CFS (Communitity File System)](../filesystems/community.md)
storage. If you have any time left in your Reserve, you will see a
line that shows your remaining balance in the top left corner of
the page.

![DOE Manager Usage display annotated](images/DOE-Manager-Usage-display-annotated.png)
256
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
257 258 259 260 261 262 263 264 265

### Finding Project/Repo Information

You can find basic information about a project by clicking on the
project name link under the Project column in the usage report.
Iris will show the compute usage info page for the project (that
is, the 'Compute' tab is chosen).

![Project Repo Information page1](images/Project-Repo-Information-page1.png)
266
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
267 268 269 270 271 272 273 274 275

Or if you know the project name, you can do a search by typing the
name in the search box near the top right corner of the page. In
this case, Iris will show the 'Details' page of the project.  This
page gives you additional information about the project such as the
DOE Office and Program, the Science Category, if it has DOE Office
of Science funding, the Requested hours, etc.

![Project Repo Information page2](images/Project-Repo-Information-page2.png)
276
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
277 278 279 280 281 282

You can also view the allocation transfer history for the project
by clicking on the 'Allocation transfer report' link provided on
both pages.

![Repo Transfer History](images/Repo-Transfer-History.png)
283
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
284 285 286 287 288 289 290 291 292 293 294

### Finding a Project Starting with a Person 

If you have a person's name but don't have the project name or don't
know if the person is a PI or if they already have a NERSC project,
you can track down which project they are in by starting with a
search. In the search box near the top right corner, enter the
person's name. You will see a list of NERSC users whose name contains
the search word.

![Person Search result](images/Person-Search-result.png)
295
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
296 297 298 299 300

Click on the name to go to the user's contact information page (that
is, the 'Details' tab).

![Person Details tab](images/Person-Details-tab.png)
301
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
302 303 304 305 306

On the menu bar next to the 'Details' tab is the 'Roles' tab. Click
on this tab to see what projects this person belongs to.

![Roles tab Info](images/Roles-tab-Info.png)
307
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
308 309 310 311 312 313

Click on the project link, and Iris will display the project's
'Compute' usage page. Select the 'Details' tab to see details about
the project.

![Project Details tab](images/Project-Details-tab.png)
314
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
315 316 317

### Usage Reports

318 319 320 321 322 323 324 325 326 327 328 329 330 331 332
You can easily generate compute and storage usage reports for
allocation accounts with the many report generation options in the
'Reports' pull-down menu on the top menu bar. For example, you can
generate compute usage for a certain date or a month, for an
allocation account or a group of accounts.  You can filter your
search with various categories (start time, end time, submit time,
user, project, etc.).  You can also examine batch jobs run on NERSC
hosts.

![Iris reports YTD Compute Usage](images/iris_reports_ytdcomputeusage.png)
{: align="center" style="border:1px solid black"}

You can run reports for a specific PI, Office or Program, by selecting
the appropriate filter field (in this case, 'Project', 'PI Name',
'Office', and 'Program', respectively).
wyang's avatar
wyang committed
333
 
334 335
![Iris reports YTD Compute Usage Filters](images/iris_reports_ytdcomputeusage_filters.png)
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
336

337 338 339
More detailed information on how to generate various reports, please
check the 'Reports menus' section in the [Iris Guide for
Users](iris-for-users.md).
wyang's avatar
wyang committed
340

341
### Transferring Time
wyang's avatar
wyang committed
342

343 344
Go to the 'Tools' menu on the top menu bar, and select 'Transfer Allocations'.
menu option.
wyang's avatar
wyang committed
345

346 347
![Transfer Allocations menu option](images/Transfer-Allocations-menu-option.png)
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
348

349 350
The top section of the displayed page is for making a resource
transfer transaction. To transer a resource, follow the steps belonw.
wyang's avatar
wyang committed
351

352 353 354
1.  In the 'From' section, select the appropriate reserve type
    among 'Allocation Pool', 'Allocation Type', 'Office', 'Program'
    and 'Project'.
wyang's avatar
wyang committed
355

356 357 358 359 360 361 362 363 364 365 366 367 368 369 370
2.  In the box next to it, select the appropriate reserve that you
    want to transfer from (e.g., 'Cosmic Frontier').

3.  In the 'To' section, make sure to select 'Project' and enter
    the project name in the text box (e.g., mp107).

4.  In the 'Resource Type' section, select the resource type:
    'Compute Time in hours' or 'Storage Space in TBs.'

5.  Enter the amount in the 'Amount' field that you wish to transfer.

6.  Click the 'Transfer' button.

![Transfer Time](images/Transferring-Time.png)
{: align="center" style="border:1px solid black"}
wyang's avatar
wyang committed
371

372 373 374
In the 'Reserve' section below, a table lists compute and storage
reserves for all the reserve types. There you can easily view
detailed info about reserves for your Office and Program.
wyang's avatar
wyang committed
375

376 377
![reserves](images/reserves.png)
{: align="center" style="border:1px solid black"}