Create/Import an Issue

A new issue can be created simply by sending Ketura an HTTP POST request containing the details of the issue. Once an issue has been created, you can use other Ketura web service APIs to add tasks and attachments to the issue. These capabilities could be used, for example, from a script that imported issues from another system. Another use would be to add issues automatically to Ketura when someone completes a form on an intranet or public website.

Python 2 example of creating/importing an issue

The following example is a Python script that will send a request to a local Ketura server to create an issue.

This example uses the free httplib2 library, which is not included as standard in most Python distributions. The httplib2 library can be download from the httplib2 website, which also has installation instructions.

#!/usr/bin/python2.5
# createIssueExample.py

# Araxis Ketura API Script Example.
# Copyright (c) 2009 Araxis Ltd. All rights reserved.
#
# Redistribution and use of this example code, with or without modification, are hereby permitted.

# import required classes from modules
from httplib2 import Http
from urllib import urlencode

# start HTTP client
client = Http()

# add user name and password credentials
client.add_credentials('es', 'pw')

# declare information to be used on request
url = "http://localhost:9453/Ketura/API/Issues"
headers = {'Content-type': 'application/x-www-form-urlencoded; charset=UTF-8'}
data = {'IssueTopicName' : 'Asset Tracking System',
        'Summary' : 'Documentation should be translated into Spanish',
        'IssueType' : 'Documentation',
        'IssueSeverity' : 'Minor',
        'Description' : 'Customer has requested that documentation should be translated into Spanish.'}

# send request
(resp_headers, content) = client.request(url, "POST", body=urlencode(data), headers=headers)

[Download This Example | Download Complete Example]

In the script above, the httplib2 library is used to create an Http object. This object acts as the client that will make the request.

Ketura’s web service authenticates users by using the Basic Authentication Scheme of HTTP. The script adds the user name and password to the Authorization header of the request that will be sent. The user name and password must only contain characters from the ASCII character set (not including the ASCII colon character ‘:’) and must not be zero length. This must be taken into account when selecting a user account to use with the API.

The request is sent to the Ketura server at the URL specified in the script. The key-value pairs of the data are encoded before they are sent. The request is sent with a header Content-type: application/x-www-form-urlencoded to inform server that the data is encoded using standard HTML form encoding.

The response received from the server consists of the response headers and the content (entity) of the response.

If the request to create an issue succeeds, the content of the response will be empty and the response header Location will contain a URL of the new issue. The example above might therefore return a Location header set to http://localhost:9453/Ketura/API/Issues/1001 for a new issue that has been given the id I1001.

If the request fails, the Location header is not returned, but the content of the response will contain details of the error.

Workflow configured for the specifed topic will be followed when creating an issue. The issue will be added to the appropriate default milestone, if one has been configured for the topic. Any tasks that have been configured to be added to an issue for its initial state will be added.

If it is desired that workflow should not be applied when creating an issue (perhaps when importing issues), remove the workflow configured for the topic within which the issue will be created.

Reference

* Sending an OPTIONS request will generate a response containing a WADL document. This document describes the services available from this resource path.

POST summary

POST data

POST response