Introduction

Create tickets using REST calls

Retrieve tickets using REST

Update tickets

Delete tickets

Retrieve lists of users and workgroups

Query tickets

Introduction

todo4teams offers a set of RESTful webservices. REST stands for Representational State Transfer, see here for an introduction.

This interface allows external applications to retrieve, search, create, modify and delete 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 an IP-filter and/or HTTP Basic Authentication . IP filtering 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.

When accessing the REST-URLs It is important 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.

Please note that you can't update the tickets' state (open, locked, finished,...)! All calls will update the tickets' data without effecting the tickets' workflow.

Generate new tickets using REST

To generate a new ticket with REST you have to send a HTTP POST-Request with the following content to the URL https://<yourtodoserver>/todo4teams/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.

Set ownerId to 0 or omit this attribute to not set the ticket's owner on creation.

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

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

or if your installation requires authentication (e.g. with user 'apiuser' and password 'supersecret':

Please note that the content of the file (in the attribute "content") has to submitted as an array of byte values .

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 scheduled  end time will be set  according to the attribute 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":

Note that we changed the content type to application/xml. The service will return something like this:

Retrieving single tickets

You can get access to a single ticket by reading out the URL of the kind  https://yourtodoserver/todo4teams/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 as HTML.

Requesting JSON format ...

the result might look like this:

In XML-formate this call may look like:

The result may look like this in XML-formate:

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, e.g.  https://yourtodoserver/todo4teams/rest/tasks/22217. Please note that you have to use the corresponding content-type as in the following examples:

This is the JSON data to be send. We will save it to a file named ticket.json.

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

Update of the ticket 22217 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 are allowed to update tickets in all states (open, locked, finished,...). Preferably update tickets while in state 'open'. Use the GET method (see above) to check a ticket's state before updating!
• 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.
• Omit the attributes ownerId and addressedGroupId (or assign 0) if you don't want to change these values.

Deleting tickets

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

Searching tickets via REST calls

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.

So if  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: t.id>14000 and t.title like '%Meier%'

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

Use the alias 't' for the ticket object, e.g. t.id for the id attribute or t.title for the title.

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.

A query result in JSON format might look like this:

 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