Buy Now

DOCUMENT VAULT for Jira Server

The Document Vault plugin consists of functionality in three different areas:

  • Document Vault on Issues for managing you attachments and comments

  • Project Vault Documents tab for searching for vault documents within a project

  • Admin Configuration for specifying who can see and use the Document Vault functionality and what features are available.

  • Project Configuration for project level access privileges or activating only particular Projects 

New Features

  1. Workflow validators to stop the transition from one status to another when there are no attachments on an issue

  2. Toggle visibility of Document Vault based on a yes/no custom field

  3. Append text to the end of a filename (before extension) to add project/issue/date information.

  4. Standalone comments.  Comments can now be added without having to have an attachment.

  5. Permissions to see and use Document Vault functionality can now be specified using roles (previously only user groups could be used).

Sections:

Document Vault on Issues

 

On an Issue the Document Vault panel can be displayed in one of two positions:

  • At the same position as Attachments (Attachments is then displayed below).  This is the default position.

  • As a tab (alongside comment, worklog, etc).

 

The position of the panel can be changed in the Admin Document Vault page (see below).  The pictures below shows the two different layout positions.  In both layout positions, the functionality is identical and the same information is displayed.

From an Issue you can view and add attachments in the Document Vault. The "Document Vault" panel with any attachments and comments are only visible to users authorised from the Admin Document Vault screen (see below). 

 

Clicking on the attachments name will download the attachment.  To the right hand side of each attachments details are three buttons for updating the attachment, edit/create the comment and delete the comment.

 

Downloading All Attachments

All attachments can be downloaded by using the menu to the right of the "+" / "Attach" button.  This will download a zip file containing all of the attachments displayed in the Issues Document Vault.

Adding Attachments

 

Attachments can be added by clicking on the "+" or "Attach" button.  Once added the attachment details are shown along with the optional comment.  Multiple files may be upload at the same time by repeatedly clicking the Browse button and selecting files.  If a comment is added to a multi-file upload the same comment is put against all files.

Update Attachment

 

Updating an attachment will replace the existing attachment with a new version.  The updated attachment does not need to have the same file name.

 

To update the attachment click on the icon with the downward pointing arrow on the right-hand side of the attachment details.  This will open the dialog shown below.  The comment can also be edited at the same time.

Edit Attachment Comment

 

