EQ302 EQUELLA Advanced Application Administration - PowerPoint Presentation

Slide1

EQ302

EQUELLA Advanced Application Administration

Welcome to EQ302

Instructor:

Who are you?

Slide2

Course

outline

This 3-day course covers: Review of Basics Educational technology architecture EQ301 Review Advanced Administration Console External Tools Troubleshooting & Support Exercise

2

Slide3

Course Planning

3

Slide4

Course Planner Overview

Day 1:

EQUELLA concepts & reviewEducational ArchitectureUser ManagementUser, Groups, RolesLDAPReplicated Data storeSecurity ManagerCollection ManagementAccess controlsITEM XMLXSLT / Display summaryExpert scripting (wizard / save script)

Day 2:

BIRT Reporting

SOAP Services

Integration Interface

Day 3:

Exercise

(Morning)Dynamic CollectionsHarvestingEQUELLA Tools & Troubleshooting

4

Slide5

Course CONTENT – DAY 1

5

Slide6

Get your laptop ready

Copy Virtual Box installation files to your computer (from external hard-drive)

Install Virtual Box on your laptopStart Virtual BoxImport Appliance -> Select VM302_EQ302_EQ5_MQU.ova fileOnce Imported, Start Ubuntu from within the Virtual BoxIt includes everything you need:EQUELLA 5 QA1 Installation with InstitutionsLDAP ServerBIRT Report DesignerLogin to the student1 institution and create yourself a user login

6

Slide7

EQUELLA review - Concepts

1

7

Slide8

Anatomy of an EQUELLA Item

An item is a grouping

of digital content andmetadata.

8

Slide9

Contribution

EQUELLA items are created by contribution. During contribution each item is given a copy of the collection metadata schema and the copy is filled with information from the contribution wizard.

Information is also added by the system including:A unique identifier called a UUIDTime and date of contributionItem status. 9

Slide10

EQUELLA item lifecycle

Create

Archive

EQUELLA Repository

10

Slide11

Access control lists (ACL)

ACL configure the items and functionality available to EQUELLA users by granting or revoking privileges.

ACL provide a hierarchy of inherited privileges enabling:Institution ACL to be applied to all collections, items or users.Collection ACL to be applied to all items in the collection.Item ACL to be applied to specific items.Role ACL to be applied to all users associated with that role.Simple and powerful control over items and users.

11

Slide12

Workflows

The interaction between the various content management roles is coordinated by a workflow.Workflows automatically notify reviewers when a review is required.Workflows are typically created by an application administrator (You).12

Slide13

Anatomy of an EQUELLA Repository

13

Slide14

EQUELLA Support

2

14

Slide15

15

User level supportTypically this support is provided by a local support team lead by the system administrator.Contact your local support team as the first step to resolving user issues.

Slide16

16

Institution level support<insert specific instructions>

Slide17

Community forum

EQUELLA Community Site:

www.equella.comDesigned to facilitate interaction amongst the EQUELLA client community.USER EXERCISE: Register at the community site, if you have internet access and haven’t done so previously17

Slide18

EQUELLA Review – EQ301

3

18

Slide19

EQ301 Review

User management introduction

Create internal users, groups and rolesEQUELLA schemasCreate schemasEQUELLA collectionsCreate collectionsVisibility scripting (contribution wizard)Display templatesTaxonomiesCreate taxonomiesACL Introduction (item metadata ACL)EQUELLA Workflows

EQUELLA SearchesHierarchiesEBI (demo?)

19

Slide20

Educational Technology Architecture

4

20

Slide21

EQUELLA Educational Technology Architecture

Database

ServerEQUELLA Application ServerHost Operating System

Java Virtual Machine

Tomcat App Server

LUCENE

Indexes

EQUELLA Config Files

File Share

File Store

(Attachments)

Browser

HTTP

HTTP

HTTP/SOAP

Scripts/Tools

LMS(s)

Integration

Module

