View on GitHub

openEQUELLA

A digital repository providing a single platform to house your teaching and learning, research, media, and library content.

Testing Tips

While not a recommendation for production use, the following are tips for sandbox and testing use.

Zookeeper

Build a ZK Quorum

openEQUELLA Clustering in a Sandbox

Integrations

Authentication

Attachments

Zookeeper

To shutdown Zookeeper:

cd /usr/local/zookeeper-3.4.X
bin/zkServer.sh stop

To check if Zookeeper is active:

echo stat | nc <<ZK IP>> 2181

Build a ZK Quorum

To turn several standalone ZK nodes into a quorum:

openEQUELLA Clustering in a Sandbox

  1. Filestore:
  2. Create a shared directory on one of the servers
  3. In mandatory-config on the sister node(s), use the path that shared path
  4. DB:
  5. On the node your database is running on:
  6. In pg_hba.conf, add the following to the bottom of the file: Note - if your sister node IPs are not covered, adjust accordingly.
    host all all 192.168.1.120/24 trust
    host all all 192.168.1.121/24 trust
    host all all 192.168.1.122/24 trust
    
  7. In postgresql.conf, ensure the following is in place:
    listen_addresses = '*'
    
  8. Then it’s just a matter of wiring in your nodes together via hibernate.properties, mandatory-config.properties, and optional-config.properties.

Integrations

Blackboard Quick Start

In openEQUELLA:

  1. Setup a Shared Secret. For the login, select ‘create a local user’ and add them to a group with enough ACLs (discover / view items).
  2. If working with an openEQUELLA that supports LTI Auth (such as 6.3-QA2+), create an OAuth client following the LTI Auth flow, and setup the LTI Mappings. (both from the Web UI Settings page).
  3. Ensure there are items / attachments available.

In Blackboard:

  1. If EQ is http, ensure mixed content is allowed in the browser.
  2. To test Bb / openEQUELLA from a student’s point-of-view in a given course, using the Admin Bb user:
  3. Go to a course
  4. In the left hand nav menu under ‘Course Management’, select ‘Users and Groups’ > ‘Users’
  5. Click ‘Enroll User’ > ‘Create User’.
  6. Fill in the needful, and click ‘Submit’.
  7. Remove any old openEQUELLA WebService and openEQUELLA Building Blocks in Blackboard.
  8. Upload your desired openEQUELLA Building Block. Set Available, and then configure the settings.
  9. Go into ‘System Admin’ > ‘Tools and Utilities’ > ‘Tools’. Search for the openEQUELLA plugin, and turn on the 3 Availability toggles. Allow it to be available for new AND existing courses / etc.
  10. If you want to test push-to-lms functionality, install the Web Service (jar can be obtained from the building block, or if a custom build, it’s one of the two artifacts from running ‘ant product’.
  11. openEQUELLA should now be hooked up to Blackboard. To test:
  12. Go into a course
  13. Select Information or Content from the left nav
  14. On the ribbon on top of the ‘editable’ area, click ‘Tools’ > ‘openEQUELLA Object’. Select an item or attachment and enjoy!

Canvas

The available Canvas site is hosted in the cloud by Instructure. Go to the website https://canvas.instructure.com/login and create a free account.

From there, you can setup an integration with a given openEQUELLA install.

  1. Create a Canvas module before trying to select an openEQUELLA resource from Canvas or use the Push To LMS feature in openEQUELLA for Canvas.
  2. There is a Canvas config guide in the docs repo. It would be good to pull out the quick start details into here.

Moodle

Same deal as Canvas… Would be good to pull out the ‘quick start’ version here.

Authentication

External Authentication

TBD

LDAP

Setup a default LDAP server. The following setup has been proven to work against the primary use cases (below):

LDIF

Import these as ldif files into the o=equellasupport partition via Apache Studio

groups.ldif

dn: ou=people,o=equellasupport
objectclass: organizationalUnit
objectclass: top
description: Contains entries which describe users
ou: people
dn: ou=groups,o=equellasupport
objectclass: organizationalUnit
objectclass: top
description: Contains entries which describe groups
ou: groups

users.ldif Password is pass.

dn: cn=John Doe,ou=people,o=equellasupport
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
objectclass: top
cn: John Doe
description: cn=John Group,ou=groups,o=equellasupport
title: cn=John Doe,ou=people,o=equellasupport
givenname: John
sn: Doe
uid: jdoe
mail: jdoe@example.com
userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=

dn: cn=Jo Smith,ou=people,o=equellasupport
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
objectclass: top
cn: Jo Smith
description: cn=Jo Group,ou=groups,o=equellasupport
title: cn=Jo Smith,ou=people,o=equellasupport
givenname: Jo
sn: Smith
uid: jsmith
mail: jsmith@example.com
userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=

mapUsersToNestedGroups.ldif

Configure openEQUELLA to use Apache DS as LDAP

General

LDAP Mappings

Primary Use Cases

  1. Login to openEQUELLA with an LDAP user
  2. Confirm CREATE_ITEM ACL works when assigned to a specific user
  3. Confirm CREATE_ITEM ACL works when assigned to a group that your logged in user is a part of
  4. Confirm Diagnostics work to find groups by user
  5. Confirm Diagnostics work to find users by group
  6. Via the security manager, retrieve an LDAP group to grant ACLs against, and confirm it affects a member ldap user. (similar / same to #3, but good to call out)
  7. Via the internal roles, search and add an LDAP group to grant ACLs, and confirm it affects a member ldap user.
  8. Via the internal roles, browse for an LDAP group, highlight the group, and the browse for LDAP users. All LDAP users in that group should display.
  9. Probably more use cases would be good to confirm…

Notes

General

Under ‘LDAP Mappings’, when the Personal object class is blank, openEQUELLA assumes ‘person’. The ‘Group Object Class’ however, is not given a default. Plugging in ‘groupOfUniqueNames’ for group object class allows the group-centric use cases to work.

Setup a partition

  1. Open Apache Studio
  2. Right click on the ‘‘openEQUELLA LDAP connection’ entry in the ‘Connections’ tab.
  3. Select ‘Open Configuration’ > Partitions
    • Click ‘Add’
    • Provide connection details:
    • Partition Type: JDBM
    • id: openEQUELLA Support
    • Suffix: o=equellasupport
    • Leave the rest as defaults
  4. Restart LDAP Server from Apache Studio
  5. You might need to reload the entities in the Root DSE - Eclipse (Studio) tends to cache these values.

RDS

RDS stands for Replication Data Store. The Postgres backup file and openEQUELLA institution tgz provides a complete example (TODO - need to locate). Inspecting the instition should give a good idea of how the RDS should be setup.

The basic concept is user, groups, and roles from the RDS will be available to openEQUELLA once the RDS UMP is configured and enabled - it’ll behave similarly to openEQUELLA Internal Users / Groups / Roles.

Putting the following in learningedge-config/learningedge-log4j.properties will log all replicated datastore queries that are performed in the resource-centre logs (requires a restart though)

log4j.logger.com.tle.core.usermanagement.standard.ReplicatedUserPlugin=DEBUG

Attachments

For an example set of attachments, the following has been historically useful for troubleshooting integration issues.

LTI

The following is a set of directions on how to create an LTI attachment:

  1. Configure an Attachments control to accept “ExternalToolProvider(LTI)” attachments.
  2. Go to Settings/ExternalToolProviders(LTI) and create tool provider TestTP1 as follows.
  3. BaseURL=https://www.edu-apps.org/tool_redirect?id=wiktionary
  4. IconURL=http://icons.iconarchive.com/icons/martin-berube/animal/32/pig-icon.png
  5. Make up a ConsumerKey, SharedSecret and CustomParams(such as dog=Fido,cat=Puss).
  6. Tick both Privacy Options then Save.
  7. Start to contribute an item with an LTI attachment, setting the attachment’s properties as follows.
    LTIProvider=TestTP1
    LaunchURL blank
    Display name=<make it up>
    
  8. Finish the contribution process.
  9. It should succeed. Attachment should be playable.
  10. Contribute another item with LTI, details as follows.
  11. Just check that it is playable.
  12. In openEQUELLA create an LTI Consumer.
  13. In Moodle go to SiteAdministration/plugins/plugins overview/LTI/Settings.
  14. Start to add an external tool configuration.
  15. Make up a ToolName, then point the ToolBaseURL to one of the LTI items you just contributed in openEQUELLA.
  16. Set the ConsumerKey and SharedSecret to match the openEQUELLA settings, then Save.
  17. Still in Moodle, go to a Course and click AddActivityOrResource/ExternalTool.
  18. Fill in details as follows, then Save.
    ActivityName=<make it up>
    ExternalToolType=Automatic
    LaunchURL=<the equella attachment URL>
    
  19. You should be able to play the attachment from Moodle now.

SCORM

The SCORM version and edition is specified in the manifest:

<metadata>
  <schema>ADL SCORM</schema>
  <schemaversion>2004 4th Edition</schemaversion>
</metadata>

For examples, refer to http://scorm.com/scorm-explained/technical-scorm/golf-examples/