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 |