An attachment has an optional comment that is shown (only if present) below the details of the attachment. The comment can be edited or created (if it doesn't already exist) by clicking on the pencil icon on the right-hand side of the attachment details.  Clicking on the icon will allow you to change the comment. NOTE: This is not available for JIRA attachments displayed in the Document Vault panel (see the Admin Document Vault page below for more details)

Delete Attachment

 

An attachment can be deleted by clicking on the rubish bin icon.  You will be prompted to confirm the deletion and then the attachment will be permanently removed.

Standalone Comments

 

Document vault also allows for the entry of comments without an attachment.  Clicking on the comment with a plus icon will open the following dialog.

The list of all comments appears under the list of attachments and the editing/visibility permissions are the same as for attachments.

Project Document Vault Tab

 

The Project Documents tab appears in the left-hand menu of the Project Overview section.  This tab allows you to search through all of the vault attachments in the selected project.  The image below shows an example Project Documents Vault tab with search results showing.

Access

The visibility of this tab is determined by whom you give access to (see the Admin Document Vault section for more details).  If access is only given to users belonging to one of the specified groups (not reporter and not assignee) then this tab is ONLY visible to users in one of the groups, and no one else.

 

If reporter and/or assignee have access to Document Vault then this tab is visible to everyone.  The results of a search are filtered in the following ways:

  • Users in one of the specified access groups see all results

  • If assignee access is specified, but not reporter, then only results in which the user is assignee are shown

  • If reporter access is specified, but not assignee, then only results in which the user is reporter is shown

  • If assignee and reporter access is specified then only results in which the user is either assignee or reporter are shown

  • If the user does not meet the criteria above then they will not see any results

Search Criteria

 

The user can filter the data by:

  • When the attachment was uploaded.  Options are

  1. Any Time

  2. Within the last month

  3. Within the last 3 months

  4. 3 or months old

  • Who uploaded the attachment.  This is context sensitive, only shows users that have uploaded an attachment for this project.

  • The status of the Issue the attachment belongs to.  This is also context sensitive and only shows the current issue status for the project.

  • The mime type of the attachment.

Search Options

 

The user has the following options for sorting the results of a search:

  • Attached Date ascending

  • Attached Date descending

  • Filename ascending

  • Filename descending

The number of results displayed can be restricted to 20, 50 or 100.

Search Results

 

The search results provide information on the related Issue as well as the attachment.  Links in the results allow you to:

  • Navigate to the Issue by clicking on either the "Issue" or "Issue Summary".

  • Download the attachment by clicking on the "Document File Name".

  • Find out information about the user by hovering over the "Attached By" user.

  • Navigate to the users profile by clicking on the "Attached By" user.

Admin Configuration

 

The admin Document Vault page allows an administrator to specify:

  1. Which groups a user can belong to before they can see and use the Document Vault functionality

  2. Which groups a user can belong to before they can get read-only Document Vault functionality

  3. If an Issues reporter and/or Assignee can also see or use the Document Vault functionality

  4. Where on the Issue screen the Document Vault functionality is placed

  5. If JIRA attachments shown, disabled or disabled and included in the Document Vault panel

  6. A Blacklist or Whitelist of file extensions that are not allowed or are allowed to be uploaded

  7. Only Activate in Projects to limit which projects will use Document Vault

  8. Send notifications on adding attachments

  9. Allow for standalone comments

  10. Webhook functionality to notify other systems of Document Vault changes

 

The page is accessible to an admin user from the Document Vault item under the Issue Features heading of the System section.  The page consists of three tabs: Acces, General Config and Other Config which are described below.

dv-admin__access.gif

1. Full Document Vault functionality to Users to the following groups/roles

At the top of the form, you can specify which groups and roles a user can belong to so they can see and use the Document Vault. You can also specify user/users/group/groups custom fields that identify which users have access to a specific user.  If a user is in the user(s) custom field or belongs to a group specified in the group(s) custom fields then they will have access to Document Vault in that issue.  

To enter value click in the edit field and start typing, you be will be prompted with matching roles/groups/custom fields.

2. ReadOnly access to Document Vault functionality to users in the following groups/roles

This field allows you to specify user groups/roles that allow the user to see the Document Vault areas but not add/remove attachments or edit comments.  If this field is left blank then no users will be treated as read-only.

3. Also give access to

Next, are two checkboxes that allow you to also give access to Document Vault to an Issues reporter and/or assignee. The reporter and/or assignee will then have access to the Document Vault functionality even if they do not belong to one of the groups specified above.

dv-admin__general.gif

4. Document Vault Position in the Issue Screen

The next section is for the specification of the position that the Document Vault panel is displayed within the Issue screen. The panel can be displayed as either a tab (alongside comment, worklog etc) or at the same position as Attachments are currently displayed (Attachments is then displayed below this panel).  

5. Attachments

The Attachments section presents three options for dealing with existing JIRA attachments.  These options are:

  1. Show JIRA Attachments as they would normally be displayed.

  2. Disable JIRA Attachments (so no more can be added) and continue showing the JIRA Attachments.

  3. Disable JIRA Attachments (so no more can be added), hide the JIRA Attachments panel and show any existing JIRA Attachments in the Document Vault panel.  The visibility of these attachments is now the same as Document Vault attachments and JIRA Attachments no longer appear in the All Activity/History tab.  The attachments look like a Document Vault attachment except the Update Comment button is missing.

 

If option 2 or 3 are selected then a checkbox called "Allow user to attach files in the comment field" is displayed.  If this is checked then the user can add a Jira attachment by using the attach button on the comment menu bar (normally this is not shown when Jira attachments are disabled).

6. File Extension Filtering

This provides the ability to Blacklist or Whitelist file extensions.  The Blacklist and Whitelist extension are entered as a comma-separated list containing just the extension, not the dot, i.e. gif, png, jpg.  The checking of extensions are case insensitive and regular expressions can be used.  There are three different ways of configuring this:

  1. No Blacklist or Whitelist items.  Attachments with any extension (or no extension) can be uploaded.

  2. One or more Blacklist items.  If an attachment has one of these extensions then the user can not upload it.

  3. One or more Whitelist items.  Only files with one of these extensions can be uploaded.

 

Entering both Blacklist and Whitelist is an invalid option because that would be the same as entering only Whitelist options.

 

7. Only Activate in Projects

This allows you to use Document Vault in just some Projects and to also restrain use of the Plugin by Issue Type(s).  If this is selected then initially no Projects can use Document Vault.  Each Project that does want to use the plugin will have to configure this in the Activate Document Vault Project administration screen, see the next section for details.

If this checkbox is not ticked then all Project and all Issues will use Document Vault as configured.

8. Notifications

This allows you to send a notification whenever a document is attached, which includes updating an existing file.  You can configure the notifications to be sent to those users that have full attach privileges (Group Visibility) and/or those that have read-only access.

9. Standalone Comments

This allows you to control whether or not standalone comments (comments that don't have a related attachment). can be used.

10. Webhook

This allows you to specify a URL that will be posted a JSON message every time an attachment/comment is added, updated or deleted.  The webhook URL makes it easy to have Document Vault changes synced to other systems.

The content of the posted messages is:

Add new comment (not an attachment comment)
{  
   "identifier":2,
   "eventTime":"2018-11-11T07:46:06.360Z",
   "eventType":"addComment",
   "eventUser":"Paul Clark",
   "issueKey": "TEST-1",
   "comment":"My new comment"
}


Update a comment (not an attachment comment)
{  
   "identifier":2,
   "eventTime":"2018-11-11T07:46:57.836Z",
   "eventType":"updateComment",
   "eventUser":"Paul Clark",
   "issueKey": "TEST-1",
   "comment":"My new comment is edited"
}


Delete a comment (not an attachment comment)
{  
   "identifier":2,
   "eventTime":"2018-11-11T07:47:30.721Z",
   "eventType":"deleteComment",
   "eventUser":"Paul Clark",
   "issueKey": "TEST-1"
}

Add a new attachment
{  
   "identifier":17,
   "fileSize":2040097,
   "eventTime":"2018-11-11T06:50:47.008Z",
   "eventType":"addAttachment",
   "eventUser":"Paul Clark",
   "issueKey": "TEST-1",
   "comment":"My comment",
   "fileNameAndPath":"/var/atlassian/jira/data/attachments/DocumentVault/TEST/TEST-1/17_PayrollChange0.9.doc",
   "fileName":"PayrollChange0.9.doc"
}


Update an existing comment
{  
   "identifier":17,
   "eventTime":"2018-11-11T07:03:07.000Z",
   "eventUser":"Paul Clark",
   "eventType":"updateAttachment",
   "issueKey": "TEST-1",
   "comment":"My comment",
   "fileNameAndPath":"/var/atlassian/jira/data/attachments/DocumentVault/TEST/TEST-1/17_PayrollChange1.0.doc",
   "fileName":"PayrollChange1.0.doc",
   "fileSize":1904262,
   "oldFileNameAndPath":"/var/atlassian/jira/data/attachments/DocumentVault/TEST/TEST-1/17_PayrollChange0.9.doc",
   "oldFileName":"PayrollChange0.9.doc"
}


Update the comment related to an attachment
{  
   "identifier":17,
   "eventTime":"2018-11-11T07:03:07.000Z",
   "eventType":"updateAttachmentComment",
   "eventUser":"Paul Clark",
   "issueKey": "TEST-1",
   "comment":"new comment",
   "fileNameAndPath":"/var/atlassian/jira/data/attachments/DocumentVault/TEST/TEST-1/17_PayrollChange1.0.doc",
   "fileName":"PayrollChange1.0.doc",
   "fileSize":1904262
}


Delete an attachment
{  
   "identifier":17,
   "eventTime":"2018-11-11T07:03:07.000Z",
   "eventType":"deleteAttachment",
   "eventUser":"Paul Clark",
   "issueKey": "TEST-1",
   "comment":"new comment",
   "oldFileNameAndPath":"/var/atlassian/jira/data/attachments/DocumentVault/TEST/TEST-1/17_PayrollChange1.0.doc",
   "oldFileName":"PayrollChange1.0.doc"
}

11. Toggle Display

The Toggle Display section allows you restrict access to the Document Vault functionality if a yes/no custom field is set to yes.  An example of the use for this could be for handling personal data.  If the custom field is set to yes, indicating that there is personal information in the documents, then access to those documents is restricted to the specified users.

To set this up you need to:

  • Declare a custom field of the type "Document Vault Display Toggle Field" (under advanced in the add custom field screen)

  • Check the "Use Toggle Field" checkbox

  • Select the custom field in the "Toggle Field" select box

  • Enter the user groups that will have access to the Document Vault functionality

12. Append To Name

The Append To Name section allows you add details to a filename when the file is uploaded.  Any text in this field will be appended to the fllename before the files extension, or at the end of the file if there is no extension.  The appending uses Apache Velocity to place issue/project/date information into the field.  The following values can be used:

  • ${YY} for two digit year

  • ${YYYY} for four digit year

  • ${MM} for 2 digit month

  • ${MON} for 3 character month abbreviation

  • ${DD} for 2 digit day

  • ${HH24} 2 digit hour of a 24-hour clock

  • ${HH} 2 digit hour of 12-hour clock

  • ${MI} 2 digits of minutes

  • ${SS} 2 digit seconds

  • ${AMPM} for AM/PM

  • ${issueKey} for the issue key

  • ${projectKey} for the project key


For example, in the issue TEST-1 on the 24th Dec 2018, the file "myfile.txt" and the append text "_${issueKey}_${YYYY}${MM}${DD}" would produce the new name myfile_TEST-1_20181224.txt

The Other tab for the Document Vault admin configuration

Project Configuration

 

This page has two sections, access level and activate document vault.  The Activate Document Vault is only functional if the "Only Activate in Projects" checkbox is ticked in the Admin Document Vault page.  If the "Only Activate in Projects" checkbox is not ticked then Document Vault will be active for all projects.

The Global Override option allows you to specify which users are allowed to see and access Document Vault functionality.  If Specify Access at the project level is checked then the Group Visibility field is used to determine access to Document Vault functionality with this project.  If the Group Visibility is blank then no users have access to Document Vault.  If there are one or more user groups specified then any users that are in at least one of those groups have access to Document Vault.  User can also have access through the "Also give access to" section in the admin screen.

The Read Only Access field allows you to specify user groups that allow the user to see the Document Vault areas but not add/remove attachments or edit comments.  If this field is left blank then no users will be treated as read-only.

 

If the "Activate for this Project" checkbox is ticked then Document Vault will be active for this project.  This screen also allows you to optionally specify Issue Types.  If there are no Issue Types specified then all Issues within this project will use Document Vault.  If one or more Issue Types is specified then only those Issues that have a type specified will use Document Vault.  All other Issues will just have JIRA attachments.

Service Desk

 

If a Service Desk customer has access to the Document Vault panel (i.e. they are the reporter and the reporter can see the panel) then this will be shown on the right hand side of the Service Desk Customer portals Issue view.

Agile Boards

 

If the user has access to the Document Vault panel then they will be able to also see it in Agile boards and backlog.  Below is an example of what is shown.

Functionality is the same as for the standard issue panel.  Users can add new attachments, edit the comments, update the file/comment and delete attachments from here.

Workflow Validator

If you want to stop an issue transitioning from one status to another without a Document Vault attachment then you can use Document Vault validators.  When a status transition occurs the validator will check to see if the attachments are present and if they are not it will display an error.

To set this up you need to edit the workflow for the project you will use (Project Admin -> Workflows).  Click on the Validators link for the workflow you want to put the validator on

dv-wf-edit.gif

Change to the validators tab and click Add Validator.

dv-validator-tab.gif

You will then be shown a list of validators.  Document Vault has two:

  1. Don't transition if there is not a Document Vault attachment

  2. Don't transition if there is not a Document Vault or Jira attachment

An example is shown below.  The top two options are the Document Vault validators

dv-wf-validator-list.gif

The following is an explanation of the top option, Must have a Document Vault attachment, but the setting up of either validator is identical. 

 

Once the validator is selected from the page shown above, you are prompted to specify which issue types the validator applies to.

dv-wf-validator-params.gif

Once this has been added you be shown the validator details under the validator tab.

dv-wf-validator-details.gif

Next, you need to publish the workflow changes by clicking on the Publish button.  The validator only becomes active once the workflow has been published.

When you now try to transition to the given status an error like the one below will be shown.

dv-workflow-no-dv-attachment-error.gif
 

Redmoon Software

Site Designed: