Version 5.0 and all following versions of  todo4teams do support webservices in REST-format. REST is Representational State Transfer, see here for an introduction.

This interface allows external applications to retrieve, search, create and modify tickets.

The todo4teams RESTful Services support the file-formates XML and JSON plus additionally (for some services) HTML.  The client sets the HTTP-Header-Attribute Accept (during the retrieving of data) and the Content-Type (if data are sent) and determines the relevant data format.

To test the different services you may use the programs curl or wget. In the following chapter we will show some examples with curl.

Todo4teams restricts the access to the services by means of a IP-filter. This means that only clients with a certain known IP-address can access the relevant URLs. You can configure the list of the allowed client-systems with their IP-addresses by logging in as admin or superadmin into todo4teams. Please select the tab systems to configure the appropriate settings.

It is important during accessing the REST-URLs to use the adequate HTTP-method GET, POST, PUT or DELETE for each action (inquiry, generate, change, delete). In the examples the HTTP-method is submitted with the curl-command using the parameter X. The implementations of the REST-clients provide separate methods per HTTP method.

Generate new tickets with REST

To generate a new ticket with REST you have to send a HTTP POST-Request with the following content to the URL http://yourtodoserver/ToDoServer/rest/tasks:

This JSON-Code generates a new ticket with the title "First", the description "This is my first todo", a targeting time of 60 minutes to the group with the ID 17 and the owner with the ID 7. Furthermore a file with the name "attachment.txt" will be attached to the ticket.

As the result of the action the ID of the new ticket will be submitted.

You may test the service by saving the JSON-Code to the file "ticket.json" and execute the following command:

Please note that the content of the file (in the attribute "content") has to submitted as base64-coded.

The following example automatically adds forms to the ticket and sets a few field values. Please note that the form-IDs must correspond with the form templates of your system:

The targeting time will be displayed  corresponding to the changing of tickets via REST-call with the element minutes in minutes.

If you should prefer the XML-formate instead of JSON, please use the following example as a template to generate a ticket:

This example generates an supplemented file and attach it to the form.

For a further test you may use the following command that saves the XML-Code to the file "ticket.xml":

Retrieving the user- and group-list

You can make a search to the list of all users and groups of the todo4teams application with REST. Please use the URLs http://yourtodoserver/ToDoServer/rest/users or http://yourtodoserver/ToDoServer/rest/workgroups with the Accept-Type application/xml or application/json as in the following examples:

Retrieving the list of users

Retrieving the list of groups

Retrieving single tickets

You can get access to a single ticket by reading out the URL of the kind  http://yourtodoserver/ToDoServer/rest/tasks/<ticketid>, for example http://yourtodoserver/ToDoServer/rest/tasks/14515 with the GET-Request.

You can test this request also in the browser of your choice, the ticket will be displayed in HTML-formate.

In XML-formate this call may look like:

The result may look like this in XML-formate:

This loads a representation of the ticket that you can edit and submit as an update of the existing ticket to the server - shown in the next chapter.

Updating tickets

In order to update the status of a ticket on the server, you cand send the modified XML- or JSON-representation via PUT-Request to the URL of the ticket, ie  http://yourtodoserver/ToDoServer/rest/tasks/14515. Please note that you have to use the corresponding content-type as in the following examples:

Update of the ticket 14519 with the ticket.json saved as JSON-formate:

Update of the ticket 14519 with the ticket.xml saved as XML-formate:

Please note:

• To change the targeting time of a ticket, please use the element minutes. A change of the elements creationDate, startDate, endDate and scheduledEndDate will not be submitted.
  
• You can only edit tickets that are not yet finished.
  
• Forms and attachments will be exactly submitted as you have sent via REST: If you delete an attachment in the REST-representation and want to update the ticket, the attachment will be deleted from the ticket on the server. The same is also valid for forms.

Deleting of tickets via REST-call

You can delete tickets with a HTTP-DELETE-request to the URL of the tickets, for example:

Searching tickets - archive search via REST

There is a possibility to perform a flexible search for certain tickets by sending a request to the URL http://localhost:8080/ToDoServer/rest/query?q=...

As result you will receive a list of all ticket-representation as JSON- or XML-files.

The HTTP-parameter q contains the the search pattern by matters of a SQL-where-expresssion. Please note that you have to use this parameter in an URL-coded manner.

If ie you want to search a ticket that contains the word "Meier" and it's ID should be bigger than 14,000, the query may look like: task.id>14000 and task.title like '%Meier%'

URL-coded this will be equivalent to the parameter q with the values task.id%3E14000+and+task.title+like+%27%25Meier%25%27 and the following query:

With help of the optional parameter limit you can define the maximum amount of hits. The parameter withAttachments=true can suppress the attachment-elements. The use of this parameter withAttachments=true is especially convenient if you make an inquiry of a large number of tickets. Otherwise it is possible that the amount of submitted data will exceed several hunderts megabytes.