HTTP

21

Slide22

Institution Manager

22

Slide23

Topics

What is it? Where is it?

How to back up EQUELLA InstitutionsHow to edit/enable/disable EQUELLA InstitutionsOther institution manager features23

Slide24

Institution Manager’s URL

Allows hosting and managing of

institutions (sharing the same DB and filestore, but else independent of each other)Configured in mandatory-config.properties fileMay be its own URLSome organisation’s internet-facing EQUELLAs only let the institution manager listen to localhost for greater securityAccessed via:http://<configured url>/institutions.do?method=adminOn the VM: http://localhost/institutions.do?method=admin

24

Slide25

Institution Management Options

Create new institutions

Disable existing institutions (disallows any login)Edit existing institutions (only the URL, the filestore location is fixed upon creation)Clone existing institutionsDelete existing institutions (also erases its filestore)Export existing institutions (backup)25

Slide26

Exporting EQUELLA Institutions

If the institution’s attachment folder is less than ~10GB, you may export with attachments

Note: if it is over 1.5GB, then only export in Google Chrome. The export will crash Firefox and IEIf the institution’s attachment folder is greater than 10GB, export without attachmentsCopy the attachments folder manually to its new home26

Slide27

Exporting EQUELLA Institutions (cont’d)

Best practice is to disable the institution first, but this is not required

If you don’t care to save the audit trail, don’t export the audit logs.This can really slow things down if it has never been purged.On highly active institutions, this could exceed a million rowsTo exclude options, move the option from the left box to the right box.Typically, only the audit logs and the Item Attachments are excluded. Excluding other options may result in unstable institutions when they’re re-imported.27

Slide28

Exporting EQUELLA Institutions (cont’d)

Institutions are first exported to the staging folder

Once everything is converted, EQUELLA compresses (tars and gzips) the institution for downloadIf you don’t want to use a browser to download an institution, you can find it in the staging folder and tar/gzip it yourself. This is unsupported, however ... But it has gotten consultants out of trouble several times 28

Slide29

Importing EQUELLA Institutions

Simply navigate to an institution import, and click “Import”

It unpacks the institution into the staging folderThen it gives you the option to exclude certain parts of the institution, similar to an institution export.You do not need to exclude Item Attachments or Audit logs if they were excluded from the exportOnce imported, you will be prompted to configure the filestore path and the institution’s URL. You may also change the password for TLE_ADMINISTRATOR here (more on this user later)29

Slide30

Editing an Institution

Change the institution’s name

Change the institution’s URLChange the password for the TLE_ADMINISTRATOR userChange the institution’s time zoneCannot change the filestore path30

Slide31

Server Settings

May set a server message, which appears whenever a user logs into EQUELLA.

May set the System Password – this is the password for the Institution ManagerMay update the licence hereUser Exercise: Set a server message and logout/login to see the message for a user.31

Slide32

Downloads

Downloads for the current

EQUELLA version:Blackboard Building BlockBlackboard Vista and CE PowerlinkMoodle Modules (1.9 / 2.x)Sakai ToolEQUELLA Integration Pack (Documentation and examples for EQUELLA SOAP API and JavaScript API) -> more on this today/tomorrow32

Slide33

Thread Dump

Shows EQUELLA Tomcat JVM thread activities at the time of the page load

Refresh the page to get a more current thread dumpUseful for developers to help troubleshoot problems33

Slide34

Cluster Health

Shows the health of the cluster (if configured)

Download the EQUELLA Cluster ToolHelps to configure/troubleshoot clustering problems34

Slide35

Demonstration / User Exercise

Locate the Institution Manager

Login Download the EQUELLA Integration packExport the current EQ302 institution ‘student1’ (with attachments/audit logs)35

Slide36

Advanced Administration Console

4

36

Slide37

User management

37

Slide38

User Management

Users in EQUELLA are managed by the User Management Tool (Administration Console)

