WSDL/SOAP interface
About this Document
This document is aimed at developers. It explains the WSDL/SOAP interface to Alcea. Using the calls defined in this document, a developer can quickly query, create and update issues within the Alcea system.
This document assumes some familiarity with XML and SOAP. You should also be at lease somewhat familiar with Alcea, and the data stored within.
Setting up Perl/SOAP-Lite on Windows…
Note that Perl and SOAP-Lite are not required, but this is what is used in the below examples in order to demonstrate the various SOAP calls used to interact with Alcea.
- Download and install Perl from ActiveState
- Download and install nmake (make utility) from Microsoft
- Download and install SOAPLite (There is also a ton of SOAP documentation here!)
- Download and install URI Perl module. Other perl modules are recommended on the SOAPLite page, but no other modules are required for communicating with Alcea.
Configure Alcea to enable SOAP Interface
Navigate to Admin Menu->Advanced->SOAP Functions, check the “Enable SOAP” checkbox and then click the Submit button.
WSDL Explained
WSDL: WSDL stands for Web Service Description Language, and it defines all of the web service requests and responses that can be made to Alcea. There are four basic opertions that can be performed through the web interface:
| Request Name | Description | Read/Write |
|---|---|---|
| GetId | This call returns the full details for a single specific issue, given the issue’s ID number. It is the equivalent of viewing an issue’s details through the web interface. | Read-only |
| GetBugList | This call allows the caller to define parameters through which a set of issues will be returned. It is the equivalent of the Filter screen in the web interface. | Read-only |
| NewBug | This call is used to create a new issue. | Write |
| UpdateBug | This call is used to update an existing issue. | Write |
Before executing any examples in this document, or using any SOAP functionality, you must enable SOAP within Alcea (it is disabled by default). To do this, navigate to Admin Menu->Advanced->SOAP Functions, check the “Enable SOAP” checkbox and then click the Submit button.
NOTE: Alcea will dynamically generate a custom .wsdl file based on how your instance of Alcea is configured (ie. if you have custom fields, they will be added to your wsdl file. All of our examples in this document assume the default Alcea installation. You can view the .wsdl file by going to Admin Menu->Advanced->SOAP Functions and clicking the “Generate WSDL File” button.
General Conventions
Field names within Alcea are prefixed with “m”, and “camelcase” is used for field naming conventions (capitalize the beginning of each word). Example: the Id field is mId, the Date Last Modified field is mDateLastModified. The full field list is available in the WSDL file.
All of the examples provided are using Perl and SOAP::Lite (a Perl module). We are using this for our examples because Perl and SOAP::Lite are available for just about every operating system, and they are free. While we are using Perl, most modern programming languages have web service modules / libraries that should work fine with Alcea. Customers with any questions about compatibility and/or would like examples for platforms can email support@alceatech.com for additional information.
getId
Description
This function is similar to viewing an issue in the web interface, and returns all details for a single, specific issue.
Sample Perl Code
The following Perl code retrieves the details of Issue 10 from the system. We turn full debug on to display both the raw data that we send to Alcea as well as the raw data received in response.
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
$response = SOAP::Lite
-> uri('https://alceatech.com:10000/Fit.wsdl')
-> proxy('https://alceatech.com:10000/Fit.wsdl')
-> getId(SOAP::Data->name("mId")->value("10")->type("string"));
$bug = $response->valueof('//getIdResponse/bugStruct');
print "nReturned Issue " . $bug->{mUniqueProjectId};
print " - " . $bug->{mSubject};
Input
We can see that the following SOAP message is sent to Alcea:
POST https://alceatech.com:10000 Accept: text/xml Accept: multipart/* Content-Length: 448 Content-Type: text/xml; charset=utf-8 SOAPAction: "https://alceatech.com:10000/getId" <?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <SOAP-ENV:Body> <getId xmlns=""> <mId xsi:type="xsd:int">10</mId> </getId> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Output
The details of the issue are returned. The contents are contained in a bugStruct element, which in turn contains all of the current (non-history) fields, plus bugEntry structures for each update to the issue. Each bugEntry contains the values that were provided in those updates.
Sample output from the perl call:
HTTP/1.1 200 OK
Content-Length: 1919
Content-Type: text/xml; charset=utf-8
Client-Date: Tue, 21 Oct 2003 02:38:11 GMT
Client-Peer: 127.0.0.1:10000
Client-Response-Num: 1
<?xml version="1.0"?>
<SOAP-ENV:Envelope
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<getIdResponse>
<bugStruct>
<mId>10</mId>
<mSubject>performance @ Aktiom ... Server timing ...</mSubject>
<mDateEntered>Tue Sep 16 00:13:23 EDT 2003</mDateEntered>
<mCurrentStatus>Closed</mCurrentStatus>
<mCurrentAssignedTo>cjustus</mCurrentAssignedTo>
<mLastModifiedBy>cjustus</mLastModifiedBy>
<mDateLastModified>Mon Sep 22 21:55:12 EDT 2003</mDateLastModified>
<mEnteredBy>cjustus</mEnteredBy>
<mPriority>3</mPriority>
<mProject>Aktiom</mProject>
<mArea>area</mArea>
<mVersion></mVersion>
<mEnvironment></mEnvironment>
<mParent>0</mParent>
<mRequestedDueDate>null</mRequestedDueDate>
<mActualCompletionDate>null</mActualCompletionDate>
<mEstimatedHours>0.0</mEstimatedHours>
<mActualHours>0.0</mActualHours>
<mPercentComplete>0.0</mPercentComplete>
<bugHistory>
<bugEntry>
<mAssignedTo>cjustus</mAssignedTo>
<mWho>cjustus</mWho>
<mStatus>Open</mStatus>
<mWhen>Tue Sep 16 00:13:23 EDT 2003</mWhen>
<mDescription></mDescription>
</bugEntry>
<bugEntry>
<mAssignedTo>cjustus</mAssignedTo>
<mWho>cjustus</mWho>
<mStatus>Closed</mStatus>
<mWhen>Mon Sep 22 21:55:12 EDT 2003</mWhen>
<mDescription>istop issue...</mDescription>
</bugEntry>
</bugHistory>
</bugStruct>
</getIdResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Returned Issue 10 - performance @ Aktiom ... Server timing ...
getBugList
Description
This function is the SOAP call equivalent to running a filter. Critera submitted via the SOAP call will return a filtered list of issues.
Sample Perl Code
The following Perl code shows how to enter filter criteria with SOAP. Take note of the method in which custom fields are entered. The custom field ID numbers can be found on the Admin Menu->Field Layout->Custom Field page.
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
$elem = SOAP::Data->name("filterStructIn" => SOAP::Data->value(
SOAP::Data->name("mPriority" => "1"),
SOAP::Data->name("mPriorityOp" => "="),
SOAP::Data->name("mPriorityAndOr" => "OR"),
SOAP::Data->name("mPriority2" => "2"),
SOAP::Data->name("mPriority2Op" => "="),
SOAP::Data->name("filterCustomField" =>
SOAP::Data->value(SOAP::Data->name("Id" => "5"),
SOAP::Data->name("Op" => ">="),
SOAP::Data->name("Value" => "2005/05/5"),
SOAP::Data->name("AndOr" => "and"),
SOAP::Data->name("Op2" => "<="),
SOAP::Data->name("Value2" => "2005/05/15"))
))
);
$elem->type("tns:FilterStructIn");
my $soap = SOAP::Lite ->uri("https://alceatech.com:10000/") ->proxy("https://alceatech.com:10000/Alcea.wsdl");
$response = $soap->call("getBugList" => $elem);
for my $bug ($response->valueof('//getBugListResponse/bugStructList/bugStruct')) {
print "nReturned Issue " . $bug->{mId};
print " - " . $bug->{mSubject};
}
Input
We can see that the following SOAP message is sent to Alcea:
POST https://alceatech.com:10000 Accept: text/xml Accept: multipart/* Content-Length: 766 Content-Type: text/xml; charset=utf-8 SOAPAction: "https://alceatech.com:10000/newBug" <?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <SOAP-ENV:Body> <getBugList xmlns=""> <mPriority xsi:type="xsd:int">1</mPriority> <mPriorityOp xsi:type="xsd:string">=</mPriorityOp> <mPriorityAndOr xsi:type="xsd:string">OR</mPriorityAndOr> <mPriority2 xsi:type="xsd:int">2</mPriority2> <mPriority2Op xsi:type="xsd:string">=</mPriority2Op> <filterCustomFields> <filterCustomField> <Id xsi:type="xsd:int">5</Id> <Op xsi:type="xsd:string">>=</Op> <Value xsi:type="xsd:string">2005/05/5</Value> <AndOr xsi:type="xsd:string">and</AndOr> <Op2 xsi:type="xsd:string"><=</Op2> <Value2 xsi:type="xsd:string">2005/05/15</Value2> </filterCustomField> </filterCustomFields> </getBugList> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Output
A list of filtered issues are returned. The results are a set of bugStruct elements contained in a bugList element.
Sample output from the perl call:
HTTP/1.1 200 OK
Content-Length: 1919
Content-Type: text/xml; charset=utf-8
Client-Date: Tue, 21 Oct 2003 02:38:11 GMT
Client-Peer: 127.0.0.1:10000
Client-Response-Num: 1
<?xml version="1.0"?>
<SOAP-ENV:Envelope
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<getBugListResponse>
<bugList>
<bugStruct>
<mId>13</mId>
<mSubject>test</mSubject>
<mCurrentAssignedTo>birdman</mCurrentAssignedTo>
<mDateLastModified>Fri May 13 16:10:00 EDT 2005</mDateLastModified>
<mCurrentStatus>Open</mCurrentStatus>
<mPriority>1</mPriority>
<mDateEntered>Fri May 13 16:10:00 EDT 2005</mDateEntered>
<mEnteredBy>jsimpson</mEnteredBy>
<mProject>SYSTEM</mProject>
<mArea></mArea>
<mVersion></mVersion>
<mEnvironment></mEnvironment>
<mRequestedDueDate></mRequestedDueDate>
<mActualCompletionDate></mActualCompletionDate>
<mEstimatedHours>0.0</mEstimatedHours>
<mActualHours>0.0</mActualHours>
<mPercentComplete>0.0</mPercentComplete>
<mParent>0</mParent>
<mLastModifiedBy>jsimpson</mLastModifiedBy>
<mElapsedTime>0</mElapsedTime>
<mNotifyList></mNotifyList>
<mRejectedCount>0</mRejectedCount>
<mRankCache>0.0</mRankCache>
<bugHistory>
<bugEntry>
<mAssignedTo>birdman</mAssignedTo>
<mWho>jsimpson</mWho>
<mStatus>Open</mStatus>
<mWhen>Fri May 13 16:10:00 EDT 2005</mWhen>
<mDescription>Test issue</mDescription>
</bugEntry>
</bugHistory>
</bugStruct>
</bugList>
</getBugListResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Returned Issue 13 - test
newBug
Description
This function mirrors the functionality of the New Issue screen. A new issue will be created using the data from any field values submitted via the SOAP call. The new issue’s ID is returned.
Sample Perl Code
The following Perl code shows how to enter a new issue with SOAP. Fields that are not included will be set to empty in the newly created issue. Take note of the method in which custom fields are entered. The custom field ID numbers can be found on the Admin Menu->Field Layout->Custom Field page.
#!/usr/bin/perl
use SOAP::Lite +trace => 'debug';
$elem = SOAP::Data->name("bugStruct" => SOAP::Data->value(
SOAP::Data->name("mSubject" => "Testing SOAP: newBug call"),
SOAP::Data->name("mDescription" => "This will enter a new issue into the system."),
SOAP::Data->name("mAssignedTo" => "admin"),
SOAP::Data->name("customField" =>
SOAP::Data->value(SOAP::Data->name("Id" => "3"),
SOAP::Data->name("Value" => "SOAP UPDATE"))
),
SOAP::Data->name("customField" =>
SOAP::Data->value(SOAP::Data->name("Id" => "4"),
SOAP::Data->name("Value" => "SOAP UPDATE"))
))
);
$elem->type("tns:BugStruct");
my $soap = SOAP::Lite ->uri("https://alceatech.com:10000/") ->proxy("https://alceatech.com:10000/Alcea.wsdl");
$response = $soap->call("newBug" => $elem,
SOAP::Data->name("loginid" => "jsimpson"),
SOAP::Data->name("password" => "myPassword"));
print $response->valueof('//newBugResponse/message');
Input
We can see that the following SOAP message is sent to Alcea:
POST https://alceatech.com:10000 Accept: text/xml Accept: multipart/* Content-Length: 766 Content-Type: text/xml; charset=utf-8 SOAPAction: "https://alceatech.com:10000/newBug" <?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <SOAP-ENV:Body> <newBug xmlns=""> <mSubject xsi:type="xsd:string">Testing SOAP: newBug call</mSubject> <mDescription xsi:type="xsd:string"> This will enter a new issue into the system.</mDescription> <mAssignedTo xsi:type="xsd:string">admin</mAssignedTo> <customFields> <customField> <Id xsi:type="xsd:int">3</Id> <Value xsi:type="xsd:string">SOAP UPDATE</Value> </customField> <customField> <Id xsi:type="xsd:int">4</Id> <Value xsi:type="xsd:string">SOAP UPDATE</Value> </customField> </customFields> </newBug> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Output
The new issue’s ID is returned in a message element.
Sample output from the perl call:
HTTP/1.1 200 OK Content-Length: 1919 Content-Type: text/xml; charset=utf-8 Client-Date: Tue, 21 Oct 2003 02:38:11 GMT Client-Peer: 127.0.0.1:10000 Client-Response-Num: 1 <?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <SOAP-ENV:Body> <newBugResponse> <message>Issue 13 has been created.</message> </newBugResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>= Issue 13 has been created.
updateBug
Description
This function works the same as the newBug call. In addition to other fields, the mId field is set to the ID of the issue that will be updated. Fields that are not set in the SOAP call will remain unchanged.
