# Getting Started with Web Services in Sakai 2.1

## Preface

This is a work in progress.

comments and suggestions to s-githens AT northwestern.edu

Everything is Creative Commons.

## Introduction

### Available Web Services in 2.1

Sakai 2.1 includes built-in support for creating and modifying Users, AuthzGroups, and Sites via Web Services. This allows for an easy way to add large numbers of users and sites to your system. It is also easy to build your own web services to open up portions of Sakai.

However, this is still a small subset of things that should be available. In future releases you can expect to see built-in web services for a much broader category of services. You should be able to do things such as post announcements and add events to calendars using web services, without needing to write your own.

Another limitation with the currently availble web services in Sakai is that you still need to understand a good bit about how Sakai works under the covers. You can expect more developer-friendly bindings to emerge in the future.

## 20 Minute Quick Start

### Prerequesites

To get started with web services in Sakai 2.1 you need:

- a Sakai 2.1 Installation

- a Programming Language with Support for SOAP Proxies

That's it. Once you have your Sakai Instance up and running you should be able to connect to it. Perl and Python are good candidates for getting started. They have a simple syntax for creating and using SOAP Web Services. We will use Python for now.

### Where are the web services?

The Apache Axis project was integrated into Sakai for the 2.0 release. Axis provides an engine for deploying web services using the SOAP specification. Axis also provides a simple means for deploying methods written in Java as Web Services. You can begin using this feature immediately with little to no knowledge of the actual SOAP specification, or any web service specification for that matter. This involves putting java code into files that end with a *.jws extenstion. We will refer to these as JWS files.

The above figure shows where the JWS files live on the deployed server. They are inside webapps/sakai-axis. The URL for connecting to them from a client is the usual URL for a webapp plus the "?wsdl" parameter. This parameter lets Axis know that you are trying to connect to the file as a web service. Let's take a quick look at what a JWS file looks like.

    import org.sakaiproject.api.kernel.session.cover.SessionManager;
    import org.sakaiproject.service.legacy.user.User;
    import org.sakaiproject.service.legacy.user.cover.UserDirectoryService;

    public class UserWebService {
    	public String addNewUser( String sessionid, String userid, String firstname, String lastname, String email, String type, String password)
    	{
    		Session s = SessionManager.getSession(id);
    		s.setActive();
    		SessionManager.setCurrentSession(s);

    		try {
    			User addeduser = null;
    			addeduser = UserDirectoryService.addUser(userid, firstname, lastname, email, password, type, null);
    		}
    		catch (Exception e) {
    	 		return e.getClass().getName() + " : " + e.getMessage();
    		}
    		return "success";
    	}
    }

If you put the above code snippet into a file named UserWebService.jws and placed it into the sakai-axis directory, you could then connect to it using the URL, "http://pedagogy:8080/sakai-axis/UserWebService.jws?wsdl". Viola, we've just created a web service to add new users to Sakai!

We can see that a JWS file contains a public Java class, and whatever import statements it needs. Any method declared as public will be available via the web service. You can use private functions to do other work in your class and they won't be available to the web service. One caveat is that you cannot yet declare your web service class to be in a package. That support is coming in the future however.

That's all you need to create a simple web service in Sakai 2.1. Wow, that was easy! At some point in your web service career you may want to create more complex SOAP services. These would require more than one *.jws file, however, you'd be surprised how far this coarse grained strategy can get you.

Now might be a good time to search the Sakai Source for the SakaiLogin.jws and SakaiScript.jws and take a peek at them. We will use them in the next section.

### Creating Users and Sites