It provides User Management Plug-ins (UMP) to connect to external authentication/user management systemsEQUELLA also has internal/local user, group and role management (covered in EQ301)Authentication may be integrated with UMPs such as LDAP (including Microsoft Active Directory), replicated data store or other External Authentication Systems38

Slide39

UMP List (available in EQUELLA)

• LDAP—users are managed with an external LDAP system;

• Replicated Datastore—users are managed by a system with an exportable database; • Internal Users—users are managed by EQUELLA; • Internal Groups—user groups are managed by EQUELLA; • Internal Roles—user roles are managed by EQUELLA; • Suspensions—users that are suspended from EQUELLA (no matter which UMS holds their data); 39

Slide40

UMP List ...

• CAS—users are authenticated from a central authentication server;

• Shared Secrets—users are authenticated for access to EQUELLA from an external system; • Share Pass—enables users to share licensed content with anybody; • Remote Support—provides TLEI with data to diagnose problems; • External Authentication—users are managed by an external authentication system.40

Slide41

EQUELLA User Management

41

Slide42

Internal / Local Groups

IMPORTANT:

Internal users assigned UUID (unique), removing or changing this will result in orphaned items (items with no owner)May be hierarchicalInheritance:Parents do not inherit users from child groups!Child groups inherit users from parent groups!Cannot assign LDAP groups to local groups42

Slide43

Roles

May have users, local groups, LDAP groups, network ranges, http referrers, and SSO connections assigned as members

Three “special” users:everyone: literally everyone. If a function does not require authentication (like view item), you do not need to be logged in if assigned to everyoneLogged in users: like everyone, except that you must be logged inGuest users: Can configure a guest user which does not require a password to loginTLE_ADMINISTRATOR (another form of special user with special privileges, it is your saviour if all goes wrong)Roles must not have other roles as membersRoles may be configured with “Match Any”, “Match All”, “Match None” to get complex membershipsBest practice dictates that permissions are assigned to roles

43

Slide44

Suspensions

Administrators may suspend user accounts without removing them

Admin Console (User Management -> Suspensions)44

Slide45

Shared Secrets

Allows SSO into EQUELLA without native logins

Requires an Identifier and Shared SecretRequires a properly configured integration (like an LMS)May prefix or postfix usernames to disambiguateMay be configured to only work from an:IP address rangeHTTP ReferrerMay allow the creation of a local user account if one doesn’t already exist in the systemDEMO: Shared Secrets Configuration45

Slide46

TLE_ADMINISTRATOR Login

Special Local User Account

Has special configurations (by default)Password is set in the institution managerWhat can it do? Basically everything. EQ401 covers this and the System parts of the Administration Console.46

Slide47

Replicated Data Store (Overview)

Provides method for automatically creating EQUELLA users from any data store that can be queried using SQL

Configuration stepsConnect to DBMap queries to EQUELLA user attributesEnable Replicated Data store UMPSupported DBsOracle 9i, 10g & 11gMicrosoft SQL Server 2000, 2005, 2008PostgreSQL 8.0 +

47

Slide48

Replicated Data Store

Your DB structure will have some specific tables to be able to be used as an external authentication system, some of which are:

UserGroupGroupMembershipCachedGroupMembershipMembershipRoles

48

Slide49

EQUELLA & LDAP Configuration

EQUELLA can be configured to allow LDAP authentication

LDAP (Lightweight Directory Access Protocol) is different for every LDAP systemEQUELLA supports multiple LDAP schemasLDAP Configuration in EQUELLA:Configure connection to LDAPMap LDAP user data to EQUELLA user attributesEnable the LDAP UMPNOTE: With LDAP turned on, internal users are still able to connect to EQUELLA (if there is no LDAP user with the same credentials)LDAP takes preference over internal user authentication (basically it is in order these UMPs appear on the User Mgmt list)

49

Slide50

EQUELLA & LDAP Configuration (hands-on)

User Exercise on LDAP configuration:

