Forums/Documentation
Web Services, API & Schema
Kris Stephen
posted this on August 25, 2010 11:34 am
Looking for additional information on Web Services and how to get started? Hopefully you'll find what you need here to get started. If not, leave a comment, and let us know.
Web Services API:
Latest version: http://www.jamasoftware.com/api/ws/latest/
Specify version to access older versions: http://www.jamasoftware.com/api/ws/v2/
Database Schema:
Latest version: http://www.jamasoftware.com/schema/
Specify version to access older versions: http://www.jamasoftware.com/schema[version]
- Available versions: 2.97 ; 2.9.9 ; 3.0.4 ; 3.1.x ; 3.3.2
- Example: http://www.jamasoftware.com/schema2.9.9/
Steps to Start Using Web Services
- Convert the WSDL published by your Contour installation into your preferred language. If you want to develop web services in Java, you need to convert the WSDL to java code. We use 'ant' and 'apache-cxf' to accomplish this. There are tools available for other languages as well. (Our default ant build.xml file is attached).
- What is a WSDL: it defines the language and functions available to be called against a web application ie it defines the language for performing Web Services calls.
- Understand the Web Services API and how to structure your function calls, building correct calls and understanding what they return. Reference the API posted above.
- A quick way to figure out how to structure web services requests, how to build function calls appropriately is to use SoapUI and the Web Services API in combination. SoapUI is a nifty tool which enables you connect and build example web services queries very quickly and I would highly recommend using this to become familiar with how to use our web services.
- Start developing!
Please feel free to leave examples as a comments below!
See WsTest_Adding_a_Filter.java for an example of creating a filter via WS and getting the items from Contour.
Custom Reporting (Velocity) API: - unrelated to Web Services
Comments
Thanks for the examples how to use the API.
We're still using v2 of the web API, with v2.9.9 of Contour. The link to the 'latest' is showing 'page not found' and once working only offers v3 of the API. How can we view the v2 API?
Thanks,
Mike
I updated the original post to include how to access older web services APIs. v2: http://www.jamasoftware.com/api/ws/v2/
Thank you... still need to fix the first link. It is pointing to .../latest/.../v2/...html, which is no longer a valid address... probably should be http://www.jamasoftware.com/api/ws/latest/index.html?com/jamasoftware/contour/ws/v3/ContourSoapService.html? (replace the .../v2/... with .../v3/...)
Another good catch. Thanks Mike (fixed)
Similar question as before... is it possible to access the prior version (e.g. 2.9 version) of the schema?
Thanks,
Mike
Mike - I updated the original post with an example. http://jamasoftware.com/schema2.9.9/ etc.
Cheers!
(1) Could you please update the database schema to current version 3.1.3? E.g. there is no information about "documentnode" in the table overview.
(1) - The schema should be up to date. Documentnode doesn't seem to display on the tables page but you can directly link to it: http://www.jamasoftware.com/schema/tables/documentnode.html
(2) We have some major issues adapting our BIRT reports to the new database scheme. Is there any more information regarding the new scheme concept?
(2) - I'm assuming you've upgraded from a 2.9 environment to 3.x. The biggest change between these is a new concept of hierarchy. In 2.9, tree location was managed entirely in the document table. Although all of these entries/columns in the database still exist in 3.x they are no longer used. All information regarding the hierarchy or location of an item in the tree is managed in the documentNode table now. Note that there are different types of trees such as the Explorer tree or the Baseline tree etc.
Hello,
How could I to create a WsAuth object in php or python? Or how should look like a proper outgoing and incoming SOAP envelope with sample method (ie. getVersion)?
Hi Thomasz,
The Contour SOAP service provides a WSDL file which contains a reference to the available calls you can make against the service. There are a vast number of tools you can find on the web which are strictly used to transform the WSDL references into language code. For instance, in the attached Word document of the original post, we demonstrated using the "apache-cxf" tool to generate Java code from the WSDL file but if you want to use PHP or Python you will need to find (or build your own) a tool to do so. I'd recommending searching "WSDL to Python" or "WSDL to PHP" and I'm sure you'll find a few out there.
Once you've generated the language code you don't have to worry about creating a SOAP envelope etc.
Hi, I have a question concerning 2.9.7. Is it possible to store fields of type "Multi" via the ws api? Thanks, Matthias
Multifields are stored as an array under wsLookup.
Is there a way to access tags through the API that I am not seeing?
Tags are not accessible through API at this time.
anyone know api call for add URL for record?
OK - I am now officially confused. I finally did figure out how to update field values using the field.values method/property. This works fine for string and int field types.
Now we come to the wsLookup (pick list) item type. This type's field.values references the wsLookupType (pick list field) ID instead of the actual wsLookup (pick list item) ID value. I can iterate through the picklist values and determine their IDs - no problem. But how do I update the wsField object since it references the wsLookupType object, not the wsLookup object?
foreach (wsField field in item.fields)
{
string[] values = field.values;
if (field.label == fieldName)
{
switch (field.type)
{
case "Lookup":
wsLookupType lookupType = new wsLookupType();
int typeId = 0;
string lookupName = null;
foreach (string val in values)
{
lookupType.id = long.Parse(val);
typeId = Convert.ToInt32(val);
}
wsLookup[] lookups = null;
lookups = css.getLookupsFromType(auth, typeId, true);
foreach (wsLookup lookup in lookups)
{
if (lookup.name == value)
{
css.updateLookup(auth, lookup);
lookupName = lookup.name;
LogFileWriteLine(lookupName);
}
}
//string[] sListItem = new string[] { lookupName };
//field.displays = sListItem;
break;
} // switch
} //if
} //foreach
Any and all comments welcome. You may even comment on my poor programming skillz :)
Thanks - Rich
Is there any way to authenticate using an api token instead of a username and password?
Our token is built off of username and password authentication. Unfortunately we do not have a call for "login", which would provide the token you are looking for, it is just built into the call itself.
For Richard and anyone else, this is some pesudo code from Dylan concerning lookup fields:
//Initial variables: What item you want to modify, what value you want to set, and what field you want to set it on
int itemId = 1234;
string lookupToSetStringValue = "Approved";
string fieldName = "status";
//Getting the item from Contour
wsItem item = css.getItem(auth, itemId);
//Getting the associated document type from Contour
wsDocumentType docType = css.getDocumentType(auth, item.documentTypeId);
//Determining what lookup type we are dealing with
//When you get the wsDocumentType, the wsField object that represents the lookup field
// has the lookup type ID in it's value array
int lookupTypeId;
foreach(wsField field in docType.fields) {
if(field.type == "Lookup" and field.name == fieldName) {
lookupTypeId = field.values[0];
break;
}
}
//Getting the ID associated with the lookup string value we want to set
int lookupToSetId;
wsLookup[] availableLookups = css.getLookupsFromType(auth, lookupTypeId);
foreach(wsLookup lookup in availableLookups) {
if(lookup.name == lookupToSetStringValue) {
lookupToSetId = lookup.id;
break;
}
}
//Setting the field's value to the lookup ID on the wsItem object
foreach(wsField field : item.fields){
if(field.name == fieldName) {
field.values = new string[] { lookupToSetId};
}
}
//Updating the item with the new lookup value in Contour
wsItem result = css.updateItem(auth, item);
@rciorba Our token is built off of username and password authentication. Unfortunately we do not have a call for "login", which would provide the token you are looking for, it is just built into the call itself.
Thanks for your prompt answer!
Are there any examples of how update/add steps to a testcase via the api? I've tried fetching the testcase, altering the displays for the Steps wsField and calling updateItem/updateItemValues on that. I get 200 OK for both updateItem and updateItemValues but nothing gets updated.
"Cannot add/update a Test Cycle through Web Services"
It seems i can't create test plans, test cycles or test executions trough the soap api. Is this correct? We were relying on this in order to import some older data while transitioning from a different tool.