XPlanner SOAP Interface

New for 0.6.2:

Methods were added to the SOAP interface to support dynamic attributes associated with most XPlanner domain objects. This can be useful for integrating XPlanner with external systems (e.g. metadata for external data or systems). Generate and view the WSDL for more details.

Michael G Schwern has developed a Perl module for accessing XPlanner data. See CPAN for more details.

Overview

The design objectives for the XPlanner SOAP interface are to provide a language-independent way of efficiently accessing an XPlanner web application. The SOAP interface in XPlanner creates new opportunities for extending XPlanner functionality and integrating it with external functionality. Here are some examples of things you can do with the SOAP services:

• Write a Subversion commitinfo or loginfo Perl (or Python or ...) script that annotates an XPlanner task in a remote web application when files are commited (e.g. Subversion on Codehaus, XPlanner hosted on your servlet-enabled ISP).
• Take advantage of Microsoft's support for SOAP to write VBA scripts to chart velocities in Excel or generate reports in Word.
• Write a script that runs from a cron job to send you a daily email describing your current tasks (or the tasks of people you work with or supervise or ...). You could also generate RSS channels for tasks as they are created, completed, etc.
• Write a whole new XPlanner front end in Swing, C++, .NET or whatever while still having access to the web UI for browser-based access.
• Integrate XPlanner functionality into a portal framework or your favorite IDE (if it is SOAP-enabled).
• Synchronize XPlanner task/story status with a bug tracking system. For example, automatically create new tasks under a specified story when bugs are reported or mark a bug as resolved when the associated task is complete.

SOAP Service Endpoints

There are three services defined for accessing XPlanner using SOAP. The can be accessed at the following URLs (replace the portions of the URL specific to your installation!). The access point is http://yourhost.com:port/xplanner/soap/XPlanner.

These are authenticated services so you must use a user ID and password to access them. The same authentication you use for XPlanner web access will work for these services. Previous versions of XPlanner provided three endpoints (viewer, editor, admin) that provided different operations. Now, all operations are available through one service and XPlanner does server-side authorization on the calls.

You can download a complete WSDL from http://yourhost.com:port/xplanner/soap/XPlanner?wsdl
An overview of some of the available operations is show below (this is as of 0.6.2 and is most likely outdated):

• Project Operations
• getProjects()
• getProject(int id)
• addProject(ProjectData project)
• removeProject(int id)
• update(ProjectData object)
• Iteration Operations
• getCurrentIteration(int projectId)
• getIterations(int projectId)
• getIteration(int id)
• addIteration(IterationData iteration)
• removeIteration(int id)
• update(IterationData object)
• User Story Operations
• getUserStories(int containerId)
• getUserStory(int id)
• addUserStory(UserStoryData object)
• removeUserStory(int id)
• update(UserStoryData object)
• Task Operations
• getTasks(int containerId)
• getTask(int id)
• addTask(TaskData object)
• removeTask(int id)
• update(TaskData object)
• Time Entry Operations
• getTimeEntries(int containerId)
• getCurrentTasksForPerson(int personId)
• getPlannedTasksForPerson(int personId)
• getTaskHistoryForPerson(int personId)
• Note Operations
• getNote(int id)
• addNote(NoteData object)
• removeNote(int id)
• update(NoteData object)
• getNotesForObject(int attachedToId)
• Person Operations
• getPerson(int id)
• addPerson(PersonData object)
• removePerson(int id)
• update(PersonData object)
• getPeople()

Service API Specification

The XPlanner WSDL-based service definition file (XPlanner.wsdl) can be generated using the generate.soap.wsdl Ant target. It will be generated in the soap-stubs directory. This specification can be used to write or generate client-side proxies for the SOAP services.

Tips for writing clients

Java - See the Apache Axis toolkit. Client-side proxies can be generated from the WSDL file.

Perl - See the SOAP::Lite library. There is a sample Perl script in the xplanner/doc/soap-examples/perl directory. Be sure to look at this script since some special setup is required to use SOAP::Lite.

PHP - See NuSOAP. There is a sample Perl script in the xplanner/doc/soap-examples/php directory. I've also included a patched copy of the NuSOAP library because of a bug that existed at the time the example was written. However, the bug has been reported so I'd suggested trying the latest official version of NuSOAP.