sakai newcomer 10 easy questions not so easy

Slide 1

Sakai Newcomer: 10 easy questions not so easy

Daniel Merino Echeverra ([email protected])Centro Superior de Innovacin Educativa - Universidad Pblica de Navarra

A brief presentation about us

March 2010

European Sakai Conference Valencia - Spain..

Universidad Pblica de Navarra


March 2010

European Sakai Conference Valencia - Spain.. Universidad Pblica de Navarra

A small university created in 1987.

8669 students.

911 teachers.

26 degrees.

Located in Pamplona (Navarra)

About 200000 citizens.

Maybe you have heard about the Sanfermines.


March 2010

European Sakai Conference Valencia - Spain..WebCT 4.1 since 2001/02.

June of 2007: 66,43% average of use.

3000 courses, 800 teachers, 8000 students.

Aulario virtual fully integrated in academic activity.

Migration to Sakai.

2008/09: Pilot of Sakai 2.5.3. Migration of contents.

2009/10: Sakai & WebCT in production at the same time.

2010/11: End of WebCT.

Disclaimer

March 2010

European Sakai Conference Valencia - Spain..This conference is about our experience.

We only have worked with Sakai 2.5.

Some things could have been fixed in newer versions.

This document is for newcomers.

Lost in the beginnings with Sakai.

With non too technical profile.

Corrections & contributions are welcome.

1- Where can I find documentation?

March 2010

European Sakai Conference Valencia - Spain..Is the first question a newcomer will do.

Not an easy question.

Open source documentation is contributive.

Every version of software can change things.

The most boring thing in the development process.

Sakai official page is a good starting point.

http://sakaiproject.org --> Support --> Documentation

2.5 and 2.6 guides, linking scattered resources.


March 2010

European Sakai Conference Valencia - Spain..But Sakai documentation is not perfect.

Some docs in the source code are a bit obsoletes.

The wiki (Confluence) is huge, but..

The pages are not classified about relevance.

The old obsolete info is not always deleted.

Is hard to know what is useful and what is not.

The JIRA title descriptions are sometimes confusing.


March 2010

European Sakai Conference Valencia - Spain..Some advices.

Read the Sakai book.

Good non-technical reference.

Many links to extend the information.

Look the previous conferences programs.

There are great documents out there.

All the programs are in Confluence.

Look the blogs (planetsakai.org).

Some blogs go in depth with concrete themes.


End-user documentation.

Few oficial documents.

It seems that each university makes its own documents.

Two awesome public resources.

Delaware:

http://www.udel.edu/sakai/training/gettingstarted/index.html

Oxford:

https://weblearn.ox.ac.uk/portal/hierarchy/info/page/browse_hel

2- How can I migrate contents?

March 2010

European Sakai Conference Valencia - Spain..A critical matter if you come from other platform.

Users want their old contents.

Starting from scratch can discourage them.

Two different problems here.

The contents organization structure.

The contents themselves.


March 2010

European Sakai Conference Valencia - Spain..The usual import schema.


March 2010

European Sakai Conference Valencia - Spain..Problems about this schema.

IMS CP partially supported.

Only Melete imports it (AFAWK).

Melete has its own resources folders.

Each platform has its own IMS standard

So each platform needs its own IMS parser.

There are several solutions already availables.

But probably you will have to touch some code.


March 2010

European Sakai Conference Valencia - Spain..Another distinct simpler schema.

2 -How can I migrate contents?

March 2010

European Sakai Conference Valencia - Spain..A simple WebDAV script can upload the contents

To a site's Resources.

To an user's MyWorkspace Resources.

You can optionally create HTML pages.

Linking the files and showing them in WebContent tool.

Flexible visual design with CSS files.

Our experience.

Our teachers love Resources

But they hardly use the WebContent pages.

3- How do the permissions work?

March 2010

European Sakai Conference Valencia - Spain..Realms, Roles, Permissions.

One of the most dangerous things in Sakai.

Very complex configuration.

Little documentation.

Disastrous consequences of a bad use.

Once settled, hard to change in existing sites.

We explain three examples that happened to us.


March 2010

European Sakai Conference Valencia - Spain..First real example: site.visit

Every maintain & access role has it checked.

We gave it to the realm !user.template.

We thought that they could only visit their sites.

But !user.template sets global permissions.

