Integrating Ares with the Moodle Plug-In

Follow

The Moodle Plug-in currently supports Moodle versions 1.9.5 through 2.9. For other versions of Moodle, please see Integrating Ares with LTI.

Ares is designed to work smoothly with the Moodle Course Management System, allowing library staff, course Instructors and students quick and easy access to course reserves information. By linking Moodle with Ares, Library staff, Instructors and their designated Proxies can connect with Ares and add courses and their related course reserves directly from within Moodle. Students in turn can access their courses and the course reserves requirements from within Moodle. The Moodle Course Reserves tool is linked to the Ares web interface, so Instructors and students using Moodle for course management see the same web pages they see when accessing Ares course reserves outside of Moodle.

Installation

The following text details procedures for the installation and configuration of the Ares Reserves addon developed by Atlas Systems, Inc. for the Moodle course management system. This addon allows Ares owners that are using Moodle to integrate the Moodle system with Ares.

  1. Download the Ares Moodle Addon from Ares Downloads and unzip the folder.
  2. Copy the ares_reserve folder into your moodle/blocks directory.
  3. Login to Moodle as an administrator and open http://yourmoodlesite/admin/index.php, replacing yourmoodlesite with the location of the Moodle site you are installing the addon to.
  4. After Moodle verifies the installation, click continue and proceed to the Ares global customization screen by clicking Modules/Blocks/Ares Reserves.
  5. Input a user agent, web service address and website address.
    • The service and site addresses MUST point to your Ares Web Service and Ares Web Site folders. For example, if the areswebservice.dll is located at http://localhost/ares/webservice/areswebservice.dll, then input http://localhost/ares/webservice/ in the web service field.
    • Optional - While on this screen you may also choose a default item display format.
  6. Click Save Changes.

Once Moodle is installed, Instructors can login to Moodle, select their course, and add the Ares Reserves block by turning on editing and using the add block interface in Moodle.

Moodle Authentication

When the Moodle addon is installed on Ares, both authentication and course creation are turned over to Moodle. Courses are generally set up by the Staff Administrator before the start of each semester, freeing Instructors from this task. Instructors and students log in using their Moodle Username and Password and access their Ares Course Reserves directly from within the Moodle interface.

Configuring Moodle Course Reserves in Ares

There are several major ways in which the Ares Reserves addon can be customized.

Global Customization

Once Moodle verifies the Ares Moodle Addon installation, you can proceed to the Ares global customization screen by clicking Modules/Blocks/Ares Reserves. Here you will input a user agent, web service address and website address and choose a default item display format as explained below. When all required changes are made, click Save Changes. Configuration is now complete. Once Moodle is installed, Instructors can login to Moodle, select their course, and add the Ares Reserves block by turning on editing and using the add block interface in Moodle.

Moodle and the Web Service Agent

In order to enhance security without the nuisance of having to replicate passwords from Moodle to Ares, the Ares web service uses user agents to identify the Moodle addon when it attempts to access the web service. In order for this to work, you must pick a user agent string to use and add that string both to Moodle and your Ares database.

To add the User Agent to Moodle:

  1. Open the Ares Reserves addon global configuration by logging into Moodle as an administrator.
  2. Click Modules/Blocks/Ares Reserves and type the user agent string into the User Agent field. This field is case sensitive.

To add the User Agent to the Ares Database:

During installing of the Ares web service a new table should have been added to your Ares database named WebServiceAgents. This table has only one field, Agent. Simply add a row containing the user agent string to use with the Ares Reserves addon in Moodle.

Ares Server Information

Enter the web service address and website address. The service and site addresses MUST point to your Ares Web Service and Ares Web Site folders. For example, if the areswebservice.dll is located at http://localhost/ares/ws/areswebservice.dll, then input http://localhost/ares/ws in the web service field.

Instance Configuration Settings

There are several major ways in which the Ares Reserves addon can be customized. The first is via Global Configuration as seen above. This was done when the user agent, web service and website address were set. These global configuration settings affect all instances of the Ares addon.

In addition, there are instance configuration settings. These are accessed by adding the Ares block to a course and clicking the edit icon while editing is enabled in Moodle. The following settings can be customized for each instance:

  1. Semester. This setting determines what semester is used to create the course in Ares. This is only necessary if the course does not already exist and you want the addon to create it for you.
  2. Student Item Display Format. This controls the format that is used to display Reserve Items when students view the course (see Item Formats below).
  3. Student Item Display Mode. This controls the mode that is used to display Reserve Items to students. The available options are:
    • None. Hides reserve items completely. This is best used if your course has a large number of reserve items attached to it that would end up causing the Ares addon display to become too large.
    • Text. Displays the items with no link to the item in Ares.
    • Link. Displays the items as links which will take the user to the item description page in the Ares web interface.
  4. Student Course Display Mode. This controls whether or not students are given a link to the course in the ares web interface.
  5. Teacher Item Display Format. This does the same thing as the student version, but affects the teacher's view.
  6. Teacher Item Display Mode. This does the same thing as the student version, but affects the teacher's view.
  7. Teacher Course Display Mode. This does the same thing as the student version, but affects the teacher's view.