Logon to studentLDAP institution in your VM using int.demosysadminLaunch Admin ConsoleOpen the LDAP UMPConfigure LDAP (walk through with instructor)Save settings & login with LDAP userWhat do you see?

50

Slide51

51

Slide52

52

Slide53

Security management

53

Slide54

Topics

ACL best practice

Override and revokeRelationships between common permissionHow to troubleshoot permissions problems (e.g. linked permissions)Administration Console functionality restrictions 54

Slide55

Security Best Practice I

EQUELLA ACLs work much like firewall ACLs

Keep a permissions spreadsheet as an audit of your security permissions. Update the spreadsheet when you make security changesIn the absence of an explicit “Grant”, there is an implicit “Revoke”The ACL closest to an object is the one that firesACLs are applied “Downwards” from the Institution level all the way down to an item levelDon’t forget that there is item status ACLs and item metadata ACLsACL overrides are applied upwards. A higher level override takes precedence to a lower level override55

Slide56

Security Best Practice II

When new ACLs are introduced, typically their default will not be set (an implicit revoke). Perform a security audit after each upgrade.

Grant at the highest level possibleMinimise Revokes wherever possibleUse Overrides sparingly (if at all)If you make mistakes and lock yourself out, the TLE_ADMINISTRATOR user is your failsafeMap users to groups and groups to roles. Always grant permissions to roles.Keep your security as simple as possible56

Slide57

Some Concerns

Changing item permissions cause an immediate reindexing on the affected collection

Changing anything in a collection with DRM causes an immediate reindexing of that collectionTherefore, make your changes in batches and only save when necessary.57

Slide58

Ways to view permissions

From the Administration Console -> Security Manager

Viewing an object in the Administration Console and clicking on its “security” tabYou can find individual items in the Items folder in the Security ManagerThe different views have different ways of allocating securityExercise: Find an item in EQUELLA, then check its permissions via the Security Manager58

Slide59

Sample permissions – linked permissions

List of permissions is available in the Security Guide document

Examples of permissions for an EQUELLA item:VIEW_ITEM, EDIT_ITEM, NEWVERSION_ITEM, ARCHIVE_ITEM, etc...Linked permissions (important for troubleshooting)SEARCH_COLLECTION – allows searching a collection in guided searchDISCOVER_ITEM – allows finding the items via (basic) search and browseVIEW_ITEM – allows viewing the item attachments 59

Slide60

Administration console permissions & Troubleshooting permissions

Restrict access to functionality

EDIT_USER_MANAGEMENTVIEW_SECURITY_TREEEDIT_SECURITY_TREECREATE_SCHEMA, DELETE_SCHEMA, EDIT_SCHEMA (to disable/enable view and access on the admin console)Troubleshooting permissionsWhat to do if you locked yourself out?How to find solutions to permission problems?Think linked permissionsCheck items

60

Slide61

Security User Exercise

In the

studentLDAP institution and modify the institution to do the following:Login with TLE_ADMINISTRATORHINT: Don’t forget to disable LDAPCreate 4 local users (int.reportUser, int.searchUser, int.viewUser, int.adminUser)Create 4 local groups (int.reportGroup, int.searchGroup, int.viewGroup,

int.adminGroup)Create 4 roles (reporting, searching, viewing, admin)

Assign users to their retrospective groups (

int.reportUser

to

int.reportGroup

) and their roles (reporting)

Disable Administration Console rights for all of these users

61

Slide62

Security User Exercise cont...

Update the permissions for the following users:

reportUsers can only create and generate reports and administer data (Manage resources)searchUsers can only search collections and generate reports, but cannot view attachments nor create reportsviewUsers can search the image collection ONLY and can view their items and attachmentsPlease make sure all other sidebar (navigation) links except for Dashboard, Favourites, Search and My resources are disabled.Enable the following administration console right for the administration user (HINT: user?):User Management (all admin rights)Collections (all admin rights)Login with each user and check that their permissions are correct !

62

Slide63

EQUELLA DASHBOARD

63

Slide64

EQUELLA Dashboard

64

<insert current dashboard image>

Slide65

EQUELLA Primer – Dashboard

Quick introduction to the following EQUELLA

x features:Dashboard custom linksDashboard portletsPermissions that hide/show custom links and portlets65

Slide66

EQUELLA Primer – Custom Links

Custom links in EQUELLA

x are similar to Navigation Groups / Links from EQUELLA 4.1Allows Administrators to specify links for different groups of usersPermissions used with custom links:CREATE, DELETE, EDIT, VIEW_CUSTOM_LINKSEDIT enables the link on the settings page66

Slide67

EQUELLA Primer – Portlets

Portlets

are little widgets of code for targeted functionalityThey allow users to customize their EQUELLA dashboardAllow Administrators fain-grained permissions to show/hide portlets to groups of usersPermissions used with custom links:CREATE, EDIT, DELETE, ADMINISTER, VIEWADMINISTER_PORTLETS will provide the link in the settings page67

Slide68

EQUELLA Dashboard

– User exercise

Using the studentLDAP institution and your previously created users:Create custom links (set of 2 links) for the viewUsers, no other users should see those linksCreate a recent contributions portlet for all users to seeCreate a favourites portlet and only show this to the reporting userOnly allow the admin user access to modify portlets and links

68

Slide69

Collections

69

Slide70

Topics

EQUELLA item XML nodes and meanings

Display Summaries with XSLTEQUELLA Script APIDynamic access controls in collections70

Slide71

EQUELLA item XML nodes and meanings

How to view an item XML (EQ301 covered this, remember?)

Try one now !Item XML nodes User generated schema Nodes / System Generated Nodes EQUELLA ACL for viewing an item XML (VIEW_RAW_ITEM)71

Slide72

Viewing item XML

Viewing item XML can be useful for:

troubleshootingchecking differences between versions of an item. The displayed XML will be a combination of:entered metadata and system generated metadata.

72

Slide73

System generated XML

The nodes for system generated XML are appended to the item metadata schema and cannot be accessed when editing a schema.

System generated XML contains system related information such as the item ID, the version number, the date of creation or editing, the workflow steps the item has been through, etc. System generated XML typically takes the form of an XML attribute.

73

Slide74

System generated XML

This is an example of system generated XML attributes:

<item id="7a9204a1-22be-957c-7408-963c1c07bbef" itemdefid="b4c2ddf0-b647-db8b-1e0d-d899d851724a" itemstatus="live" key="30219" version="1">This is an example of system generated XML elements:<datecreated>2010-01-27T16:49:30+1100</datecreated>

<datemodified

>2010-01-28T11:08:40+1100</

datemodified

>

<

dateforindex

>2010-04-09T09:09:17+1000</

dateforindex>

74

Slide75

Display Summaries with XSLT

What is an XSLT?

How can it be used for EQUELLA?Examples?75

Slide76

Display Summaries with XSLT cont.

What is an XSLT?

XSLT stands for eXtensible Style Sheet Language TranslationIt is used to generate HTML displays from an XML structure (the EQUELLA item XML)Use in EQUELLA?XSLT instead of the in-built metadata displaysXSLT fragments to target specific metadata nodes/subtrees of an item XMLLet’s have a look at one !

76

Slide77

EQUELLA Script API

How to get it?

API OverviewHow to write to the logger (logger.log()) and check the output (show and tell !)Sample script exercise (show and tell !)77

Slide78

Scripting User Exercise

Expert Save Script (Keywords splitter)

Using the EQUELLA documentation collection, write a save script to split keywords, separated by comma and target a repeating keyword metadata node of the schema (this may require schema modification).Log at the start and end of the script, also when splitting the keywords (Logger Object)Modify the item summary display template to show these keywords78

Slide79

Dynamic access controls in collections

Item Metadata ACL (done in EQ301?)

Administration Console -> Collections -> Security Tab -> Item Metadata ACLsUser Exercise: Using the images collection, create a metadata ACL that allows only the system administrator to view images in the ‘Kids’ albumHow do you find the XPATH to the schema node?79

Slide80

External Tools – Day 2

5

80

Slide81

Reporting & BIRT

81

Slide82

Overview

Part I:

What is BIRT?What can it do?How do I get it?How do I use it?Part II:Sample reportsCreate reportsCreate your own report (Exercise task for Friday !)82

Slide83

EQUELLA Reporting

EQUELLA allows authorized users to view reports on system and user activity (and a little more….)

Reports are constructed using BIRT, the Business Intelligence Reporting Tool and are generated by querying the database natively.Reports can be returned as HTML, PDF or Excel and can take parameters for user input.Reports can also include hyperlinks, and these can be made back to EQUELLA® items or include sub-reports.

83

Slide84

What is EQUELLA Reporting?

Report Designer is a customised version of BIRT (Business Intelligence Reporting Tools).

BIRT is a product derived from the Eclipse Foundation, it supports the development of complex reports using relational database queries.84

Slide85

Report

Designer

85 <insert image>

Slide86

Report Output in

Equella

86

Slide87

EQUELLA Reporting Basics - Terms

87

Slide88

EQUELLA Reporting Basics – Data Sets

88

Slide89

Basic Reports

Metadata, User Info, Usage, Simple Lists

89

Slide90

Complex Reports

Drill-down reports

Cross-tab reports90

Slide91

Overview & Prerequisites

You need...

A copy of the EQUELLA Report Designer (installed on a machine that can communicate with the EQUELLA repository)DESIGN_REPORT privilege for the userDevelop and test the reportUpload the report to the EQUELLA server (via the Admin Console)SQL knowledge is a requirement if you want to write your own reports91

Slide92

How to get it... if not using the VM

Windows

<insert info here>MacDownload Eclipse & Birt package from http://www.ecliplse.org/bit/phoenix/Update Eclipse with the EQUELLA Data Connector files to be able to use it on your EQUELLA repositoryInstructions can be provided92

Slide93

Hands on from here ...

Start it up

Quick demo on the Report DesignerGuide through a simple reportView the Database tables.....93

Slide94

EQUELLA DB Tables

You may need the following:

ITEM (for item information)TLEUSER (for INTERNAL user information other than the UUID)LDAP users need to be found via the User Management Data Source)BASE_ENTITY (for collection ID information and link to the below)LANGUAGE_STRING (for collection and item name information)AUDIT_LOG_ENTRY (for any usage reports, as this is where logs get written into, depending on EQUELLA’s configuration)94

Slide95

EQUELLA Reports with Parameters

Parameters in BIRT allow users to input information, based on which the reports are executed. Examples are:

Days for usage reportDays for CAL reportCollection names for individual Institute’s informationParameters are defined in BIRT under the Report Parameter folder in the Data Explorer TabOnce this is done, you have to add the parameter to the query to allow this parameter to be used in the running of the reportExample:SELECT * FROM ITEM WHERE ITEM.STATUS = ?

95

Slide96

AUDIT_LOG_ENTRY Reports

Useful to get Usage information. A very complex table, where depending on the user action, different values are written into table fields

Important to note are the following entries:EVENT_CATEGORYITEM (SUMMARY_VIEWED, CONTENT_VIEWED)USER(LOGIN, LOGOUT)SEARCH96

Slide97

Additional Reports

Demo of the following:

Xml Extracter code for OracleReport with a graph/chartJoint DataSet report (joining User Mgmt and DB query)Data Cube example report97

Slide98

Group inheritance UPDATE (REMINDER)

98

Slide99

HARVESTER & Dynamic Collections

99

Slide100

HARVESTER & DYNAMIC COLLECTIONS in EQUELLA