Result: URL direct access to every site.

Every user can visit every site, pasting its URL.


March 2010

European Sakai Conference Valencia - Spain..Second real example: site.upd.site.member

We assigned it to the realm !user.template

We thought that it affects only to user's MyWorkspace.

We wanted that users could unsubscribe of their sites (this is configurable in the site's xml file).

But MyWorkspace is ruled by !site.user.

!user.template sets user's global permissions.


March 2010

European Sakai Conference Valencia - Spain..Second real example: site.upd.site.member

User permissions prevail over site permissions.

The sites access role hasn't site.upd.site.member.

But the global !user.template permission wins.

Result: Any user can add users to their sites.

It doesn't matter if he is access or maintain.


March 2010

European Sakai Conference Valencia - Spain..Third real example: realm.add/del/upd

We thought that realms are a matter of admins.

Problems with public resources.

Users can't make public resources.

Other users can't revert to private contents.

Any public resource has its own realm.

Users must have permissions over realms in their sites.


March 2010


Read carefully the permissions document deployed with Sakai. http://confluence.sakaiproject.org/download/attachments/37290420/sakai_permissions_2-1-2.pdf

Then read carefully Configuring Sakai Boston 09: http://confluence.sakaiproject.org/display/CONF10/Wednesday+-+Configuring+Sakai

Make a collaborative wiki to document your permissions.

So you can see other's changes and others can see yours.

Don't touch permissions without being sure about what they do.

Specially the !user.template permissions, which are global.

If you need to propagate a role to existing sites, look here: http://steve-on-sakai.blogspot.com/2009/05/roles-in-sakai-sites.html

4- How can I configure sites?

March 2010

European Sakai Conference Valencia - Spain..Enter as admin.

In MyWorkspace/Sites, you have templates.

!user: Configure MyWorkspace's template.

!user.guest

!user.registered

!admin: Configure admin's MyWorkspace template.

!gateway: Configure the portal's gateway template.

These templates have pages with tools.

All sites inherit their corresponding templates.


March 2010

European Sakai Conference Valencia - Spain..Worksites are different.

Configure them in sakai.sitesetup.xml.

Categories (project, course, etc).

Tools of each category.

There is a !worksite too in sites, but is overriden.

More useful information about configuration:

Configuring Sakai Boston 09

(http://confluence.sakaiproject.org/display/CONF10/Wednesday+-+Configuring+Sakai)


March 2010


It's hard to change existing sites.

Changes in templates don't propagate to existing sites.

You'll need webservices to do this.

We had about 800 bad MyWorkspaces...

Home: Announcement's limit set to 3.

Home: Without Messagecenter synoptic tool.

Home: Iframe with a height value too big.

Just be sure about the tools you want!

5- Which tools should I use?

March 2010

European Sakai Conference Valencia - Spain..Many tools to choose.

http://confluence.sakaiproject.org/display/DOC/Tool+List+%282.x%29

Several tools for similar things.

2 blogs (Blogwow & Blogger)

3 forums. (Forums, JForum & Yaft)

2 testing tools (Samigo & Mneme)


March 2010

European Sakai Conference Valencia - Spain..There is an official (deprecated?) classification.

Core tools.

Included in the release. Tested and following best practices.

Provisional tools.

Mature enough to be included in the release.

Not fully tested in production, not enabled by default.

Contrib tools.

Not formally QA'ed, neither included in releases.

Is being replaced by the Scorecard Working Group.


March 2010


Some contrib tools might look better than core tools.

Nicer user interfaces.

Some better and extra functionalities.

But several core functionalities aren't obvious.

Integrations with other tools (e.g. Section Info or Resources)

i18n.

More deeply tested and more community support.

Always check that somebody is using the tool in production.

6- How can I patch my Sakai?

March 2010

European Sakai Conference Valencia - Spain..JIRA is not too intuitive.

The principal page has attachments of tested patches.

Users can think that these attachments are the real patches.

But usually they are only temporary tests.

The true patches are obtained with Subversion.

You must get them from the official source code.

Search for your Sakai version's patch, if available.


March 2010

European Sakai Conference Valencia - Spain..We must look in the tab Subversion commits.

Search for our Sakai version's patch, if there is any.

If there isn't, we can try the trunk patch revision.

Generate the revision of the patch with Subversion.

svn diff -r 45235:45236 https://source.sakaiproject.org/svn/dav/branches/ sakai_2-5-x/ > parche.patch

Apply the patch with the command patch (in Unix).

patch -p0 < parche.patch (with --dry-run for testing the patch without applying).


March 2010


A JIRA page example.

7- How can I modify the help pages?

March 2010

European Sakai Conference Valencia - Spain..Sakai brings a bunch of help pages.

There are several properties included.

help.button: Showing the help button.

help.location: External location for help.

help.url: URL to use instead of built-in help.

display.help.menu: Showing/hiding the help's link.

But we can change the built-in help easily.


March 2010

European Sakai Conference Valencia - Spain..Each tool has (should have) a folder with:

A help.xml file.

A bunch of html files linked from help.xml.

For example, sam/samigo-help/src/sakai_samigo/

You can edit these files to change whatever you want.

You must redeploy and restart to see changes.


March 2010

European Sakai Conference Valencia - Spain..These changes can include i18n.

You can translate the help to your language.

You just must create:

A translated help_xx_XX.xml file (e.g. help_es_ES.xml)

The translated html pages linked from it.

Redeploy, restart and it's done.


March 2010


8- How can I change the Sakai appearance?

March 2010

European Sakai Conference Valencia - Spain..Skin (portal's visual design)

Well documented in sakai_skin.doc (https://source.sakaiproject.org/svn/reference/trunk/docs/architecture/sakai_skin.doc)

Static content

Several pages are static, without i18n.

At {sakai_root}/reference/library/src/webapp/content/

myworkspace_info.html : Initial info in the user's My Workspace.

webcontent_instructions.html: Template for Web Content Tool.

webdav_instructions.html: Webdav tutorial at Resources tool.


March 2010

European Sakai Conference Valencia - Spain..Tools names.

{sakai_root}/tool/tool-impl/impl/src/bundle/tools.properties

These are the tools names in the database.

Can be i18n'ed too (e.g. tools_es_ES.properties).

Properties

Each tool has its own properties files.

The texts of Sakai can be modified or i18n'ed.


March 2010

European Sakai Conference Valencia - Spain..An useful shell script to locate properties (Unix).

find . -name "*.properties" -print -exec grep "Text to locate" {} \; |more


March 2010

European Sakai Conference Valencia - Spain..Our advice:

If you change this and you are more than one person...

...make common collaborative environments.

Repositories.

For files (e.g. properties and static html content)

Wiki pages.

For text (e.g. tools names).

Individual local copies can be a living hell.

9- How can I change the Wiki's pages?

March 2010

European Sakai Conference Valencia - Spain..Wiki's default pages are based on templates.

Default page: used in all new pages.

Help pages: normal help and macros help.

Etcetera.

These templates are created from a properties file.

./rwiki-tool/tool/src/bundle/uk/ac/cam/caret/sakai/rwiki/tool/bundle/PrepopulatePages.properties

These templates:

support i18n partially (they use the tomcat's language).

are used one only time for site (when the wiki is created).

the pages created from them are stored in the database.


March 2010

European Sakai Conference Valencia - Spain..Any maintain can change the templates in his site.

Just use the macro {index} before creating content.

More awesome documentation at http://udel.edu/~mathieu/wiki/


March 2010

European Sakai Conference Valencia - Spain..More advices, of course.

Changing globally the created pages is hard.

Raw database sentences.

The user's changes in these pages will be lost.

We changed all our wiki's help pages.

We changed the prepopulate_pages_es_ES.properties.

So all the new help pages are OK.

We changed the database tables.

update rwikicurrentcontent set content='Wiki Help Page's Formatted Content'

where rwikiid = any (select distinct id from rwikiobject where name like '%edit_right%')

10- How can I change things without restarting Tomcat?

March 2010

European Sakai Conference Valencia - Spain..An annoying matter.

You change a tool and deploy it with mvn.

Theorically, Tomcat should notice the changes.

But it's needed (we, at least) to restart Tomcat to see them.

A non general solution.

touch /webapps//WEB-INF/web.xml

It restarts only that tool.

Only possible with light tools.

Heavy tools (e.g. portal, site, etc) still need the restart.

March 2010

European Sakai Conferenca Valencia - Spain..

sakai newcomer 10 easy questions not so easy

Documents