Language Format Files

The third form of customization is via languages. Almost all of the static text used in the Ares addon can be customized via language format files. By default the addon only comes with two language format files: en_us_utf8 and en_utf8.

You can add more languages by navigating to your moodle/blocks/ares_reserves/lang folder and adding a new folder named after the language for which you are creating a file. Once you've added this folder, you can copy and paste the block_ares_reserves.php file from one of the existing language folders into your newly created folder and simply make changes to the pasted file. Only the strings to the right of the = on each line should be changed. You should also take care not to accidentally delete the single quotes around the strings or use single quotes in your modified string without escaping them using \.

Moodle uses abbreviated language names, so check the Moodle documentation for the correct naming of your language folder.

The final piece of customization that can be done to the Ares addon is adding or removing item formats. The available item formats are controlled by php code in the ItemDisplayFormats.php file. By modifying this file according to the guidelines outlined in the Item Formats section below, you can easily add your own item formats or remove/modify the formats that come with the addon.

Item Formats

By default, the Ares addon only comes with a few possible reserve item formats. This can be modified fairly easily with only a very limited grasp of PHP. To add an item format:

  1. Navigate to and open your moodle/blocks/ares_reserves/ItemDisplayFormats.php file.
  2. You will see two php objects: a function named FormatItemText and an array named $formatTypes. Both of these objects require minor modifications for each new display format.
    • The first and easiest change required is to the $formatTypes array. Entries in this array come in pairs in the format of "formatName" => "formatDescription" and are delimited by commas.
    • Add a new entry in this array using the formatname and a short description or example of the format. Note that the description is what is displayed in the format configuration drop downs.
    • After adding your format type entry to the $formatTypes array, you must add a case for your format type in the switch structure contained in the FormatItemText function.
    • The string for this new case must match the name of your format type as entered in the $formatTypes array.
  3. Once you have added your case block, you can add whatever code is necessary to create the format to your newly created case block.
    • For the most simplistic formats, the following example can be used with few changes: return "$item->Title - $item->Author"
      This produces a reserve item entry that looks like this: Scientific American - A Study of Smoking Affects on the Body.

The key to creating item formats is the $item-> part of that example. $item is a variable provided by the addon that contains pieces of information about the reserve item currently being formatted for display. Using the syntax $item->FieldName allows you to reference fields from the item. A complete list of these fields is listed below. For more complicated formats or for value checking like the type that is done in the included formats, if statements and other php constructs that are not covered here may be necessary.

Item Format Fields

  • ItemID
  • Username
  • CourseId
  • PickupLocation
  • CurrentStatus
  • CurrentStatusDate
  • ItemType
  • DigitalItem
  • Location
  • ShelfLocation
  • AresDocument
  • InstructorProvided
  • CopyrightRequired
  • CopyrightObtained
  • Active
  • ActiveDate
  • InactiveDate
  • CallNumber
  • ReasonForCancellation
  • Proxy
  • Title
  • Author
  • Publisher
  • PublicationLocation
  • PublicationDate
  • Edition
  • ISXN
  • EspNumber
  • CitedIn
  • Doi
  • ArticleTitle
  • Volume
  • Issue
  • JournalYear
  • JournalMonth
  • Pages
  • DocumentType
  • ItemFormat
  • Description
  • CccNumber
  • LoanPeriod
  • DirectLink


Moodle Field Mapping


Mapping for User Creation

The Ares plugin for Moodle uses the global $USER variable defined by Moodle for its mappings. The plugin will first check to see if the user exists by using the UserExists webservice call using the $USER->username field. If the user doesn't exist, they are created with the following mapping:

Ares User Field  Moodle User Field
 Username username
 FirstName firstname
 LastName lastname
 LibraryId blank (empty string)
 EmailAddress  email
 Status blank (empty string)
 Department  department
 ExternalUserId  id


Mapping for Course Creation

The Ares plugin for Moodle uses the global $COURSE variable defined by Moodle for its mappings. The plugin will first check to see if the course exists by using the GetCourseByExternalID webservice call using the $COURSE->id field. This attempts to find a course in Ares with an ExternalCourseId matching the Moodle $COURSE->id value. If a course is not found, it is created with the following mapping:

Ares Course Field Moodle Field
Name $COURSE->FullName
CourseNumber $COURSE->idnumber (If Moodle setting for Moodle Course Number Field is set to ID Number)
CourseNumber $COURSE->shortname (If Moodle setting for Moodle Course Number Field is set to Course Short Name)
Department $USER->department
Semester Semester from instance settings. If the setting is set to “Current Semester”, the current semester is determined by retrieving the value from calling the GetCurrentSemester from the Ares Web Service.
Instructor Username $User->Username
ExternalCourseId $Course->id

Questions?

If this article didn’t resolve your issue, please take a moment and answer a few questions to help improve our documentation:

Feedback