EQUELLA can harvest from external sources (OAI & LORAX) using the Harvester functionality or can be harvested by external applications (other EQUELLAs) using Dynamic Collections

OAIbased on Dublin Core XML nodes Open Archives Initiative (http://www.openarchives.org)Open standard for harvesting world-wideLORAXLearning Object Repository Access and eXchangeSOAP interface developed by The Learning FederationUsed to harvest The Learning Federation repositories

100

Slide101

HARVESTER in EQUELLA

Allows content from third-party sources to be collected and uploaded to the local EQUELLA repository

Requirements:Access to Harvester Profiles tool (set permissions in Admin Console)Know type of Harvester (OAI, LORAX, EQUELLA) and server detailsCollection you want to harvest intoImport Transformation XSLT (show code) to convert OAI set to local schema nodes

101

Slide102

Dynamic Collections in EQUELLA (outgoing)

Access to Dynamic Collections (set permissions in Admin Console)

Dynamic Collection can be set up as a harvestable collectionSpecific filtering can be applied to the collection(s) to only harvest certain types102

Slide103

SOAP Web services

103

Slide104

SOAP

What is it?

104

Slide105

SOAP API

Used to provide a thin application layer on top of EQUELLA

Documentation available from the Institution manager OR from the Support siteAPI walk-throughSOAP API examples (LDAP script, EQUELLAizer, Bulk-upload of course material, Reading List Applications (UTAS, CIT))Hands-on show and tell (upload an item, search and display)Explain touch scripts !!! What are they, why are they useful?User exercise:Develop a python SOAP API script that uploads a file to the Image collection.105

Slide106

Simple Object Access Protocol

Computer centric interface to application, an API.

Usually XML over the web (proxy friendly)Language agnostic (Java, Python, PHP etc..)WSDL describes the APILanguage specific tools used to create interfaces from WSDL106

Slide107

SOAP in EQUELLA

Several “endpoints” (SoapService50, SoapService41).

Most functionality in latest SoapServiceXX.Endpoints remain compatible in newer versions. E.g. SoapService41 still works in 5.1Major additions to the API get new endpoint.EQUELLA SpecificsSession is maintained by http cookie.We try to use basic types.Structured data is usually sent as strings containing XML.107

Slide108

What can you do?

Items

Create/Edit/Delete/ArchiveManipulate attachmentsSome workflow (accept/reject, task list)CommentsTaxonomy editingSearchingRaw queries (e.g. text and xpath queries)Manipulate hierarchiesUser managementEditing internal users/groups108

Slide109

EQUELLA Soap Clients

Clients in 4 different languages; Java, PHP, Python and C#

Downloadable from the “Downloads” tab of the Institution Management page.Thin layer on top of raw SOAP calls.Not a direct one-to-one mapping of the WSDL.Let’s look at the sample Python code…109

Slide110

EQUELLA Python Client

Library code

equellasoap.pySOAP request code, wrapper codeutil.pyUtility code (generate tokens, encode urls)Sample appssettings.pySettings shared by the apps (Institution URL, Username/Password)search.pySearch for items and display their names/URLs

contribute.pyContribute items with an attachment

110

Slide111

settings.py

#An example institution URL of http://www.myhost.com/path/to/institution/ will be broken down us such:

institutionUrl = 'http://host:port/context/'

username

=

'username'

password

=

'password'

#use this if your network connection requires use of proxy. if the proxy requires authentication the

url

will of the form http://username:password@proxyurl:proxyport

proxyUrl

=

None

#You can specify

useTokens

= True to append a single-sign-on token to the results of the search result URLs.

#Note that to use this functionality, the Shared Secrets user management

plugin

must be enabled (see User Management in the EQUELLA Administration Console)

#and a shared secret must be configured.

useTokens

=

False

tokenUser

=

'

someUsername

'

sharedSecretId

=

'

someSecretId

'

sharedSecretValue

=

'

someSecretValue

'

111

Slide112

search.py

import

settingsimport equellasoapfrom

util

import

generateToken

from

util

import

urlEncode

equella

=

equellasoap.EquellaSoap

(

settings.institutionUrl

,

settings.username

,

settings.password

,

proxyUrl

=

settings.proxyUrl

)

results

=

equella.searchItems

(

'test'

)

tokenPostfix

=

''

if

settings.useTokens

==

True:

tokenPostfix

=

'?token=%s'

%

urlEncode

(

generateToken

(

settings.tokenUser

,

settings.sharedSecretId

,

settings.sharedSecretValue

)

)

for

result

in

results.iterate

(

'result/xml/item'

):

print

'%s: %

s%s

'

%

(

result.getNode

(

'name'

),

result.getNode

(

'

url

'

),

tokenPostfix

)

equella

.logout

()

112

Slide113

equellasoap.py

“

searchItems” has optional parameters in equellasoap.py, the WSDL does not.Not everything in the WSDL is in equellasoap.pyAll XML is parsed and manipulated by a python class call XmlWrapper (very similar to the “xml” object in wizard scripting)Contains calls for manipulating taxonomies too, which is a different endpoint.113

Slide114

SOAP API client examples

Bulk upload scripts for clients (network drives, directory structures, etc..)

User & group creation, assign group membership Taxonomy uploads Reading List Applications (more on this later)EQUELLAizer (Moodle Content Harvester)Full Application Layer implementation (OLE) using almost all the functionality of EQUELLA via SOAPMoodle EQUELLA Admin Block uses SOAPeReserve Bulk Migration to EQUELLA

114

Slide115

SOAP API Reading List Application

Reading List Application

Developed for 2 clients so farUTAS, CIT (in client testing phase)Written in PHP, using the PHP SOAP API for EQUELLALet’s have a closer look !http://rlms.utas.edu.au/erl/http://ereadinglist.cit.edu.au/index.php

115

Slide116

SOAP API Reading List Application (UTAS)

116

Slide117

SOAP API Reading List (UTAS)

117

Slide118

SOAP API Reading List (UTAS)

118

Slide119

UTAS Reading List

119

Features:Browse, search and display items from various EQUELLA collections (SOAP API)Links to EQUELLA items/attachments Links to Horizon Library catalogueEZPROXY protected access to content in EQUELLA (no EQUELLA login) -> middleware authentication mechanism used at librariesFlexible citation options (displayed using PHP)Overnight batch process to pre-populate arrays, HTML files for faster loading times

Lot of work into XML manipulation/extraction

Slide120

UTAS Reading List II

120

Multiple EQUELLA collections setup to support itReading List Management (Configuration)Unit Reading Lists (Units)Reading List Items (Items for units)Exam papers (Exams)Ebook, ImageTS Items (Transcription Students / Disabled access) (possible future extension)All the above collections are accessed via SOAP (Using PHP) to retrieve necessary items

Slide121

SOAP API Reading List Application (CIT)

121

Slide122

SOAP API Reading List Application (CIT)

122

Slide123

CIT Reading List

123

API Usage:Search itemsDisplay attachment and item linksList taxonomy termsDiscipline list is a taxonomyDifferences to UTASUTAS uses a cron process to pre-populate a text file and html file, which are rendered on first load

CIT uses the taxonomy SoapService endpoint to retrieve a live list of disciplines on first load

Slide124

SOAP API Taxonomy Code

124

function getDisciplineTerms($query) { global $_VGLOBAL; $taxID = $_VGLOBAL['TAXONOMY_DISC']; $equella = new EQUELLA(); $discTerms = $equella->listTerms($taxID

, ""); foreach ($discTerms

as $disc):

foreach

($disc as $item):

echo '<

li

><a target="iframe_detail" href="'.$_VGLOBAL['phproot'].'erlreadinglistdetail.php?disc='.$item.'">'.$item.'</a></li>'; endforeach

; endforeach

;

}