INTRODUCTION

    The Simple Tasklists Plugin gives you the ability to create simple, lightweight tasks within Issues, making it perfect to track todo's, or any of the steps necessary to complete a JIRA Issue.

    It eliminates the need to track simple things as entirely separate subtasks, by allowing you to add tasks anywhere within the Issue Description or any Comment.

    Tasks are automatically aggregated into a convenient tasklist on the right side of the Issue Details View.

    PREREQUISITES

    In order to use the Simple Cloud Files addon, you will need an Amazon AWS account as well an Amazon S3 Bucket. For security purposes, we suggest creating a user with access to the Buckets you wish to use.

    Additionally, You will need to configure your S3 Bucket to allow our addon to communicate with it.

    Follow the steps below to setup and configure your S3 Bucket, and for creating IAM credentials.

    Setting up your S3 Bucket

    To configure the Simple Cloud Files plugin, you will need an Amazon S3 Bucket.
    You can use an existing bucket if you already have one, or follow these steps:

    Log into your Amazon AWS Account, and navigate to the S3 Management Console.



    From there, click on "Create Bucket", fill out the dialog, and click the "Next" button.





    Once your bucket is created, you will need to allow the Simple Cloud Files addon to communicate with your bucket. To do so, you need to edit the CORS Configuration of the bucket.

    Select the bucket in the list, and click on the Permissions tab to show the bucket permissions. In the permissions tab, click on the CORS Configuration button, which will bring up the "CORS Configuration editor".



    In the CORS Configuration editor, replace the existing configuration with this one:

    <?xml version="1.0" encoding="UTF-8"?>
    <CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
       <CORSRule>
         <AllowedOrigin>https://www.jirafiles.com</AllowedOrigin>
         <AllowedMethod>GET</AllowedMethod>
         <AllowedMethod>PUT</AllowedMethod>
         <AllowedMethod>POST</AllowedMethod>
         <AllowedMethod>HEAD</AllowedMethod>
         <AllowedMethod>DELETE</AllowedMethod>
         <AllowedHeader>*</AllowedHeader>
         <ExposeHeader>ETag</ExposeHeader>
       </CORSRule>
    </CORSConfiguration>


    The contents of the dialog should look like this:


    This accomplishes the following:
    1) it allows our addon (which lives at https://www.jirafiles.com) to communicate with your bucket
        This is the pre-cursor to us being able to do anything with your bucket

    2) it allows our addon to make GET / PUT / POST / HEAD / DELETE requests to your bucket
        This is needed to retrieve files, upload new files, or delete files

    3) it provides our addon with the ETag header in responses
        This is needed for things like multi-part uploads of larger files

    WHAT IS 'CORS' AND WHY DO I NEED IT?

    'CORS' stands for Cross-Origin Resource Sharing.
    For security reasons, browsers restrict requests coming from a different domain. In this case, AWS keeps your bucket safe from others, and doesn't allow anyone (including us) to communicate with your bucket from the browser. The above settings tell AWS that it's okay for our addon to communicate with your bucket.

    Setting up S3 Credentials

    In Addition to the S3 Bucket, you will need AWS Credentials to connect with.

    NOTE

    For security purposes, we suggest creating an IAM User that only has permissions to this specific bucket, and nothing else.



    To create such an IAM user, log into your Amazon AWS Account, and navigate to the "Identity and Access Management" section.



    From the "Identity and Access Management" Dashboard, click on the "Users" section in the left navigation, and then on the "Create User" button.





    Fill out one of the user name fields with a desired username, and make sure the checkbox for "Generate an access key for each user" is checked. Click the "Create" button when done.



    This will create the user, and bring you to a screen to see the Security Credentials.



    A Note about Default Permissions

    Write these credentials down, or download them (blue button in the footer), as this is the only time these credentials are visible.



    Once done, return to the list of user, and click on the user record to get to the user's profile. Expand the "Permissions" section, and then expand the "Inline Policies" section, and create a new inline policy.



    When creating the policy, select "Custom Policy", and give it a name. We usually use something like "Bucket [BUCKET NAME] Acess", but anything will suffice.
    For the actual policy, paste the following, but replace YOUR_BUCKET_NAME_HERE with the name of your S3 bucket.

    {
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "s3:*",
          "Resource": [
            "arn:aws:s3:::YOUR_BUCKET_NAME_HERE",
            "arn:aws:s3:::YOUR_BUCKET_NAME_HERE/*"
          ]
        }
      ]
    }


    The dialog should look something like this:

    Click on "Apply Policy", and you're done setting up S3, and ready to configure the plugin with your new bucket.

    SETUP & CONFIGURATION

    Configuring the Simple Cloud Files Plugin

    To configure the addon to use your S3 Bucket, navigate to the addons section of JIRA, and then "Manage add-ons". Find the Simple Cloud Files plugin, and then click on "Configure".



    Alternatively, you can also navigate to a project, click on the "Browse S3" icon in the project navigation, which will bring up the Cloud Files section. From there you can then easily get to the bucket configuration.

    Configuring the Global Bucket

    Simple Cloud Files allows for a single (global) bucket to be shared across all projects. Once this bucket is configured, all JIRA projects automatically use it.

    Each project automatically receives it's own folder within the bucket, based on the project key. Within each project folder, each issue receives a folder based on the issue key.
    The resulting folder structure looks somewhat like this:

    root/
    ├── ABC/
    │    ├── projectFiles/
    │    │    ├── Mockups/
    │    │    └── Timesheets.xls
    │    │
    │    ├── ABC-1/
    │    │    ├── screenshot1.png
    │    │    └── Requirements.doc
    │    │
    │    └── ABC-23/
    │         └── API-Spec.pdf
    │
    └── XYZ/
         ├── projectFiles/
         │    └── Style Guide.pdf
         │	 
         ├── XYZ-136/
         │    └── report.xls
         │	 
         └── XYZ-137/
              └── Designs.psd
    
    To configure the global bucket, click on the "Edit Bucket" button, and fill in the form.

    Basic Settings

    The basic settings consist of the credentials to connect to the bucket, as well as the name of the bucket itself. These are required in order to setup a bucket.

    Setting Description
    AccessKey The AccessKey is provided by Amazon when setting up the IAM credentials.
    Secret AccessKey The Secret AccessKey is provided by Amazon when setting up the IAM credentials.
    Bucket Name This is the name of an existing bucket. The above credentials need access to this bucket.


    Testing the Bucket Connection

    Once you've entered all the credentials, you can test the connection to the bucket via the "Test Connect" button. This will attempt to connect to the bucket, and ensure the credentials are valid, and have permissions to the bucket.

    If successful, you should see a shiny green success message:

    If the connection failed, you will see a red error message with some details about why the connection failed.

    The error message can sometimes be a bit vague, which is due to the fact that AWS doesn't always tell us the most descriptive errors.

    If the connection fails, and it is not due to incorrect credentials, ensure the bucket name is spelled correctly, the bucket has the proper CORS configuration, and the credentials you've provided have access to the bucket.



    Testing the CORS Configuration

    Once the credentials are setup, and you are able to connect to the bucket, you can test the CORS configuration via the "Test CORS Settings" button. This will attempt to connect to your bucket, and read the CORS config, and ensure the settings we require are present.

    If the connection fails, this is most likely due to missing settings like AllowedHeaders, or missing AllowedMethod GET. Both of those would result in us not being able to communicate with the bucket.

    Advanced Settings

    The advanced settings are options, and allow you to further tweak how Simple CloudFiles interacts with your S3 Bucket.

    Setting Description
    Prefix By default, we store files in the root of the bucket (based on the structure detailed above). If you wish to store the files somewhere else in the bucket, (a subfolder perhaps), then enter the path here as a prefix.
    Timeout This settings determines how much time we give each upload/download request. The default is 10 minutes. This means a file upload for example has 10 minutes to finish before it gets aborted for taking too long. If you have to live with a slow connection, or have large files to upload, we suggest increasing the timeout to a larger number.
    Full Navigation Normally, each Issue only allows navigating for files that belong to the issue. The same is true for proejcts. You can only see the project-level files. Enabling this setting allows navigating through the full bucket from anywhere. Thus from within an issue, you could navigate upwards and see project level files.
    Multipart Upload This settings controls whether file uploads are processed as a single request, or split into multiple chunks that are uploaded separately, and then assembled back together once the upload finishes. Multipart upload is required if you want to upload large files. This is turne on by default.

    Disabling the Global Bucket

    As you may have noticed, it is possible to disable the Global bucket. To do so, simply switch the toggle button

    If the global bucket is disabled, none of the JIRA projects will have a bucket assigned to it (obviously). This means each project will either need to supply its own bucket, or disable Cloudfiles entirely.

    Once you've filled out the form, click on "Save Settings", and you're ready to use the plugin.

    Configuring a Project Bucket

    If you don't want to have a Global bucket that's shared between all projects, or simply would like to have a separate bucket for some of your projects, you can do so by configuring Project Buckets.

    As you can see, each JIRA project is listed, and tells you which bucket it is currently using, if any.

    To add a bucket

    Simply click on the "Add Custom Bucket" link, which will guide you through the same steps as described above for the global bucket. The only difference being that the bucket will be directly associated with the selected project, and nowhere else.


    To remove a bucket

    Simply click on the small red X icon next to the bucket name. This will remove the bucket from the project. Note that the bucket itself remains untouched within AWS.


    To disable Cloudfiles for a Project

    To disable the Cloudfiles section for a project entirely, simply click on the toggle button on the right. In this case the CloudFiles section within issues as well as the project will be hidden, and inaccessible by users.

    If the project has a bucket associated with it, the bucket remains stored with the project, but simply won't be used / accessible.

    If you re-enable the project, the existing bucket will spring back into action.


    NOTE

    If a project used the Global bucket, and you then add a project bucket, none of the existing files are transferred automatically. You will have to take care of that outside of the addon.

    Similarly, if a project was using a project bucket, and you remove the bucket from the project, the project will revert back to the Global Bucket, which will not contain any of the files that were in the project bucket.


    USING SIMPLE CLOUD FILES

    Uploading files to a Project

    To upload project related files to your S3 bucket, navigate to the project and select "Browse S3" from the project navigation bar.



    Once the plugin loads, you'll see a grid with existing files for this project (if any have been uplaoded yet).
    To upload more, simply click the upload button, and select one or more files to upload.

    Uploading Files to an Issue

    To upload issue related files to your S3 bucket, navigate to an issue of your choice, and utilize the "Cloud Files" panel that is displayed below the issue description.
    Click the upload button, and select one or more files to upload to the issue.



    NOTE

    Issues still retain their ability to have files attached to them directly, which are stored on Atlassian servers. This means your users will see 2 files related sections within issues. "Cloud Files", and "Attachments".

    TIP

    If you wish to disable the JIRA files section, take a look at the documentation for Disable JIRA Issue Attachments

    Creating Folders

    Creating a folder can be done from the Cloud Files toolbar within each issue. Click on the folder icon, and a new row will appear within the file list. Enter the name of the folder to create, and hit enter, or click on the + sign.

    Once created, the folder will show up in the file list, and will be marked with a folder icon.

    To navigate to a folder, click the name, and the Cloud Files section will show the contents of that folder.

    To move up a folder, click on the "../" folder entry at the top.

    Moving Files & Folders

    The short answer:

    Due to technical limitations, this feature is not yet available, but we're trying to figure out how to best implement it.


    The slightly longer answer

    AWS S3 doesn't actually have folders. In S3, a folder is simply an empty file with a filename that ends in a slash. Files that appear in folders actually have a filename that is equivalent to the whole "folder" structure.
    So, a structure that looks like this:

    /
    --/folder1
    ----/someimage.png

    Is actually stored like this:
    /folder1/
    /folder1/someimage.png

    Note that those are the actual filenames within the S3 bucket. So the image has the foldername and the slashes as part of the filename.

    The reason this explanation is important is because the S3 API does not have a proper "move" operation. Instead, every "move" is actually a copy + delete. So, a file is copied and once the copy is done, the original is deleted.

    Moving a single file is technically pretty straight-forward. There is an issue however where we need to manually clean up (delete) the original after the coppy is done. So, if a user tries to move a large file that takes a while, and we start the copy operation and the user then navigates away, we could end up with orphaned or duplicate files.

    When moving a "folder", this issue is compounded, since we would need to traverse the folder structure and find all the files within it, and then do a copy/delete for ALL of them.

    Deleting Files & Folders

    To delete a file, simply click on the trash icon for that file, and confirm the deletion, and the file will be deleted.

    Deleting a folder is currently not possible, for the same reasons that moving a folder is not possible, as described above.

    Renaming Files

    To rename a file, click on the pencil icon on the right, and the name of the file will change to a text field, allowing you to change the name. When done, click on the green checkmark, and the file will be renamed.

    NOTE: Renaming a folder is currently not possible, for the same reasons that moving a folder is not possible, as described above.

    JIRA SERVICE DESK INTEGRATION

    Introduction to Cloud Files for Service Desk

    Simple Cloud Files integrates with Service Desk by exposing the cloud files section to Service Desk Customer requests.

    The files section appears at the bottom of the request and allows customers to upload and download files.



    Files uploaded by Customers from the Service Desk portal are automatically stored in the folder associated with the JIRA issue behind the Service Desk Ticket. Customers can see the files they uploaded, as well as the files that were added to the JIRA Issue.

    If you want customers to not see all the files assocaited with the JIRA Issue, you can configure the Service Desk integration to automatically store customer uploads in a subfolder of the issue. Thus customers can only see the files they uploaded, and the ones an agent uploads into the same folder. All the other files which live in a parent folder would not be visible.

    TIP

    You can restrict what customers can do within the Cloud Files section by disabling upload, folder creation, or delete operations.

    You can even disable the files section conditionally, so it only shows on Service Desk requests where you specifically enable it.

    Configuring Cloud Files for Service Desk

    By default, any Servide Desk JIRA project has Simple Cloud Files integration fully enabled either through the global bucket, or through a project bucket.

    This means if your JIRA instance has Service Desk, all your Service Desk requests automatically show a Cloud Files section, and Customers can fully interact with it, including uploading files, creating folders, as well as deleting files.

    Cloud Files exposes multiple settings that allow you to define which actions customers can take within the Cloud Files section.
    These settings exist on the Global Bucket as well as project buckets for Service Desk projects.



    Explanation of Settings

    Visibility Settings

    This setting determines whether the Cloud Files section is always visible within Service Desk Tickets, or hidden by default.

    Selecting "Per-Ticket" hides the files section until an Agent enables it in the corresponding JIRA Issue.
    This can be done by clicking on the lock icon in the toolbar.


    Subfolder

    This determines the folder within each JIRA issue where customer uploads should be stored. The default value is the root of the issue, which means all customer uploads are stored within the same folder as the regular issue files.

    If you add a value, customer uploads will be placed in the folder you specify. NOTE: this also means that customers can only see files uploaded to this folder, and no others.


    Allow Delete Allows Service Desk customers to delete files associated with the Service Desk ticket.

    Allow Upload Allows Service Desk customers to upload files to the Service Desk ticket.

    Allow Folder Create Allows Service Desk customers to create sub-folders within the Service Desk ticket.


    MISC

    Disable JIRA Issue Attachments

    By default, Simple Cloud Files lives side-by-side with regular Issue attachments. Users can upload files to issues directly, or to the S3 bucket.

    If you don't want users to be able to upload files to JIRA directly, you can disable the JIRA Attachments sections through the project permissions.
    To do so, navigate to the project administration screen, and click on the Permissions link in the left navigation.

    This will bring up the permissions for the project. Click on the Actions button in the top navigation to edit the permissions.

    Find the "Create Attachments" permission, and remove the Roles for the users that should not be able to upload Attachments to issues anymore.

    The result is that users do not have permissions to create attachments, and JIRA will naturally hide the Attachments section from users without this permission. The Cloud Files section within each project remains unchanged, and thus users cannot upload files to Issues, but can still upload them to S3.


    TIP

    A pleasant side effect of this permissions change is that users can drag & drop files from the Desktop onto the Cloud Files section to trigger a file upload.

    Technically, this ability is always enabled, but the JIRA Attachment handling logic automatically hijacks the focus, and thus if the user has Create Attachment permissions JIRA will assume the user wants to attach files to the issue, instead of dropping the file onto the Cloud Files panel.

    Managing Files outside of JIRA

    In case you're not aware of this, Simple Cloud Files does not restrict you from using your S3 bucket in other ways. It simply connects to your bucket, and assumes that files are stored in a specific folder structure. Beyond that though, you can manage the contents of the bucket however you wish, independent or JIRA.

    This effectively means, you could connect to your S3 bucket through one of the various GUI tools, or even the command line, and manage files. You can browse the folders for each project and issue, upload and download files, or move files around.
    Simple Cloud Files will simply pickup the changes the next time an issue or project is loaded.

    NOTE

    Simple Cloud Files expects a specific folder structure. You can move files between folders at will, but do note that the addon will always look for the project files and issue files in the corresponding folders. Thus, if you move the folder for issue ABC-1 to another project for example, Cloud Files would not be aware of it.

    On the other hand, if issue ABC-1 has a subfolder named "Specs", and you move files into it for example, then Simple Cloud Files would pick those up, as the folder for the issue itself is where the addon expects it to be.

    A USEFUL TIP FOR SERVER ADMINS

    For our own purposes, we have a simple shell script that automatically generates an Issue in JIRA if a server encounters an issue, and then uploads log files to the S3 bucket directly. This way, the issue automatically shows the log files associated with the incident.

    Migrating files from JIRA Server to S3

    If you a JIRA Server instance and would like to migrate Issue attachments to S3, you can use the JIRA Server Migration Script we've created.

    Migrating files from JIRA Cloud to S3

    If you have Issue attachments in your JIRA Cloud instance that you would like to migrate to an S3 bucket (and still show within each issue), you can use the JIRA Cloud Migration Script we've created.

    Migrating files between Bucket

    Added a bucket to a project and now need to migrate files from the Global bucket to a Project bucket? (Or vice versa?). you can use the Bucket Migration Script we've created.