add_attachment

This action uploads a file from the local file system to be attached to an existing record in ExtraView. It is designed to be used within an HTML form. Note that the syntax and usage of this command is different to other API commands; extra care should therefore be taken when using the add_attachment command.

SYNTAX

<FORM METHOD="post" action=http://www.myserver.com/dev/ExtraView/ev_api.action?
user_id=username
&password=password OR [&access_token=token-value]
&statevar=add_attachment
&p_template_file=template_filename
[&strict=no | yes]
 

This command must have additional parameters that are not part of the FORM tag, but are part of the HTML within the <form> ... ... </form> construct. These will be provided as part of the INPUT tags within the form. The INPUT tags that must be provided are:

Tag name Purpose
p_id The issue ID
p_attach_desc The description of the attachment
file The filename of the attachment

The following example shows how this API command is used from within an HTML form. The example includes the use of a template file that formats the results returned from ExtraView.

Adding an attachment from an HTML page

<html>
<title>Add an attachment to an existing issue</title>
<body>
<form method="POST"
    action="http://myserver.extraview.net/dev/ExtraView/ev_api.action?
    statevar=add_attachment&p_template_file=attach_results.html&p_id=12345"
    enctype="multipart/form-data">
<input type="hidden" name="p_id" value="12345">
<table>
<tr>
<td>Description</td>
<td><input type="text" size="40" name="p_attach_desc"></td>
</tr>
<tr>
<td colspan="2">Add attachment</td>
</tr>
<tr>
<td>Filename</td>
<td><input type="file" size="40" name="file"></td>
</tr>
<tr>
<td colspan="2"><input type="submit" value="Add Attachment"> </td>
</tr>
</table>
</form>
</body>
</html>

Note that if you are using a template file to return the results of the command, you must include the parameter named p_id twice within the HTML, once within the <form ...> tag, and once as a hidden field within the <INPUT ...> tag. This is because of the limitations of how browsers work with multi-part forms.

attach_results.html template file

This file must reside in the WEB-INF/user_templates directory. Please see the page on server-side templates for a fuller explanation. Carefully note the following in the example file. The following fields are available as tags within the template.

You will see in the example that there is a __REPEAT_START__, __REPEAT_STOP__ block. This allows the display of all attachments added to the issue, with the one just added being the first in the list. If you only want to see the details of the attachment you just added, you can remove the __REPEAT_START__ and __REPEAT_STOP__ statements.

<html>
<title> Attachment added to ExtraView </title>
<body>
<p>Attachment added successfully to issue # __ID__</p>
<br>
A list of all attachments held in the issue is as follows
<br><br>
<table>
<tr>
<td>File name</td>
<td>Description</td>
<td>File size</td>
<td>Created By</td>
<td>Date Created</td>
</tr>
__REPEAT_START__
<tr>
<td>__FILE_NAME__</td>
<td>__ATTACH_DESC__</td>
<td>__FILE_SIZE__</td>
<td>__CREATED_BY_USER__</td>
<td>__DATE_CREATED__</td>
</tr>
__REPEAT_STOP__
</table>
<br>
</body>
</html>

NOTES

  • This command uses a different syntax to most other commands within the API. This is to allow ExtraView to handle the multi-part form, used for uploading files to the server
  • You can upload and attach the same file multiple times to a single record within ExtraView
  • There are no limits to the number of files that can be attached to a single record
  • Each file uploaded can be up to 4 GB in size
  • The syntax of this command is likely to change with future versions of ExtraView, to be consistent with the same action structure as other commands
  • 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
  • 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.
Tag name Purpose
__ATTACH_DESC__ The description of the file that was attached
__ATTACHMENT_ID__ The internal ID of the attachment. Typically not useful for external purposes
__CREATED_BY_USER__ The user who added the attachment
__DATE_CREATED__ The date the attachment was created
__ID__ The ID of the issue to which the attachment was added
__FILE_NAME__ The filename of the file attached
__FILE_SIZE__ The size, in bytes, of the attached file
__NFILES__ The total number of files attached to the issue