update

This command allows you to update an existing record within ExtraView’s database. Only values that are being altered need be supplied within the API call. Fields whose values are to remain the same need not be supplied as parameters. All defined business rules using the preupdate and the postupdate directives are executed and checked before and after the record is updated. The fields used with this command are typically those that are placed on the EDIT_PROBLEM layout for the business area and project specified in the syntax of the command.

SYNTAX

http://www.myserver.com/evj/ExtraView/ev_api.action?
user_id=username
&password=password OR [&access_token=token-value]
&statevar=update
&p_template_file=file.html
&id=nnnnn
[&strict=no | yes]
&field1=value1 [&field2=value2] [fieldn=valuen]

There is one additional name and value pair that can be provided, that is not a field within ExtraView. This is &send_email=no. If you supply this name and value pair, then the update will override the set default with which ExtraView will generate email upon the update of an existing issue.

If the issue is updated without error, the function will return the issue number as shown below. Note that the term “Bug #” is dependent on the screen title used for the ID field in the data dictionary.

Bug # 12352 updated.

NOTES

You must provide a valid name and value pair for the ID field. The value must be an existing issue ID within the ExtraView database. If you do not provide this, an error message is generated.

The optional parameter strict, with a value of yes, enforces the action to operate only on ALT_ID. If there is no match for the value of the ALT_ID in the specified ID parameter, then the message Invalid Id will be returned.  This means that a matching ID value will be ignored.

Many of the fields within the ExtraView database, such as product_name, status, priority, severity_level, assigned_to, category, etc., must be given valid values that already exist within the metadata of your installation. If you attempt to enter a value that is not known to ExtraView, an error message will result.

If you attempt to contravene a business rule, an error message will result. For example, if your installation only allows issues to be FIXED if they are in an OPEN state and you provide a value of CLOSED, an error message will result.

All field permissions are obeyed with the command, and if you attempt to update a field that does not have write permission, then the whole command will fail.

The Role of PROBLEM_RELEASE_ID in the update Command

Usually, when one or more specific repeating rows must be affected (modified or deleted) through the update command, the PROBLEM_RELEASE_ID parameter is used to identify specific rows. More than one instance of PROBLEM_RELEASE_ID may be specified. In this case, each field=value parameter corresponds to the PROBLEM_RELEASE_ID which shares the same position in the parameter list for the same field name.

Thus, for example,

…&problem_release_id=111&problem_release_id=222&rr_field=abc&rr_field=def

maps the

rr_field=abc to problem_release_id 111 and rr_field=def to problem_release_id 222.

When no PROBLEM_RELEASE_ID in the parameter list maps to a specific rr_field=value, then a new repeating row is added to accommodate the new value.

Multiple Repeating Row Types

ExtraView supports repeating rows of multiple types. Each type denotes a grouping of fields based on a layout with that item group type. All repeating row types can be updated via the API. There are two ways of specifying a repeating row type:

• Specific PROBLEM_RELEASE_IDxxx values, where xxx is the item group type, e.g., PROBLEM_RELEASE_ID3
• Generic PROBLEM_RELEASE_ID values.

Note1: Specific and generic PROBLEM_RELEASE_ID’s may not be combined in a single API call.

Note2: Each API Update operation using generic PROBLEM_RELEASE_ID values can support only one repeating row type. Attempts to mix two or more repeating row types in a single API operation with generic PROBLEM_RELEASE_ID’s will return with an exception.

The edit screen layout, along with the repeating row layouts applicable to the update request, define which fields belong to which item group type, and therefore, which PROBLEM_RELEASE_IDxxx’s apply.

When generic PROBLEM_RELEASE_ID’s are used, all the specified fields must be grouped into the same item group type (via the edit layout and the repeating row layouts) – this item group type is used to qualify the PROBLEM_RELEASE_ID values.

Example of specific PROBLEM_RELEASE_ID Update

…&PROBLEM_RELEASE_ID3=111&PROBLEM_RELEASE_ID4=222&field1=val1&field2=val2

where field1 is in the repeating row layout of item group type 3 and field2 is in the repeating row layout of item group type 4, both of which are embedded in the edit layout for the user’s curren business area, project and role. Then two repeating rows are updated, one with field1=val1 and the other with field2=val2, each in a different repeating row type.

Example of generic PROBLEM_RELEASE_ID Update

…&PROBLEM_RELEASE_ID=111&field1=val1

where field1 is in the repeating row layout of item group type 3 and repeating row 111 is in item group type 3 results in the update of field1 in the specified row. Note that there is no item group type specified in the PROBLEM_RELEASE_ID variable name.

Using update to Add Repeating Rows

To add new repeating rows, values for fields in the repeating rows are provided without a corresponding PROBLEM_RELEASE_ID value. For each non-corresponding value of a field, a new repeating row is inserted. Thus, specifying &rr_field_a=1&rr_field_a=2&rr_field_a=3 with no specification of PROBLEM_RELEASE_ID will result in three new repeating rows being added with these values, assuming rr_field_a is a field in the repeating row. To update a repeating row value, you must provide the PROBLEM_RELEASE_ID value of the row in question.

Using update to Delete Repeating Rows

Within the ExtraView GUI, users check a box named PROBLEM_RELEASE_DELETE in order to delete a repeating row. The API can emulate this behavior, by setting PROBLEM_RELEASE_DELETE to the checked for value for any repeating row you wish to delete.

For example, use a call similar to the following to delete a repeating row:

Updating Document & Image type fields

These fields require additional metadata in the form of a description and the file to upload’s character set. You will have created an HTML form for the upload. An HTML snippet that shows how to make this work is as follows:

This form assumes an image field that has a data dictionary name of image_dd_name. Note the optional charset and desc. The charset is not required for image fields, but for documents it can be useful. The default, if charset is not given is UTF-8.