insert

This API call inserts a new record into the ExtraView database. All fields are treated as optional, and all defined business rules are executed and checked before and after the record is inserted (the preupdate and postupdate rule directives). The fields used with this command are typically those that are placed on the ADD_PROBLEM layout for the business area and project specified in the command syntax.

SYNTAX

http://www.myserver.com/evj/ExtraView/ev_api.action?
user_id=username
&password=password OR [&access_token=token-value]
&statevar=insert
&p_template_file=file.html
&username_display=ID | LAST | FIRST
&send_email=no
&field_name1=value1 [&field_name2=value2] [&field_name_n=valuen]
 

There are two name-value pairs that can be provided, that are not fields within ExtraView. These are –

1. &send_email=no

If you supply this name and value, then the insert will override the standard default with which ExtraView will generate email upon the submission of a new issue

1. &username_display=ID | LAST | FIRST

The optional parameter USERNAME_DISPLAY may be used to override the behavior setting named USERNAME_DISPLAY, for the duration of the execution of a single API call. This allows the developer to return the user names in a different format than the system-wide default.

If the issue is added to the database 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 added.

NOTES

You must not provide a name and value for the ID field. ExtraView allocates all new issue numbers internally and any attempt to provide an ID will result in an error message, similar to “You cannot provide a Bug # when you are adding a new issue.”

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 meta-data 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 new issues to be SUBMITTED and you immediately attempt to provide a value of CLOSED when inserting a record, an error message will result.

Also, note that special non-alphabetic characters, such as a space, must be “escaped”.

You may optionally specify the values for the AREA and PROJECT into which the issue is to be inserted, using their numeric ID. These ID’s can be seen within the administration utilities in the web interface. You may not use their titles. If you do not specify the AREA and PROJECT within the parameter list, then the current AREA and PROJECT of the current user are used. For example, use:

… … &p_area=3&p_project=58 … ….

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

The optional access_token parameter allows you to use a valid OAuth2 token obtained with the get_token command.  If you provide the access_token parameter, then the user_id and password parameters should not be provided.  This prevents the password being sent in clear text over your network connection.

Inserting 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.