The REstful API is a set of programmable HTTP calls. These calls operate on the ExtraView application to return data and metadata to the calling program or to update items within the ExtraView database.
ADD_ATTACHMENT | uploads a file attachment to the ExtraView database |
ADD_FIELD_LIST | provides an ordered list of fields that are used to insert records |
ADD_USER_TO_GROUP | adds an existing user to a user group |
ALLOWED_LIST | gives the list of allowed values for a key |
CUSTOM | invokes a call within the CLI user exit in the UserCustom java class |
DEBUG | alters the debug level of messages sent to the application server log |
DELETE | deletes existing issue(s) from the database |
DELETE_USER | deletes an existing user |
EDIT_FIELD_LIST | provides an ordered list of fields that are used for update |
FIELDS | displays a list of available fields and their screen names |
FILL_IN | uses a template and fills in the values with the parameters provided |
GET | retrieves a single record from the database |
GET_APP_DEFAULT | retrieve an ExtraView behavior setting (deprecated) |
GET_AREAS | retrieves a list of the areas in use from the database |
GET_ATTACHMENT | downloads a copy of a file from an issue attachment |
GET_BEHAVIOR_SETTING | retrieve an ExtraView behavior setting (supercedes GET_APP_DEFAULT) |
GET_FIELDS | download a specific field or fields from an existing issue |
GET_HEARTBEAT | return a status indicator to show that ExtraView is alive |
GET_LOG | returns the contents of the application server log |
GET_PROJECTS | retrieves a list of projects for a given area from the database |
GET_REPORTS | retrieves a list of the reports currently available to the user |
GET_ROLES | retrieves the available roles for a specified user from the database |
GET_TITLE | retrieve data dictionary information on a field |
GET_TOKEN | retrieves an authentication token |
GET_USERS | retrieve a list of user names from the database |
GET_VALID_META_DATA | retrieve the metadata for an issue |
HISTORY | retrieve all records from a specified point in time |
IMPORT_ALLOWED_VALUES | import allowed values from a file into ExtraView |
INSERT | inserts new records into the ExtraView database |
INSERT_USER | create a new user account |
INSERT_XML | inserts a new record into ExtraView from XML formatted input data |
ITEM_EXISTS | checks whether an issue exists in the database |
LIST_ATTACHMENT | retrieves a list of file attachments against a single issue |
RUN_REPORT | runs a report that has been defined within ExtraView |
SEARCH | provides a general search and retrieval mechanism |
SEARCH_FIELD_LIST | provides a list of fields that can be searched for |
SET_AREA_PROJ | sets the working area and project |
SET_ROLE | sets the working role of the user |
UPDATE | updates existing records in the ExtraView database |
UPDATE_USER_PASSWORD | updates a user’s password |
USER_FIELD_LIST | displays an ordered list of fields for the user record |
USER_GROUP_LIST | displays a list of user roles ordered by the user role title |
VERSION | returns the version number and build number of ExtraView |
All API commands require authentication. This can take one of three forms:
get_token
command. This call must include a valid User ID and password, but subsequent calls may use the token. This is more secure than the first form, as the password is only passed on the first access, until the token used in the subsequent calls expires. This is the most secure form of accessThe setting ALLOW_ANONYMOUS_API_ACCESS. allows anonymous access to ExtraView. Most commonly, this is used to provide a web page that you have designed to perform transactions, or to query the ExtraView database, not to need a hard-coded username and password. To preserve a secure environment, it is necessary to perform the following steps to set up anonymous access:
Once you have set up anonymous access, the parameters named user_id and password in all API commands become optional. If they are provided, they must be valid combinations of user names and passwords.
To create an API call, the user creates an HTTP request (HTTPRequest object) and submits this to the server. This request can be composed within virtually any computer language. Each HTTP request is composed of the following parts:
If you are creating your own HTTPRequest object from a programming environment to call the ExtraView API, then you must also set the standard parts of the HTTPRequest object, such as the USER_AGENT. There will most probably be standard libraries for your environment to assist in doing this.
Much of the data returned by an API call is in XML format. This has some significance to the user of the API, in that Extraview's XML data may embed your own XML within its results. To accommodate this, ExtraView uses Base64 encoding whenever it sees XML data returned from the application to ensure that the XML returned by API commands through the API must be well-formed. This means that the contents of a CDATA string must not contain the character string "]]>", because that is the end sentinel for a CDATA section. So, if the original data contains this string, there must be some way to escape the data. For easy recognition of an escaped CDATA string, ExtraView prepend the characters %25S to the front of the string. These characters are merely a sentinel and are not part of the output string. The encoding used for the rest of the CDATA string is called Base64, and algorithms for encoding/decoding are widely available. Furthermore, ExtraView ensures that the %25S sentinel string does not appear in the CDATA raw character string by encoding any CDATA raw character string to Base64 as well. It is the responsibility of the receiver, therefore, to test each CDATA section for the sentinel characters %25S at the beginning of the CDATA, and, if present, perform the Base64 decode function on the remainder of the character data to get the raw character values in the field.
Server-side templates can be defined for many API commands. These templates allow you to control the presentation of the output from the API command. Most commonly this is used to allow the administrator to integrate ExtraView with their company’s own web site. For example, a page within your company’s web site can perform a search of the ExtraView database and return the results formatted with the same look and feel as the web site.
Templates allow you to use “tags” that are substituted at runtime, with the actual value in a record. For example, the tag __STATUS__ refers to the value of the STATUS field of the current record. Tags are available for most fields in the data dictionary. In addition, if you place a data dictionary field on a template, it must exist on the Detailed Report layout inherited by the specific Business Area and Project. The user must also have read permission to the field.
See this page for full details of server-side templates.
Output from ExtraView using repeating rows can be turned off, to simplify the XML returned from a command. To use repeating rows within the API, you must set the behavior setting named MULTI_RELEASE_XML to a value of YES within the administration section.
The following API commands support repeating rows:
The commands that return XML will do so as shown in the following example:
<REPEATING_ROWS TITLE='Repeating Rows' REPEATING_ROWS='1'> <REPEATING_ROW REPEATING_ROW_ID='1073779532'> <FRED_RR TITLE='Repeating row fred'> <![CDATA[a new fredrr]]> </FRED_RR> <RELEASE_CHILD_STATUS TITLE='Branch Status'> <![CDATA[Assigned]]> </RELEASE_CHILD_STATUS> <RELEASE_REQUESTED_RELEASE TITLE='Requested Release'> <![CDATA[4.0.3.14]]> </RELEASE_REQUESTED_RELEASE> <RELEASE_COMMITTED_RELEASE TITLE='Committed Release'> <![CDATA[4.0.3.14]]> </RELEASE_COMMITTED_RELEASE> </REPEATING_ROW> <REPEATING_ROW REPEATING_ROW_ID='1073779542'> <FRED_RR TITLE='Repeating row fred'> <![CDATA[a new fredrr2]]> </FRED_RR> <RELEASE_CHILD_STATUS TITLE='Branch Status'> <![CDATA[Assigned]]> </RELEASE_CHILD_STATUS> <RELEASE_REQUESTED_RELEASE TITLE='Requested Release'> <![CDATA[4.0.3.13]]> </RELEASE_REQUESTED_RELEASE> <RELEASE_COMMITTED_RELEASE TITLE='Committed Release'> <![CDATA[4.0.3.13]]> </RELEASE_COMMITTED_RELEASE> </REPEATING_ROW> <REPEATING_ROW REPEATING_ROW_ID='1073779552'> <FRED_RR TITLE='Repeating row fred'> <![CDATA[a new fredrr3]]> </FRED_RR> <RELEASE_CHILD_STATUS TITLE='Branch Status'> <![CDATA[Assigned]]> </RELEASE_CHILD_STATUS> <RELEASE_REQUESTED_RELEASE TITLE='Requested Release'> <![CDATA[4.2.2.7]]> </RELEASE_REQUESTED_RELEASE> <RELEASE_COMMITTED_RELEASE TITLE='Committed Release'> <![CDATA[4.2.2.8]]> </RELEASE_COMMITTED_RELEASE> </REPEATING_ROW> </REPEATING_ROWS> |
The data structures here are:
<REPEATING_ROWS TITLE=’Repeating Rows’ REPEATING_ROWS='1'> ... (repeating row elements) </REPEATING_ROWS>
<REPEATING_ROW REPEATING_ROW_ID='nnnnnnn'> ... (repeating row field elements) </REPEATING_ROW>
<fieldTag TITLE='fieldTitle'> <![CDATA[fieldData]]> </fieldTag>
where – fieldTag = data dictionary field name fieldTitle = title of the field fieldData = data contained in the field (in CDATA-encoded format)
Previous to release 4.2.2.8, the API did not handle repeating row records, therefore the previous format for for update of fields within an issue is maintained for backward compatibility. An extension is made to allow for the insertion or the update of one or more specific repeating row fields as follows.
To update an existing repeating row field, there must be a parameter named PROBLEM_RELEASE_ID in the update parameter set. This parameter may have multiple values, each one specifying a specific repeating row ID (i.e. the ITEM_ID of the repeating row within the issue). The field values associated with these repeating rows are specified in a parallel set of parameters, named for the field name within the repeating row. Each such parameter may be given mutiple values, each of which maps to a repeating row as specified by the multiple values of PROBLEM_RELEASE_ID.
As an example, assume that there are 5 repeating rows in issue #100, numbered 201, 202, 203, 204, and 205.
Then with PROBLEM_RELEASE_ID set to the values (202, 204), the value of FRED_RR, a repeating row-resident field, might take on the values ("fred202", "fred204") in the input parameters.
Then, the repeating rows with the ID’s of 202 and 204 are updated with the value of FRED_RR being set to "fred202" and "fred204" respectively. No other repeating rows would be affected by the update.
Inserting repeating rows is similar to updating repeating rows, except no PROBLEM_RELEASE_ID is given as a parameter. When no PROBLEM_RELEASE_ID is present, ExtraView will insert the remaining fields as a new repeating ROW.
You can insert multiple repeating rows with a single API call. For example, the following parameter string will insert three repeating row records, each within a single field named FRED_RR:
&FRED_RR=val1&FRED_RR=val2&FRED_RR=val3
First, make sure you have set the behavior setting named MULTI_RELEASE_XML to YES. The following examples assume you have an ExtraView server located at http@//extraview.myserver.com/evj/ExtraView.
We will first retrieve issue number 26788 from ExtraView. This issue has existing repeating rows.
http@//extraview.myserver.com/evj/ExtraView/ev_api.action?user_id=myname&password=mypass&statevar=get&id=26788
ExtraView returns XML data that includes a section about Repeating Rows. The XML is shown indented here for clarity.
... ... ... <REPEATING_ROWS TITLE="Repeating Rows" REPEATING_ROWS="1"> <REPEATING_ROW REPEATING_ROW_ID="1073788412"> <RELEASE_SOURCE_CODE_BRANCH TITLE="Code Branch"> <![CDATA[ 4.3 ]]> </RELEASE_SOURCE_CODE_BRANCH> <RELEASE_CHILD_STATUS TITLE="Branch Status"> <![CDATA[ Assigned ]]> </RELEASE_CHILD_STATUS> <RELEASE_REQUESTED_RELEASE TITLE="Requested Release"> <![CDATA[ 4.3.1 ]]> </RELEASE_REQUESTED_RELEASE> <RELEASE_COMMITTED_RELEASE TITLE="Committed Release"> <![CDATA[ 4.3.1 ]]> </RELEASE_COMMITTED_RELEASE> </REPEATING_ROW> <REPEATING_ROW REPEATING_ROW_ID="1073791532"> <RELEASE_SOURCE_CODE_BRANCH TITLE="Code Branch"> <![CDATA[ 4.4 ]]> </RELEASE_SOURCE_CODE_BRANCH> <RELEASE_CHILD_STATUS TITLE="Branch Status"> <![CDATA[ Open ]]> </RELEASE_CHILD_STATUS> <RELEASE_REQUESTED_RELEASE TITLE="Requested Release"> <![CDATA[ 4.4 ]]> </RELEASE_REQUESTED_RELEASE> <RELEASE_COMMITTED_RELEASE TITLE="Committed Release"> <![CDATA[ 4.4 ]]> </RELEASE_COMMITTED_RELEASE> </REPEATING_ROW> </REPEATING_ROWS> ... ... ... |
The important data you need is located at
To update the field named RELEASE_CHILD_STATUS field within the repeating record field just retrieved from the example above:
http://extraview.myserver.com/evj/ExtraView/ev_api.action?user_id=myname&password=mypass&statevar=update&id=26788&problem_release_id=1073788412&RELEASE_CHILD_STATUS=6936
To insert a new issue, including one repeating row:
http://extraview.myserver.com/evj/ExtraView/ev_api.action?user_id=myname&password=mypass&statevar=insert&area_id=4&project_id=8&category=SOFTWARE &short_descr=Testing&product_name=EVJAVA&module_name=DATABASE&RELEASE_CHILD_STATUS=6936&description=blah
The presence of the field named RELEASE_CHILD_STATUS, as the only field in the example that has exists within a repeating row record, causes a new repeating row record to be created.