Skip to end of metadata
Go to start of metadata

This page explains how to attach files to Jira issues (contributions). It applies to the Jira CONTRIB, LIAISE, and SANDBOX projects. Read more about what constitutes a contribution.

Quick Start

  • Jira attachments are automatically re-named when they are uploaded
  • For regular contributions:
    • The filename will be in the form "CONTRIB-nnnnn-company-title-version.extension", where version and extension are taken from the uploaded filename; e.g., "CONTRIB-12345-bbf-aprilsdocument-01.doc"
  • For drafts:
    • The filename will be in the form "Documentnumber-company-title-version.extension", where version and extension are taken from the uploaded filename; e.g., "WT-398-bbf-aprilsdocument-01.doc"
  • Create a test in SANDBOX 

Table of Contents


Notes and tips

  • If you are uploading an attachment to a new Jira issue, create the issue first, then click the gray "Attach Files" button to upload
  • Sort attachments by clicking the "..." menu at the top right of the list of attachments
  • The automatic file re-naming ensures that all attached filenames include the contribution number, the uploading company, and a version number
  • The automatic filename will use only the version number (if present) and file extension from the uploaded filename
  • Versions are two digits 00-99 and need to be the last part of the filename, just before the extension
  • BBF leaders have additional permissions
  • See the FAQ for more information


Examples

These examples illustrate the life cycle of a contribution.

ExampleDescription
Create contribution

The "Create Issue" screen has changed in one respect:

  1. You can no longer attach files when creating an issue

Other than this, contribution creation is unchanged.

View contribution

The "View Issue" screen has changed in several ways:

  1. The "Attachments" area below the description no longer allows files to be uploaded
  2. The "Attach Files" option has been removed from the "More" menu (OK, you have to look harder to notice this change!)
  3. There's a new "Attach Files" button in the menu bar below the title line

The purpose of these changes is to force the use of the "Attach Files" button for attaching files.

 Click here see the new "View Issue" screen...

Attach a file

Click the "Attach Files" button to display the new "Attach Files" screen. This screen has five sections:

  1. Message: An explanatory message that includes a link to this wiki page
  2. Errors: This will initially indicate "None" because you haven't tried to attach any files yet
  3. Current: This will also initially indicate "None" because there aren't any current attachments
  4. Title: This is initially empty. You can set it, and then it becomes part of future attachment filenames
  5. Attachment: This is the attachment drop / browse area that used to be on the "Create Issue" and "View Issue" screens
 Click here to see the "Attach Files" screen...

Upload a file, e.g. by dragging and dropping it.

Below the title field there's an example actual filename. As we will see later, this will update if you change the title.

(It would be wonderful if the example filename was based on the file that you just uploaded, but unfortunately this isn't possible. Instead the example filenames are based on any previously-uploaded filenames or, if there aren't any, on example.docx.)

 Click here to see how the screen updates...

Click the "Attach Files" button, which will take you back to the "View Issue" screen and you can see that there's now an attachment. In the example, the uploaded file was called Kittens.jpg, but the actual attachment is called CONTRIB-20406-bbf-00.jpg.

  • CONTRIB-20406 is the issue key
  • bbf is the company name (derived from the "BBF Company" field)
  • 00 is the version number (automatically incremented)
  • .jpg is the file extension (unchanged)
 Click here to see the updated "View Issue" screen...

You can attach multiple files at the same time, but this only really makes sense if you are attaching the same file in multiple formats, e.g. a .docx and a .pdf version of the same file.

Attach another version

Click the " Attach Files " button as before (the " Current " section now lists the current attachments), and upload the new files. In the example we use the same Kittens.jpg file but in real life it would be a new version.

 Click here to see how the screen updates...

As before, click the "Attach Files" button, which will take you back to the " View Issue " screen and you can see that there are now two attachments. In the example, they are called CONTRIB-20406-bbf-00.jpg and CONTRIB-20406-bbf-01.jpg .

If you scroll down, you'll see that a comment is automatically added for each attachment. The comment indicates who uploaded the file, the file's original name, and the actual attachment name. You can edit the comment to add additional information if you like.

 Click here to see the updated "View Issue" screen...

Attach a different file

You might want the actual attachment names to be more descriptive, and/or you might want a contribution to have several different sets of independently-versioned attachments. If so, you should set the attachment title.

Suppose we have uploaded a picture of a reclining cat. We can set the title to "reclining".

After I'd set the title, I clicked outside the title area and the example actual filename updated to show how the new title will be incorporated. As already noted, the example filenames are based on the previously-uploaded filenames.


 Click here to see how the screen updates...

When you click the " Attach Files " button you will see that there are now three attachments. In the example, they are called CONTRIB-20406-bbf-00.jpg, CONTRIB-20406-bbf-01.jpg and CONTRIB-20406-bbf-reclining-00.png. Note how the new file is version 00 rather than 02 (each title has independent versions).

 Click here to see the updated "View Issue" screen...

If you return to the "Attach Files" screen you can see that the current attachments are listed by title, and that the title is remembered.

 Click here to see how the title affects the display...

Download → modify → upload workflow

In the earlier examples the uploaded filenames were simple, but often you'll want to use more structured local filenames. Indeed very often you'll want to download a file, update it and then upload the new version.

Let's try downloading CONTRIB-20406-bbf-reclining-00.png and uploading the same file (this is of course a silly thing to do). This gives an error message.

 Click here to see the "Attach Files" screen with the error message...

Rename the file to be version 01 and try again (in real life you'd presumably change the file too!). This works fine, and the actual attachment name is (in this case) the same as the uploaded filename.

 Click here to see the updated "View Issue" screen...

The version number in the uploaded filename is honored (if it's valid). Try renaming the file as version 05 and uploading it.

 Click here to see the updated "View Issue" screen...

Now that version 05 has been created, you can't upload an earlier version, even if the file extension is different. Try creating and uploading a version 04 text file. When you click the "Attach Files" button an error will be reported.

 Click here to see the "Attach Files" screen with the error message...

However, you can upload a version 05 text file (or a later version).

 Click here to see the updated "View Issue" screen...

BBF leaders

For the purposes of this discussion, BBF leaders are members of the tcleaders group.

 Click here to see who's in the tcleaders group...

User list not rendered as you do not have the privilege to view user profiles.

BBF leaders will see an additional "Company" field on the "Attach Files" screen. This allows them (as part of their leadership roles) to change the company part of attachment filenames when uploading files on behalf of another user, WA or PS.

ExampleDescription
BBF staff member uploads on behalf of Arris user

Click "Attach Files" to bring up the "Attach Files" screen. The "Company" field is displayed (its value is always reset to the user's company alias).

 Click here to see the updated "Attach Files" screen...

Change the "Company" field from "bbf" to "arris". When you click outside the field, the example filenames are updated (just as they were when you modified the "Title" field).

 Click here to see the updated "Attach Files" screen...

BBF leader enters invalid company alias

The "Company" field value is checked against known member company aliases, WA keys (e.g. "BUS") and PS keys (e.g. "USP"). If the value doesn't match anything, a warning message is output but the entered value is always used anyway.

 Click here to see the updated "Attach Files" screen...

ATA leader uploads file on behalf of ATA WA

Here's an example of a BBF leader uploading a file on behalf of a WA.

 Click here to see the updated "Attach Files" screen...

Drafts

A draft is an attachment that is (a) associated with a contribution whose issue type is "Draft", and (b) whose filename looks like a BBF draft (e.g. WT-123i2_Rev-00.docx looks like a BBF draft, but Cat.png doesn't).

 Click here for more details...

A filename looks like a BBF draft if it starts with:

  1. One of "ID", "IL", "MD", "OD", "SD" or "WT"
  2. Followed by a hyphen
  3. Followed by a number

Filenames that look like BBF drafts are only treated specially for contributions of issue type "Draft". This is because it's very common for "normal" contributions to have attachments with filenames of the form WT-123-comments.docx. It would be a mistake to treat such attachments specially!

Filenames that don't look like BBF drafts are not treated specially (even if the contribution issue type is "Draft").

Draft attachments are handled differently as follows:

  1. The actual attachment filename begins with the BBF document name (which can include "i", "a" and "c" suffices as in WT-181i2a12) rather than with the CONTRIB name
  2. The attachment "key" is just the BBF document name (including any "i", "a" and "c" suffices), and doesn't include the title
  3. The company name isn't included in the filename (because drafts are in a sense not company contributions)
  4. The version number is preceded by "Rev-" (following existing practice)
  5. Some separators are underscores rather than hyphens (following existing practice)

These rules are designed to give natural behavior (you shouldn't need to be particularly aware of them). Let's look at some examples.

ExampleDescription
Simple filename; no title

Suppose the filename is simply WT-123.txt and the title is an empty string (which is the default for a new contribution). If we upload this file, the actual filename might be WT-123_Rev-00.txt. If we then edit the file and upload the new file, the actual filename will be WT-123_Rev-01.txt.

 Click here to see the updated "View Issue" screen...

Simple filename; with title

Setting the title to "Applied Montreal agreements" and again uploading WT-123.txt will result in WT-123_Applied-Montreal-agreements_Rev-02.txt.

 Click here to see more details...

The title has been entered but the user hasn't yet clicked outside the "Title" box.

The user has now clicked outside the "Title" box, so the title has been processed. A message indicates that the spaces have been replaced with hyphens.

This shows the resulting attachments. Despite having added a title, this is version 02. If it wasn't a draft it would have been version 00.

This shows the same thing. The attachment "key" is the BBF document name and ignores the title. For non-drafts the key is the title.

Complex filename

More complex filenames, e.g. including issue, amendment or corrigendum names, or including version numbers, are handled similarly. For example WT-123_Issue-4_Amendment-5_Corrigendum_6_Rev-07.txt is uploaded as WT-123i4a5c6_Applied-Montreal-agreements_Rev-07.txt. The filename parser is quite permissive.

Note that an explicitly specified "Issue-1" (or "i1") will always be included in the actual filename. For example WT-135_Rev-07.txt is uploaded as WT-123_Applied-Montreal-agreements_Rev-07.txt but WT-135i1_Rev-07.txt is uploaded as WT-123i1_Applied-Montreal-agreements_Rev-07.txt.

 Click here to see more details...

Liaisons

LIAISE attachments are also uploaded via the "Attach Files" screen. This is simpler than for CONTRIB (and SANDBOX): the actual filename will be same as the uploaded filename, except that:

  • The appropriate LIAISE-nnn prefix will be added if not already present (it's an error if the filename already has the wrong prefix)
  • For outgoing liaisons, a version number will be added if not already present

Let's look at some examples.

ExampleDescription
Incoming liaisons

Files can be attached to incoming liaisons in the RECEIVED or RESPONSE NEEDED states.

 Click here to see addition of the prefix, but no version number...

No version number is added, so you have to ensure that the filename is unique.

 Click here to see examples of duplicate filenames...

If the prefix is present, it must be correct!

 Click here to see example of invalid prefix...

Outgoing liaisons

Files can be attached to outgoing liaisons in the IN PROGRESS or UNDER REVIEW states.

Files can't be attached in the OPEN state; you need to click "Start Progress" before you can attach a file.

 Click here to see that you can't attach files in the OPEN state...

Unlike incoming liaisons, outgoing liaison attachments have version numbers.

 Click here to see that outgoing liaison attachments have version numbers...

FAQ

Oops, it seems that you need to place a table or a macro generating a table within the Table Filter macro.

The table is being loaded. Please wait for a bit ...
#QuestionAnswer
1What about attachments on existing contributions? Won't they confuse things?

Yes, this is possible. Attachment naming conventions on existing contributions vary widely. All existing attachment names will be parsed (the parser is quite forgiving) and will be grouped by title as well as possible.

 Click here to see some examples...


CONTRIB-20403 - Getting issue details... STATUS

The two attachment names result in two different titles because one of them uses a "CONTRIB-20403.00" prefix (the version number should be just before the file extension). Hence:

CONTRIB-20396 - Getting issue details... STATUS

The two attachment names result in two different titles because one of their names starts with the wrong CONTRIB number. Hence:

CONTRIB-20171 - Getting issue details... STATUS

Lastly, a draft. No problems here (although note that any new attachment filenames will not have "Contrib-20171" prefixes):

2What about "long-lived" contributions, e.g. contributions that may track BBF document revisions across many meetings?

The key point here (and perhaps the only point that isn't somewhat obvious) is that the issue type must be set to "Draft" in order to enable the special "BBF document" file naming treatment.

CONTRIB-17752 will be used as an example. It was created over two years ago and manages the WT-380 issues list. It has 28 attachments:

  • 10 revisions from ARO days: IL-380_bbf2016.864.xx.docx for xx = 00,...,09
  • 18 further post-ARO revisions: IL-380_C17752.xx.doc for xx = 10..27

We want future attachment filenames to start with "IL-380", which requires the following:

  • The issue type must be "Draft" (at the time of writing, the CONTRIB-17752 issue type is "Other")
  • The uploaded filenames must start with "IL-380"

The other things that influence the actual attachment filename are:

  • The value of the "Title" field (this is set in the "Attach Files" screen)
  • The uploaded filename version number (this is used if present; otherwise the highest existing version number is incremented)
  • The uploaded filename extension (this is always used)

For example, if the "Title" field is empty and I upload IL-380_Rev-28.doc then the actual attachment filename will be IL-380_bbf_Rev-28.doc (the uploaded filename could also have included "bbf"; this would have made no difference).

 Click here for more details and some examples...

The examples use a "dev" Jira version in which there are only 12 existing attachments, of which the most recent is IL-380_C17752.11.doc. That's why you don't see revisions 12 through 27.

The first step is to change the issue type to "Draft":

Then bring up the "Attach Files" screen (leaving the "Title" field empty), drop IL-380_Rev-28.doc and click "Attach Files". The file is uploaded as IL-380_Rev-28.doc and a comment is automatically added:

Now suppose there's a meeting on 20-Nov-18 and I want to upload a Rev-29 that addresses the meeting comments. I rename IL-380_Rev-28.doc as IL-380_Rev-29.doc, edit it, bring up the "Attach Files" screen, set the "Title" field to "20-Nov-18 Agreements" and drop the edited file.


Then I click "Attach Files".

3Can I drag a file, e.g. a screenshot, into a comment?

No. In order to enable the attachment filename processing, it's necessary to completely disable drag-and-drop (after all, a screenshot is an attachment!).

Having said this, it seems that drag-and-drop isn't 100% disabled (and it might not be possible to completely disable it). We have noticed that if you edit a comment in visual mode you can drag a file into the edit screen and it apparently works, except that an "Adding attachments is not supported for this screen" message is displayed. However, when you save the comment the attachment isn't actually there.

 Click here to see what it looks like...

This image was dragged into the edit screen. It apparently worked, but note the error message...

...and that it didn't really work!

4Why are current attachments sometimes labeled "Files" in the "Attach Files" screen?

These are attachments with empty titles. I felt that it was less confusing to label them with a neutral word like "Files" than to show a blank title.

 Click here to see an example...

5When I tried to attach a file I got an "At least one attachment filename is invalid " error but the " Errors " information below doesn't show the details.If this happens, simply re-click the " Attach Files " button. There's a race condition somewhere...
6I don't like the company name abbreviation that's used in my actual attachment filenames. Can it be changed?

The company name abbreviation is derived from your company's primary email domain. Some of them are a bit long, and we can add an alias that will be used in preference to the automatically-derived name. For example, we've added a "bbf" alias that's used in preference to "broadband-forum".

If you'd like such an alias, please create a TOOLS Jira issue or email us on tools@broadband-forum.org.

7I have some other problem.Please create a TOOLS Jira issue or email us on tools@broadband-forum.org. Specify the contribution number and the rough date/time when you had the problem.


  • No labels