To demonstrate writing a client, we will write a python script that adds a few users to Sakai, and then creates a site for them. First, the entire contents of the example script.

    import os
    import sys
    from SOAPpy import WSDL

    loginsoap = WSDL.SOAPProxy("http://localhost:8080/sakai-axis/SakaiLogin.jws?wsdl")
    scriptsoap = WSDL.SOAPProxy("http://localhost:8080/sakai-axis/SakaiScript.jws?wsdl")

    sessionid = loginsoap.login("admin", "admin")

    print scriptsoap.addNewUser(sessionid, "teacher", "Bob", "Smith", "bob@pedagogy.edu", "", "password" )
    print scriptsoap.addNewUser(sessionid, "student1", "Laura", "Hope", "laura@pedagogy.edu", "", "password"
    print scriptsoap.addNewUser(sessionid, "student2", "Sam", "Goodman", "bob@pedagogy.edu", "", "password" )
    print scriptsoap.addNewSite(sessionid, "psych101", "Psych 101 ", "Psychology", \
                                "Psych", "", "", True, "access", True, True, "", "" )

    print scriptsoap.addNewPageToSite(sessionid, "psych101", "Announcements", 0)
    print scriptsoap.addNewToolToPage(sessionid, "psych101", "Announcements", "Announcements", "sakai.announcements", "")
    print scriptsoap.addMemberToSiteWithRole(sessionid, "psych101", "teacher", "maintain")
    print scriptsoap.addMemberToSiteWithRole(sessionid, "psych101", "student1", "access")
    print scriptsoap.addMemberToSiteWithRole(sessionid, "psych101", "student2", "access")

Running this script on the command line will show results something like:

    sgithens@thumbtack$ python QuickExample.py
    success
    success
    success
    success
    success
    success
    success
    success
    sgithens@thumbtack$

Results of QuickExample.py

Writing a script like the one above typically requires the following steps:

1. Creating SOAP Proxies

2. Authenticating, getting a Session ID

3. Performing the work

In our case, we create two soap proxies. One of them is to the SakaiLogin web service that lets us login and returns a Session Id. The second is to the SakaiScript web service containing the methods we need to perform useful work. For Sakai 2.1, these are the primary web services use you'll use (unless you create your own). The code to create these proxies is:

    loginsoap = WSDL.SOAPProxy("http://localhost:8080/sakai-axis/SakaiLogin.jws?wsdl")
    scriptsoap = WSDL.SOAPProxy("http://localhost:8080/sakai-axis/SakaiScript.jws?wsdl")

Next we authenticate to get a Session Id. A Session Id isn't strictly necessary to use Sakai Web Services. The majority of web service methods will take a Session Id since most parts of Sakai are restricted to users with certain permissions. To get a Session Id we use the SakaiLogin webservice:

    sessionid = loginsoap.login("admin", "admin")

We use the admin user account in order to have permission for adding Users and Sites to the system.

With our SOAP Proxies and Session ID in hand, we can now use methods from SakaiScript to add Users and Sites to our Sakai installation. Adding Users:

    print scriptsoap.addNewUser(sessionid, "teacher", "Bob", "Smith", "bob@pedagogy.edu", "", "password" )
    print scriptsoap.addNewUser(sessionid, "student1", "Laura", "Hope", "laura@pedagogy.edu", "", "password"
    print scriptsoap.addNewUser(sessionid, "student2", "Sam", "Goodman", "bob@pedagogy.edu", "", "password" )

This adds 3 users to the system and prints the results (hopefully success). The Session Id is from our login web service. Try using this script and substituting "admin" with a normal Sakai user and their password. It will fail. The methods also takes parameters for User ID, Firstname, Lastname, email, type, and password. We can leave the type blank. Some Sakai installations use this field for special purposes.

The next few lines create a Site, and a Page with a Tool for the site.

    print scriptsoap.addNewSite(sessionid, "psych101", "Psych 101 ", "Psychology", \
                                "Psych", "", "", True, "access", True, True, "", "" )

    print scriptsoap.addNewPageToSite(sessionid, "psych101", "Announcements", 0)
    print scriptsoap.addNewToolToPage(sessionid, "psych101", "Announcements", "Announcements", "sakai.announcements", "")

The first thing to note is that we leave a lot of parameters blank. They are most or less optional for the purposes of this excercise, and some of their descriptions are out of the scope of a 20 minute getting started guide.

The first call adds a new Site with the ID "psych101". The other strings offer various labels for the course. See the Javadoc'd entries on SakaiScript.jws for a full description of the parameters. (note: I am still JavaDoc'ing it).

Next we add a new page. A page is one of the entries that shows up on the Sidebar in Sakai. We then add an Announcement tool to the page. For both methods we use the Site ID, "pysch101" to indicate which Site we are adding pages and tools to. For Pages and Tools though, the names of the ID's are not always so clear, so we use the human readable label, "Announcements" to add them. This is not the cleanest approach, but it works for now. Just be sure not to make multiple Pages with the same label, or multiple tools on a page with the same label. "sakai.announcements" is the type of tool we are adding.

Lastly, we add the users to the newly created site.

    print scriptsoap.addMemberToSiteWithRole(sessionid, "psych101", "student1", "access")
    print scriptsoap.addMemberToSiteWithRole(sessionid, "psych101", "student2", "access")

The second parameter is the Id of the Site we created, the 3rd that of the user that is being added to the site. The last parameter contains the name of the role for the new user. For this exercise we give intructors the "maintain" role, and students the "access" role.

### Wrapping Up

This small introduction as touched on the essential things you need to get a Web Service up and running in Sakai 2.1. From here you will probably want to learn more about using SOAP in your favorite programming language and dive into other Sakai Documentation to gain an in-depth understanding of the platform.