Concepts

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.

API command summary

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

Authentication

All API commands require authentication.  This can take one of three forms:

1. Each call may embed parameters for a valid User ID and a valid password
2. An API call may request a token for subsequent calls using the 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 access
3. A behavior setting named ALLOW_ANONYMOUS_API_ACCESS may turn off authentication via the API.  This is the least secure method of access.

The 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:

1. Within the ExtraView administration section, under the Systems Control tab and within the API Settings section, set the behavior setting named ALLOW_ANONYMOUS_API_ACCESS to have a value of YES
2. In the same section, set the application default named ANONYMOUS_API_USER_ID to the user ID that you will use for the anonymous access
3. All entries made in an anonymous fashion will use this user ID to log their activities
4. Ensure that you only give security privileges to the user group to which this user ID belongs that is in keeping with the fact that this user is used to log all activities. Normally this means that this user group will have limited access to fields, especially in write and query modes
5. It is recommended that when you allow users to enter issues in an anonymous fashion, that you have ExtraView fields that capture their names and other contact details

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.

Requests Passed to the API

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:

• The server domain name, including the path to the servlet where ExtraView is running. For example, http://www.myserver.com/evj/ExtraView
• The class and method which accesses the API. Usually this is ev_api.action
• The user_id and password for the user, passed as name / value pairs or an unexpired token
• The statevar, passed as a name / value pair. This parameter defines the specific API call being made
• A list of name / value pairs providing the parameters and their values for the API call, and which are necessary or optional to execute the API call. Note that the user is responsible to provide a correct list of parameters for each call. If the API does not recognize a parameter, then it is ignored and no warning is given to the user.

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.

XML Data Returned From API Calls

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

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.

Repeating Row Records and the API

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:

• GET
• GET_FIELDS
• HISTORY
• INSERT – note that you can only insert a single repeating row when inserting an issue, but you can then update that issue with additional repeating rows
• RUN_REPORT
• UPDATE – note that you can only update a single repeating row with a single update command.

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:

1. Repeating Rows Element — at most one per issue extracted:

   <REPEATING_ROWS TITLE=’Repeating Rows’ REPEATING_ROWS=’1′> … (repeating row elements) </REPEATING_ROWS>
    

2. Repeating Row Elements – as many as there are repeating rows in the issue extracted:

   <REPEATING_ROW REPEATING_ROW_ID=’nnnnnnn’> … (repeating row field elements) </REPEATING_ROW>
    

3. Repeating Row Field Elements – one for each field inside the 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)

Updating and Inserting Fields in Repeating Row Data

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.

Updating Repeating Rows

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

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

Repeating Row Example

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.

Retrieving an Issue

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 . This provides the unique identifier for the particular repeating row of the issue.

Updating an Issue

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

Inserting an Issue

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.