Download through your institution

Pangur's server cannot sign in to your library or university, so for a paywalled work the most it can do is give you a link (Where PDFs come from). Pangur for Mac can go further. It opens the publisher's page in a window of its own, on your Mac and your network, signs in through your institution if it needs to, downloads the PDF and attaches it to the item. For some publishers it can download a whole book chapter by chapter and join the chapters into one PDF.

The steps the Mac follows are written down as source flows. A sign-in flow says how to sign in to one institution and which publishers that sign-in unlocks. A download flow says how to find and download the PDFs on one publisher's site. Pangur provides flows for some institutions and publishers as templates, and you can write your own.

Downloading from source needs Pangur for Mac. You can see and edit your flows in the web settings as well, but only the Mac runs them.

Downloading a PDF from sourceCopy Anchor Link

1. In Pangur for Mac, open the item. It needs a web address starting https://, a DOI or, for a book, an ISBN.
2. Open the item's menu and choose Download PDF from source…. The Download source window opens.
3. Pangur opens the source and works out a route (see How the Mac chooses a route). If a sign-in flow needs you, for example to complete a security check or a sign-in page it cannot fill in, the window shows the page and waits for you.
4. When the window has found PDFs, it lists them. Choose Download PDF, then Add PDF to item. Access is checked when the download runs, not when the list is made.

For a book that a download flow handles, the window downloads each chapter and joins them. If a chapter fails, the download pauses and keeps the chapters it has, and Continue book download carries on from there.

The window has a few more controls for when the automatic route does not work. Sign in with chooses a sign-in flow by hand, opens your Institution proxy page, or opens Saved sign-in details…. Check for PDFs looks again for PDF links on the page in the window. Show page and Hide page show or hide the page. Open in browser opens the source in your browser, although a sign-in you make there stays in the browser and does not help the window. Forget source access clears everything the window has stored from websites, including its sign-ins, so that the next attempt starts afresh.

If the item's menu shows Update the Mac app to download from source, the installed Pangur for Mac is too old for this item. Update it from Pangur › Check for Updates….

When the download failsCopy Anchor Link

Saving your sign-in detailsCopy Anchor Link

A sign-in flow that types a username and password uses details you save on the Mac.

1. In Pangur for Mac, choose Pangur › Settings.
2. For each sign-in flow that needs details, fill in the fields (the flow names them, for example Email and Password) and choose Save.

The details are kept in the Mac's Keychain, under your Pangur account. They are not sent to Pangur's server, and the Mac types them only on the sign-in pages the flow names. If no flow needs details, the settings say so and offer Add flows in Source flows.

How the Mac chooses a routeCopy Anchor Link

For each download, Pangur for Mac works through three possibilities in order and stops at the first that gives it PDFs.

1. Your institution's network. If you are on the network of an institution that unlocks this publisher, the Mac downloads from the publisher's own address with no sign-in at all. A network counts if it is in a sign-in flow's own list of networks, or if it is one you saved for that flow. Pangur's server checks your address against those lists.
2. Your sign-in flows. Otherwise the Mac tries each switched-on sign-in flow that unlocks this publisher and has the saved details it needs, in the order of your list. After signing in, it runs the publisher's download flow through that institution's proxy.
3. No access. If neither works, the window says there is no access and names any flows it skipped because their details were not saved.

Flows that need your institution's EZproxy address are skipped when you have not set one in Settings › Institution.

If you are working at an institution whose network Pangur does not know yet, and a book download finds no access, the window offers Add this network for …. Adding it saves your current network to that institution's flow, so that later downloads there go straight to the publisher.

Managing your flowsCopy Anchor Link

Open Settings on the web or in the Mac's main window, and choose Source flows.

Your flows lists your flows in the order the Mac tries them. Move up and Move down change the order, the On switch turns a flow off, Edit changes it and Delete removes it. Templates lists the flows Pangur provides; Add … copies one into your flows, and when Pangur publishes a newer version of a template you added, your copy shows Update available and Update replaces it. New flow starts a blank Sign-in flow or Download flow. For a sign-in flow, IP access lists the networks where the institution gives access without signing in: Add this network adds the network you are on, and Add range adds a network range.

The templates are:

Writing a flowCopy Anchor Link

The flow editor has a Visual view, which lists the steps, and a YAML view, where you write the flow as text. Save stores it. If the YAML has a mistake, the editor tells you which line.

A flow is a YAML mapping. These keys are common to both kinds of flow:

A sign-in flow also has these keys:

A download flow also has publishers, the host names it handles.

StepsCopy Anchor Link

Each step is a mapping named by its type, such as - click: {selector: "button.pdf"}. A selector can be one CSS selector or a list of them, tried in order.

The variables available to a flow are $INPUT, $BOOK_URL, $TITLE, $USERNAME and $PASSWORD (sign-in flows only), $EZPROXY_BASE and $EZPROXY_HOST (from Settings › Institution), any variable a step stores, and loop variables such as $_FOREACH_INDEX.

What a flow cannot doCopy Anchor Link

Because a flow types saved passwords into pages, it is only allowed to drive and read the page. Pangur refuses steps that run code or reach outside the page, including run_command, run_script, execute_js, call_api, invoke_llm, upload, screenshot, while and the window-switching steps.

The networks must be public because a private range, such as a home router's, would match every home network and so unlock the publisher from anywhere.