Connect Moodle

This guide is for Moodle administrators connecting their institution to Alexandria.

There are two ways to connect. The plugin does everything in one click and is what we recommend. The manual LTI route exists for sites that cannot install plugins.

Which route to use

	Plugin (recommended)	Manual LTI
Effort	Install plugin, fill two fields, click once	Register tool, then adjust several settings
Course and material sync	Configured automatically	Not included, contact us to add it
Launch container	Set to new window for you	You must set it yourself
Requires	Ability to install a local plugin, Moodle 4.1+	Nothing beyond admin rights

Unless your institution forbids third-party plugins, use the plugin. It sets up the LTI tool, the web service, the service account, and the launch behaviour in one step, and each of those is something that can be got wrong by hand.

Plugin (recommended)

Step 1: Install the plugin

Request the local_alexandria plugin package from us at [email protected], then either:

• go to Site administration → Plugins → Install plugins and upload the ZIP, or
• copy the folder to <moodle>/local/alexandria and run php admin/cli/upgrade.php.

The plugin requires Moodle 4.1 or later.

Step 2: Connect

1. Go to Site administration → Plugins → Local plugins → Alexandria connection.

2. Fill in Your name and Your work email. Use your institutional address: its domain tells us which email domains belong to your school, and it is how we reach a real person if something needs attention later.

3. Click Connect.

Enlarge

The connection page on a site that has already been connected, before the first connection the button reads Connect, afterwards Reconnect.

That single click does all of the following, so that you do not have to:

• enables web services and the REST protocol
• creates a dedicated external service exposing six read-only functions and nothing more: site info, user lookup by field, a user’s courses, course lookup by field, course contents, and enrolled users
• creates a dedicated service account and role scoped to exactly those functions
• registers Alexandria as an LTI 1.3 tool in the active state, with the launch container set to new window and the tool available in the activity chooser
• reports the connection to Alexandria

The page then reports back. “Connected. Alexandria is active for your institution” means you are done. “Almost there” means everything on this site is set up and we are verifying the institution by hand, you will be emailed at the address you entered once it is approved.

What the service account can and cannot do

It can read the course content and enrolment data Alexandria needs. It cannot write anything, cannot see grades, and cannot administer your site. Inspect it under Site administration → Server → Web services → External services.

Step 3: Check it appears

Alexandria is now in the activity chooser. An educator adds it to a course the same way they add any other activity.

Manual LTI

Use this route if you cannot install plugins.

Step 1: Register the tool

1. Go to Site administration → Plugins → Activity modules → External tool → Manage tools.

2. Paste this into the Tool URL box at the top of the page and press Add LTI Advantage:

   https://production-backend.libraryofalexandria.nl/lti/register

Enlarge

Paste the registration URL into Tool URL and press Add LTI Advantage. A registered tool appears below as a card marked Active.

Moodle contacts Alexandria and the tool configures itself.

Step 2: Set the launch container

1. On the newly added tool’s card, click the pencil icon to open External tool configuration.

2. Set Default launch container to New window.

This step is easy to miss and the integration will not work without it

Alexandria signs users in through a secure cookie exchange, which browsers only permit in a top-level tab. Left as an embedded default, the sign-in is blocked and the tool appears to hang or shows a blank frame.

The plugin route sets this for you. This route does not.

Step 3: Activate and expose the tool

1. On the same configuration page, set Tool configuration usage to Show in activity chooser and as a preconfigured tool, so educators can add Alexandria to a course like any other activity. Save the page.

2. Back on Manage tools, check the tool’s card reads Active. A newly registered tool can sit under Pending until you activate it from the card.

Enlarge

Both settings that this route does not fill in for you live on one page: Tool configuration usage and Default launch container.

What this route does not include

Manual registration gives you working launches and nothing else. Course and material sync runs over a separate Moodle web service token, which the plugin creates automatically and this route does not. If you want sync, email us after registering and we will walk you through creating the token by hand.

Deciding where Alexandria appears

Registering the tool, by either route, makes Alexandria available to your whole site. Two settings on the tool’s own configuration page narrow that, and both matter more to a pilot than to a full rollout.

Find them at Site administration → Plugins → Activity modules → External tool → Manage preconfigured tools. Preconfigured tools are grouped under Active, Pending, and Rejected tabs. Open the pencil icon next to Alexandria on the Active tab.

Enlarge

Tool configuration usage controls who can reach Alexandria, and Restrict to category controls where.

Tool configuration usage

This decides how visible the tool is to educators. It offers exactly three choices:

Setting	What educators see
Do not show; use only when a matching tool URL is entered	Nothing. The configuration applies only if someone pastes a matching URL themselves
Show as preconfigured tool when adding an external tool	Alexandria in the tool list, but only after choosing the External tool activity
Show in activity chooser and as a preconfigured tool	Alexandria alongside Assignment and Quiz in the activity chooser

The plugin sets the third. That is the setting you want unless you are deliberately keeping Alexandria out of sight during an evaluation.

Restrict to category

Underneath, Restrict to category lists your course categories with a checkbox each. Moodle’s own help for the field says it restricts use of the tool to courses within the categories you select. This is the closest Moodle has to the org unit and sub-account scoping other systems offer, and it is how you run a pilot: tick the category holding the pilot courses and Alexandria stays out of every other course on the site.

An empty category list means every course

Leaving every checkbox unticked does not mean “no courses”. It means no restriction, so the tool is available site-wide. If you intended a limited pilot and ticked nothing, you have just published Alexandria to your whole Moodle.

Scoping is per category, not per course. If your pilot courses sit in different categories, either move them or accept that the category around them comes along.

Institution verification

If your Moodle runs on your institution’s own domain, for example moodle.your-university.nl: Alexandria verifies the institution automatically and the connection goes live immediately. This covers most self-hosted Moodle sites.

If it runs on a shared hosting domain that identifies the host rather than your institution, a person reviews the registration first. We confirm within one working day, and launches show a holding message until then.

What educators and students see

The first educator to launch Alexandria from a course is taken to a setup page where they link the Moodle course to Alexandria and choose which materials the AI may use. This takes a few minutes and happens once per course.

A student who launches a course the educator has not set up yet sees a page explaining that the course is not ready and asking them to check back.

Course copies and restores

Moodle gives a copied or restored course a new context ID. Alexandria reads the course from the launch every time, rather than remembering it against the link, so a copy is treated as a new course: the educator is walked through setup again, and students see the “not ready yet” page until that is done.

Launches never break, and they never silently serve the previous term’s materials.

Troubleshooting

When a launch cannot complete, Alexandria does not fail silently: the user gets a page naming the problem and an error code to quote to you.

Enlarge

What a student sees when a launch fails. The error code identifies the cause, LTI-05 means the launch URL in the tool registration does not match the one Alexandria expects.

Moodle-specific problems are below. For issues common to every LMS, see Troubleshooting LTI launches.

The tool opens a blank frame or spins forever. The launch container is not set to New window. The plugin sets this for you, so this should only affect manual registrations.

Educators cannot find Alexandria when adding an activity. Tool configuration usage is not set to Show in activity chooser and as a preconfigured tool, or the tool’s card on Manage tools is not Active.

Alexandria is missing from some courses only. Restrict to category is ticked for a category those courses are not in. See Deciding where Alexandria appears.

Launches work but no course materials appear. The web service token is missing. Expected on manual registrations, email us to add sync.

Data and privacy

• Received per launch: issuer, a stable user identifier, email address, LTI role, and course context.
• Received via the web service (plugin route): course content, materials, and enrolment lists, through six read-only functions.
• Hosting: processed and stored in the EU on Google Cloud. Encrypted in transit (TLS 1.2 and above) and at rest (AES-256).

Full detail is in the Trust Center and the privacy policy.