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

Resource path /Issues
Accepted HTTP methods OPTIONS*, POST

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

POST summary

HTTP method POST
Request media type application/x-www-form-urlencoded
Request format HTML form-encoded key-value pairs
Successful response code 201
Authentication method Basic HTTP Authentication

POST data

Name Description Required Can Be Empty Maximum Length (Characters)
IssueTopicName The name of an existing topic to which the new issue will belong. All issues must have a topic. The value is case-sensitive. yes no 128
Summary A short description of the issue. yes no 255
IssueTopicVersion The name of an existing subtopic or topic version. This will be the value of the Reported in field of the new issue. The value is case-sensitive. no no 32
IssueTopicBuild The build number that will be used for the issue’s Reported in Build field. no yes 32
IssueType The name of an existing issue type. This value is one of the named issue types specified in your Ketura system. The value is case-sensitive. yes no 64
IssueSeverity The name of an existing issue severity. This value is one of the named severities specified in your Ketura system. The value is case-sensitive. yes no 64
Description A full description of the issue. yes yes 15728640
MilestoneName The name of an existing milestone to which the issue will be added instead of the default milestone specified by the workflow configured in Ketura. The value is case-sensitive. no no 100
ProjectName The name of the project to which the milestone above belongs. This must specified if the milestone name is specified. The value is case-sensitive. no no 100

POST response

Response Code(s) Significant Response Headers Response Response MIME Type
201 Location, contains the URI with new issue. e.g. http://localhost:9453/Ketura/API/Issues/1001 for a new issue that has been given the id I1001. None n/a
401, 500 and greater None Text containing java stack trace text/plain
Others None HTML error page text/html