--- version: "latest" variant: "File Field Cloud" language: "en" --- # Apwide File Field ## Apwide File Field Attachment Field for Jira Cloud [Get Started](https://file-field.apwide.com/doc/latest/cloud/get-started.md) ### Documentation * #### [Get Started](https://file-field.apwide.com/doc/latest/cloud/get-started.md) * #### [Custom Field Options](https://file-field.apwide.com/doc/latest/cloud/custom-field-options.md) * #### [JQL Properties](https://file-field.apwide.com/doc/latest/cloud/jql-properties.md) #### [How-to Guides](https://file-field.apwide.com/doc/latest/cloud/how-to-guides.md) * #### [DC to Cloud Migration](https://file-field.apwide.com/doc/latest/cloud/dc-to-cloud-migration.md) * #### [Change Logs](https://file-field.apwide.com/doc/latest/cloud/change-logs.md) --- version: "latest" variant: "File Field Cloud" language: "en" --- # Change Logs ## 4.0 (2026-07-20) **Manual Upgrade Required** Version 4.0 requires an additional permission to read/write to app storage service, and requires manual approval. To complete the upgrade, a **Jira Administrator** must go to **Manage Apps** and click **Update**. improvement Better file management in the Atlassian storage. improvement One-click download of PDF files. *** ** * ** *** ## 3.0 (2026-07-08) The first version of File Field Cloud brings dedicated file upload custom fields to Jira Cloud and Jira Service Management Cloud. * Create custom fields of type **Apwide File Field** * Upload files directly from Jira work items and JSM request forms * Configure the maximum number of files per field * Restrict uploads by file category, extension, or MIME type * Define a maximum file size * Store uploaded files securely using Atlassian Forge Object Storage * Runs entirely on Atlassian infrastructure with the **Runs on Atlassian** badge --- version: "latest" variant: "File Field Cloud" language: "en" --- # Custom Field Options In order to access your File Field options: 1. Click the gear icon in the top navigation and select **Marketplace apps**. 2. In the **File Field** section in the side navigation, click **Configure**next to the field to configure. 3. In the Configuration Scheme you want to edit, click **Edit custom field config**. ![image-20260708-160819.png](https://file-field.apwide.com/__attachments/a_9f81c9323e6028095e6c7e3b1dcf649a7883f31b9c012a61c4aee91505223746/image-20260708-160819.png?cb=aed3aa4370c17f07114e28478a662498) Use these settings to control how many files users can upload, which file types are accepted, and the maximum permitted file size. ![image-20260708-161230.png](https://file-field.apwide.com/__attachments/a_902c069d07b748f84155986124a807424e3552f0cf0b9505c9500c49d40b7264/image-20260708-161230.png?cb=4c94db230402f62180dee951933a3ad4) ## Max quantity of files Defines the maximum number of files that can be uploaded to the field. For example, enter `1` to allow only one file or `5` to allow up to five files. ## Allowed file type Select one or more predefined file-type categories from the dropdown. Depending on the available options, categories may include images, documents, audio files, videos, archives, or other common file formats. Leave this field and **Custom file types** empty to allow any file type. ## Custom file types Enter additional file extensions or MIME types that should be accepted. Separate multiple values with commas. Examples: .zip, .json, video/* application/json, application/pdf You can use: * File extensions, such as `.zip` or `.csv` * Exact MIME types, such as `application/json` * MIME type wildcards, such as `video/*` Custom file types are added to the predefined categories selected under **Allowed file type**. ## Maximum file size Defines the maximum permitted size for each uploaded file. Enter a numeric value and select the corresponding unit, such as `kB` or `MB`. For example, `100 kB` means that each uploaded file must be no larger than 100 kilobytes. Files exceeding this limit cannot be uploaded. ## Save the configuration Select **Save** to apply the configuration. The restrictions will be checked whenever a user uploads a file to this field. Existing files are not modified when the configuration changes. --- version: "latest" variant: "File Field Cloud" language: "en" --- # DC to Cloud Migration We are currently working on a migration path based on the Jira Cloud Migration Assistant (JCMA) to help you migrate from File Field Data Center to File Field Cloud. This migration capability is expected to become available by mid-July 2026. *** ** * ** *** ## Planning a migration? If you are planning to move from File Field Data Center to File Field Cloud, please contact us before starting your migration. Our team will: * Keep you informed about the availability of the JCMA migration path * Help you prepare your File Field migration * Guide you through the migration process * Provide dedicated support if you encounter any issues [Contact Apwide Support](https://apwide.atlassian.net/servicedesk/customer/portal/1/group/1/create/1) to discuss your migration plans. *** ** * ** *** ## Main differences | **Feature** | **File Field DC** | **File Field Cloud** | |------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------| | Default value | Configure a default file that is automatically added to the field when an issue is created. | This feature is not yet available. [Let us know if you need it](https://apwide.atlassian.net/servicedesk/customer/portal/1/group/1/create/6) | | Read-only fields | File fields can be configured as read-only. Combined with a default value, this allows users to download predefined files while completing forms. | This feature is not yet available. [Let us know if you need it](https://apwide.atlassian.net/servicedesk/customer/portal/1/group/1/create/6) | | Image thumbnails | Image thumbnails are displayed directly in File Field. | Image thumbnails are not currently available due to Atlassian platform limitations and the requirements of the Runs on Atlassian program. | | JQL properties | Supports a limited set of JQL properties. | Supports additional JQL properties for more advanced searches. | --- version: "latest" variant: "File Field Cloud" language: "en" --- # Get Started ## Welcome to File Field Cloud Get started in just a few steps: 1. [Install](https://marketplace.atlassian.com/apps/1217971/file-field-attachment-custom-field-for-jira?hosting=cloud&tab=overview) Apwide File Field for free. 2. [Create](https://support.atlassian.com/jira-cloud-administration/docs/create-a-custom-field/) a new custom field of type **Apwide File Field**. 3. [Configure the field](https://file-field.apwide.com/doc/latest/cloud/custom-field-options.md) according to your requirements. 4. Start uploading files. 😎 ## Security \& Compliance * Apwide File Field **Runs on Atlassian** , which means that uploaded files are stored securely within your Jira Cloud site using [Atlassian Forge Object Storage](https://ecosystem.atlassian.net/jira/polaris/projects/ROADMAP/ideas/view/5062047?selectedIssue=ROADMAP-190). * Apwide has been an [Atlassian Marketplace Partner](https://marketplace.atlassian.com/vendors/1211423/apwide) since 2016 and actively participates in the [Marketplace Security Bug Bounty Program](https://developer.atlassian.com/platform/marketplace/marketplace-security-bug-bounty-program/). * File Field was also a winner of [Codegeist 2025](https://devpost.com/software/file-field-cloud), Atlassian's official app-development hackathon. * For further information about our security practices, compliance program, and data protection measures, visit the [Apwide Trust Center](https://trust.apwide.com/). --- version: "latest" variant: "File Field Cloud" language: "en" --- # How-to Guides Follow these step-by-step guides to configure File Field for common Jira Cloud and Jira Service Management Cloud use cases. Start by learning how to collect required documents through a Jira Service Management request form. More practical guides covering file organization, upload restrictions, and automation will be added over time. * [How to Collect Required Documents in Jira Service Management](https://file-field.apwide.com/doc/latest/cloud/how-to-guides/how-to-collect-required-documents-in-jira-service-management.md) --- version: "latest" variant: "File Field Cloud" language: "en" --- # How to Collect Required Documents in Jira Service Management Use File Field to collect required documents from customers through the Jira Service Management portal. In this example, we will create a **Request a contract review** request type with a required **Contract to review** field. *** ** * ** *** ## Before You Begin Make sure that: * File Field is installed on your Jira Cloud site. * You can create and configure Jira fields. * You can configure request types in the relevant Jira Service Management space. *** ** * ** *** ## 1. Create the File Field Create a new custom field of type **Apwide File Field**: 1. Open the **Jira settings** (top-right gear icon). 2. Select **Work items**. 3. Select **Fields**. 4. Select **Create new field**. 5. Search for and select **Apwide File Field**. 6. Enter a name for the field, such as `Contract to review`. 7. Add the field to the relevant field scheme. Atlassian is currently rolling out [changes to how fields are configured in Jira](https://developer.atlassian.com/changelog/#CHANGE-3019). Depending on your site, you may still see **field configurations** instead of **field schemes**. The process remains the same: make sure the field is added to the configuration used by your Jira space. ![image-20260715-192637.png](https://file-field.apwide.com/__attachments/a_3156a023d8e200d1dbbf51a236c2840a7c3b1489171babdc57a9a5c75fcaee32/image-20260715-192637.png?cb=70265626d78a0f0563a0e6b436293b6b) Create the File Field ![image-20260715-192741.png](https://file-field.apwide.com/__attachments/a_697bc727d46c47f724fb49344d56f2ce5c4d148e75247c8e1eb5e293891ffdd0/image-20260715-192741.png?cb=9cc4b6ae09cf5c0aec0468142ef0915a) Add the field to the field scheme *** ** * ** *** ## 2. Configure the Upload Restrictions Configure the field according to the documents you want to collect: 1. Locate your field in the **Fields** section. 2. Select **Contexts and default values** in the Actions (three-dots) menu next to your field. 3. Select **Edit custom field config** in the relevant configuration scheme. ![image-20260715-194326.png](https://file-field.apwide.com/__attachments/a_118a6e801e2f5d98aff97fe7fdb4ea6374933ce5b0236a29408e83a6e30c3be0/image-20260715-194326.png?cb=280ad1130a2aaface583e27d8a592ff0) Edit the field configuration For this example, use the following configuration: | Option | Value | |-----------------------|--------------| | Max quantity of files | `1` | | Allowed file type | `PDF` `Word` | | Custom file types | *\[empty\]* | | Maximum file size | `10 MB` | ![image-20260715-193958.png](https://file-field.apwide.com/__attachments/a_6ac19ceaa02d452331f1524587a8b311833aa8afb23f138458ba57f9caf1c956/image-20260715-193958.png?cb=8c57b78fa9c459dee5040836e2a1754e) Configure the File Field Select **Save** to apply the configuration. For more information about the available settings, see [Custom Field Options](https://file-field.apwide.com/doc/latest/cloud/custom-field-options.md). *** ** * ** *** ## 3. Create the Request Type Create the service request that customers will use to submit contracts: 1. Open the relevant service space. 2. Select **Space settings**. 3. Select **Request management** , then **Request types**. 4. Create a request type named `Request a contract review`. 5. Select the Jira work type that will be used for these requests. You can start with a simple request form. The **Contract to review** field will be added in a later step. *** ** * ** *** ## 4. Add the Field to the Jira Screens Add the **Contract to review** field to the screens used by the Jira work type selected for the request: 1. In the **Request management** section, select **Screens**. 2. Find the work type used by **Request a contract review**. 3. Add the **Contract to review** field to the relevant Create, Edit, and View screens. Depending on your Jira configuration, the same screen may be used for the Create, Edit, and View operations. At minimum, add the field to the **Create screen** so it becomes available when configuring the request form. *** ** * ** *** ## 5. Add the Field to the Request Form Open the **Request a contract review** request type, then add the **Contract to review** field to its request form: **Display name** `Contract to review` **Description** `Upload the contract for review as a PDF, DOC, or DOCX file, up to 10 MB.` Enable **Required** so customers cannot submit the request without uploading a valid contract. ![image-20260715-204732.png](https://file-field.apwide.com/__attachments/a_cbcf5dcff4000faba209886d084b069da8b2527c6b8f419ec4e1b9484c03a450/image-20260715-204732.png?cb=879d695680d544d103a83d9cae69dbde) Add the field to the contract review request form *** ** * ** *** ## 6. Test the Request Open the customer portal and submit a test request. Confirm that: * A valid PDF, DOC, or DOCX file can be uploaded. * Unsupported or oversized files are rejected. * The request cannot be submitted without a contract. ![image-20260715-205717.png](https://file-field.apwide.com/__attachments/a_22511bf392b817d21896c2126bf1cbf7342532c607c1f7ffefeda406351ff6db/image-20260715-205717.png?cb=ebd26b84463da5ccf7dda49b7510f315) Contract review request in the customer portal ![image-20260715-205429.png](https://file-field.apwide.com/__attachments/a_6a25b17191de274dfbe9fc63e10f7aac5bebcbaafc85d3bf2cde6694d4a59a3b/image-20260715-205429.png?cb=05bc5c1ebeea7cbb4526fe6335f3de19) Missing document ![image-20260715-205819.png](https://file-field.apwide.com/__attachments/a_1fbe189a20700878bbb237502f6f7d50830b0c1720acc227f45f3ee1f4eb6a8e/image-20260715-205819.png?cb=5dfdbed9da603b9e66431fc679cb1e95) Oversized PDF file *** ** * ** *** ## 7. Review the Submitted Contract Open the submitted request in Jira. The uploaded contract appears in the dedicated **Contract to review** field, where agents can preview or download it. ![image-20260715-203307.png](https://file-field.apwide.com/__attachments/a_f45527edffeea5cf0ad14d3eb42ae3ae33139a7ef426a699f4092c82da32a87f/image-20260715-203307.png?cb=ef5837605a08c53d96742c5e79bb664d) Contract in the Jira work item Using a dedicated field keeps the contract separate from unrelated attachments added during the review process. *** ** * ** *** ## Related Use Cases You can use the same approach to collect: * Proof of purchase for refund requests * Identity documents for access requests * Certificates for compliance reviews * Test evidence for validation workflows You can also search File Field metadata with JQL and use it in Jira Automation rules. See [JQL Properties](https://file-field.apwide.com/doc/latest/cloud/jql-properties.md) for the available search options. *** ** * ** *** ## Need Assistance? For help configuring File Field for Jira Service Management, reach out to our [Customer Portal](https://apwide.atlassian.net/servicedesk/customer/portal/1/group/1/create/1). --- version: "latest" variant: "File Field Cloud" language: "en" --- # JQL Properties File Field Cloud exposes dedicated JQL properties that let you search issues based on the files stored in a File Field. You can search by filename, extension, MIME type, number of files, or file size. These properties can be used in Jira searches, saved filters, dashboards, and Automation rules. ![image-20260714-073646.png](https://file-field.apwide.com/__attachments/a_be1602ee053778adf6509064dfdeb6323302721bd5a383bfcafe0cb63fca28c3/image-20260714-073646.png?cb=d294bdc7fc8434df5b763dd95de5fc5e) Properties displayed when typing the field name in a JQL search ## Available properties Replace `CV` in the examples below with the name of your File Field. | **Property** | **Description** | **Example** | |-----------------|-------------------------------------------------------|-----------------------------------| | `extension` | File extension, without the leading dot | `CV.extension = "pdf"` | | `fileCount` | Number of files stored in the field | `CV.fileCount > 1` | | `fileName` | Name of an uploaded file | `CV.fileName ~ "contract"` | | `mimeType` | MIME type of an uploaded file | `CV.mimeType = "application/pdf"` | | `sizeInKB` | Size of an individual file, in kilobytes | `CV.sizeInKB > 500` | | `sizeInMB` | Size of an individual file, in megabytes | `CV.sizeInMB > 5` | | `totalSizeInKB` | Combined size of all files in the field, in kilobytes | `CV.totalSizeInKB > 1000` | | `totalSizeInMB` | Combined size of all files in the field, in megabytes | `CV.totalSizeInMB > 10` | When the field name contains spaces, enclose it in quotation marks: "Contract Documents".extension = "pdf" ## Search by file extension Find issues containing a PDF file: CV.extension = "pdf" Find issues containing a PNG or JPG image: CV.extension IN ("png", "jpg", "jpeg") Exclude ZIP files: CV.extension != "zip" ## Search by filename Find issues containing a file whose name includes `contract`: CV.fileName ~ "contract" Find a file by its exact name: CV.fileName = "signed-contract.pdf" Exclude files whose names contain `draft`: CV.fileName !~ "draft" ## Search by MIME type Find issues containing PDF documents: CV.mimeType = "application/pdf" Find issues containing PNG or JPEG images: CV.mimeType IN ("image/png", "image/jpeg") MIME type searches can be more reliable than extensions when different extensions represent the same file format. ## Search by number of files Find issues containing at least one file: CV.fileCount > 0 Find issues containing more than one file: CV.fileCount > 1 Find issues where the field contains exactly three files: CV.fileCount = 3 You can also use the standard JQL syntax to find empty fields: CV IS EMPTY Or fields that contain a value: CV IS NOT EMPTY ## Search by individual file size Find issues containing a file larger than 5 MB: CV.sizeInMB > 5 Find issues containing a file between 1 MB and 10 MB: CV.sizeInMB >= 1 AND CV.sizeInMB <= 10 The same query can be written using kilobytes: CV.sizeInKB > 500 The `sizeInKB` and `sizeInMB` properties apply to individual files stored in the field. ## Search by total file size Find issues where all files in the field use more than 10 MB in total: CV.totalSizeInMB > 10 Find issues where the combined size is between 1 MB and 20 MB: CV.totalSizeInMB >= 1 AND CV.totalSizeInMB <= 20 The `totalSizeInKB` and `totalSizeInMB` properties represent the combined size of all files stored in the field. ## Combine File Field properties You can combine multiple File Field properties in the same query. Find issues containing more than one PDF file: CV.extension = "pdf" AND CV.fileCount > 1 Find issues containing files larger than 5 MB, with more than 20 MB stored in total: CV.sizeInMB > 5 AND CV.totalSizeInMB > 20 Find issues containing a signed PDF document: CV.extension = "pdf" AND CV.fileName ~ "signed" ## Combine with standard Jira fields File Field properties can be combined with any other JQL criteria. Find unresolved issues containing PDF documents: resolution IS EMPTY AND CV.extension = "pdf" Find service requests without any uploaded files: project = SUPPORT AND issuetype = "Service Request" AND CV IS EMPTY Find completed issues containing large files: statusCategory = Done AND CV.sizeInMB > 10 Find recently created issues containing contract documents: created >= startOfMonth() AND "Contract Documents".fileName ~ "contract" ## Use File Field JQL properties in Automation These properties can also be used in Jira Automation wherever a JQL query is supported. For example, you can create rules that: * Notify users when a required document is missing. * Detect files exceeding a defined size. * Transition an issue when a specific document is uploaded. * Identify issues containing unsupported file types. * Create scheduled reports for incomplete documentation. Example JQL condition: "Approval Documents".fileName ~ "signed" AND "Approval Documents".extension = "pdf" ## Notes and limitations JQL searches File Field metadata, not the contents of uploaded files. For example, you can search for a PDF by its filename, extension, MIME type, or size, but not for text contained inside the PDF. After a file is uploaded, replaced, or deleted, Jira may need a short time to update its search index before the change is reflected in JQL results. ## Need Assistance? For support with searching on file fields, reach out to our [++Customer Portal++](https://apwide.atlassian.net/servicedesk/customer/portal/1/group/1/create/1). --- version: "latest" variant: "File Field Data Center" language: "en" --- # Apwide File Field ## Apwide File Field Attachment Field for Jira Data Center [Get Started](https://file-field.apwide.com/doc/latest/data-center/get-started.md) ### Documentation * #### [Get Started](https://file-field.apwide.com/doc/latest/data-center/get-started.md) * #### [Custom Field Options](https://file-field.apwide.com/doc/latest/data-center/custom-field-options.md) * #### [Java/Groovy API](https://file-field.apwide.com/doc/latest/data-center/java-groovy-api.md) * #### [REST API](https://file-field.apwide.com/doc/latest/data-center/rest-api.md) * #### [DC to Cloud Migration](https://file-field.apwide.com/doc/latest/data-center/dc-to-cloud-migration.md) --- version: "latest" variant: "File Field Data Center" language: "en" --- # Custom Field Options ## Configure Custom Field → Click on the "Configure" link in the custom field admin list and click on the Apwide File Field configuration menu: ![ApwideFileFieldConfigurationMenu.png?version=1&modificationDate=1595321792650&cacheVersion=1&api=v2](https://file-field.apwide.com/__attachments/a_ca422ea0f8eca4ae28b403879783ca34840de00ff5fb0b4fe3e9ede9fddbb2a9/ApwideFileFieldConfigurationMenu.png%3Fversion=1&modificationDate=1595321792650&cacheVersion=1&api=v2?cb=2d86a14974ceca5f2986c73beb087c31) ## Auto Clean From **version 1.1.+** you can activate the "Auto-clean" option in the configuration of your custom field. When this option is activated, the old file is automatically removed from the file system when uploading a new file. → Activate or Deactivate the Auto clean, and save ![AutoCleanFileOption.png?version=1&modificationDate=1595321853479&cacheVersion=1&api=v2](https://file-field.apwide.com/__attachments/a_52ad8ceb3e37d2eac48e07fac2684276c0abc60e0925f375b2d90ea74318944c/AutoCleanFileOption.png%3Fversion=1&modificationDate=1595321853479&cacheVersion=1&api=v2?cb=97ef9d011245e0603cc106b98f2cc4ef) ## Allowed File Extensions From **version 2.+** you can check the file extensions before uploading using an option in the configuration of your custom field: ![Apwide_File_Field_Limit_File_Types.png?version=1&modificationDate=1595321906173&cacheVersion=1&api=v2](https://file-field.apwide.com/__attachments/a_0a43a3552d12ce4ed6dc60e18d402c52612f63e7e065adaf393962f77ac33cb5/Apwide_File_Field_Limit_File_Types.png%3Fversion=1&modificationDate=1595321906173&cacheVersion=1&api=v2?cb=a32111c9ad67583ec90dc0bddf2a5c0d) ## File Size Limit From **version 2.1.+** you can limit the maximal size of files that can be uploaded using an option in the configuration of your custom field: ![MaxFileSize_Apwide_FileField.png?version=1&modificationDate=1595321947284&cacheVersion=1&api=v2](https://file-field.apwide.com/__attachments/a_03c02ac0c388c600f8b852cf690e2c9c83bb294f2e0477f3e553cd81f75233f1/MaxFileSize_Apwide_FileField.png%3Fversion=1&modificationDate=1595321947284&cacheVersion=1&api=v2?cb=db54b7e7756f118510050cffb39d168c) ## Max Files Allowed From **version 3.1.+** you can customize the maximum number of files that can be uploaded to the current custom field (default value: 10). ![File%20Field%20Option%20-%20Max%20Files%20per%20field.png?version=1&modificationDate=1595335500640&cacheVersion=1&api=v2](https://file-field.apwide.com/__attachments/a_7596822a8c46a08c3fc85d9c473b8e494c638bc9d9f4d39589529d013e03933e/File%2520Field%2520Option%2520-%2520Max%2520Files%2520per%2520field.png%3Fversion=1&modificationDate=1595335500640&cacheVersion=1&api=v2?cb=f4b4ef39a27d8159556c53330cc76b9f) ## Grid Display From **version 3.1.+** downloadable files are arranged in a grid by default when displayed in the custom field. You can customize the size of the icons/miniatures and the width of the file name. Tip: set the *Name width* to 0 to completely hide it. ![File%20Field%20Grid%20Display%20Options.png?version=1&modificationDate=1595335838623&cacheVersion=1&api=v2](https://file-field.apwide.com/__attachments/a_103d000aa7aa2ff006d5b779a4baf9dc62a810eb0f064a820cda10cadb04728b/File%2520Field%2520Grid%2520Display%2520Options.png%3Fversion=1&modificationDate=1595335838623&cacheVersion=1&api=v2?cb=ac7d2b09711e2f9463f585d51619168e) ## List Display From **version 3.1.+** you can arrange downloadable files in a compact list when displayed in the custom field. This layout is convenient when many files may be uploaded into a single custom field. ![Screenshot%202020-07-21%20at%2014.55.15.png?version=1&modificationDate=1595336130684&cacheVersion=1&api=v2](https://file-field.apwide.com/__attachments/a_cc34b84a315d42dc21a7bf41122909dfe6f2f3903dc382cc0a103420fae0700e/Screenshot%25202020-07-21%2520at%252014.55.15.png%3Fversion=1&modificationDate=1595336130684&cacheVersion=1&api=v2?cb=a89702cdadf896dc2c81769c0c292c90) ## Default Values From **version 3.1+** you can set multiple files as default values directly from the main configuration screen. ![Screenshot%202020-07-21%20at%2015.09.15.png?version=1&modificationDate=1595336973987&cacheVersion=1&api=v2](https://file-field.apwide.com/__attachments/a_4348c807dc5af258a1adf646b3e3f02ef02217b7a36ba8e1a054cbca496a0324/Screenshot%25202020-07-21%2520at%252015.09.15.png%3Fversion=1&modificationDate=1595336973987&cacheVersion=1&api=v2?cb=6612f4f0cd865c063e58f33387906d33) ## Readonly / Documentation Mode Activate this option to push reference files \& documentation to users creating/updating issues/tickets. The files set as default values will not be editable, just downloadable by users on create/update issue/service desk screens. ![image-20220605-140040.png](https://file-field.apwide.com/__attachments/a_ccfe84a451343fb5bb5d08145ff6a40c7c93dd22c798ed22ec11c720867307ef/image-20220605-140040.png?cb=588294ed906ffe76e71462f4ab348cb8) --- version: "latest" variant: "File Field Data Center" language: "en" --- # DC to Cloud Migration We are currently working on a migration path based on the Jira Cloud Migration Assistant (JCMA) to help you migrate from File Field Data Center to File Field Cloud. This migration capability is expected to become available by mid-July 2026. *** ** * ** *** ## Planning a migration? If you are planning to move from File Field Data Center to File Field Cloud, please contact us before starting your migration. Our team will: * Keep you informed about the availability of the JCMA migration path * Help you prepare your File Field migration * Guide you through the migration process * Provide dedicated support if you encounter any issues [Contact Apwide Support](https://apwide.atlassian.net/servicedesk/customer/portal/1/group/1/create/1) to discuss your migration plans. *** ** * ** *** ## Main differences | **Feature** | **File Field DC** | **File Field Cloud** | |------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------| | Default value | Configure a default file that is automatically added to the field when an issue is created. | This feature is not yet available. [Let us know if you need it](https://apwide.atlassian.net/servicedesk/customer/portal/1/group/1/create/6) | | Read-only fields | File fields can be configured as read-only. Combined with a default value, this allows users to download predefined files while completing forms. | This feature is not yet available. [Let us know if you need it](https://apwide.atlassian.net/servicedesk/customer/portal/1/group/1/create/6) | | Image thumbnails | Image thumbnails are displayed directly in File Field. | Image thumbnails are not currently available due to Atlassian platform limitations and the requirements of the Runs on Atlassian program. | | JQL properties | Supports a limited set of JQL properties. | Supports additional JQL properties for more advanced searches. | --- version: "latest" variant: "File Field Data Center" language: "en" --- # Get Started ## Welcome to File Field's World! Thanks for your interest in *Apwide File Field* Jira App. Learn how to turn your Jira instance into a powerful document-based workflow engine! ## Get Started 1. [Install](https://marketplace.atlassian.com/plugins/com.apwide.document.file-field/server/overview) the latest version of *Apwide File Field* for free 2. [Create](https://confluence.atlassian.com/adminjiraserver075/adding-a-custom-field-935391218.html) a new custom field of type *Apwide File Field* 3. Enjoy! 😎 ![Apwide File Field Custom Field Inline Edition.png](https://file-field.apwide.com/__attachments/a_83362db5074bbba7dddec336026497c79092dae02224739491839cec26afd635/Apwide%20File%20Field%20Custom%20Field%20Inline%20Edition.png?cb=ff1f52970b49638b640cbc1e06579b0d) ## Notes for Jira Administrators There is **no required setup** in order to use this app in your test or production environments: * All documents uploaded by "File Field" app are stored in the sub-folder "00_apwide_file_field_files" of the already existing "attachments" folder used to store standard Jira attachments. * Size limit of files you can upload is the same as the one for standard Jira attachments * File Field is compatible with [Jira Automation](https://marketplace.atlassian.com/apps/1215460/automation-for-jira-server) and automation apps like [ScriptRunner](https://marketplace.atlassian.com/apps/6820/scriptrunner-for-jira), [JSU](https://marketplace.atlassian.com/apps/5048/jsu-automation-suite-for-jira-workflows), etc. * File Field is **not compatible** with Amazon S3 attachment storage ([more information](https://confluence.atlassian.com/adminjiraserver100/storing-attachments-in-amazon-s3-1442846216.html)). In order for File Field to work properly, your attachments should be stored locally in the file system. *** ** * ** *** ## Documentation * [Custom Field Options](https://file-field.apwide.com/doc/latest/data-center/custom-field-options.md) * [REST API](https://file-field.apwide.com/doc/latest/data-center/rest-api.md) * [Java/Groovy API](https://file-field.apwide.com/doc/latest/data-center/java-groovy-api.md) *** ** * ** *** ## Quick References * [App Installation Procedure](https://marketplace.atlassian.com/apps/1217971/file-field-attachment-document-field?hosting=server&tab=installation) * [Apwide Customer Portal](https://apwide.atlassian.net/servicedesk/) * [More about Apwide](https://www.apwide.com/) *** ** * ** *** ## Contact us We are happy when we can make your life easier, do not hesitate to contact us: * To get specific support or to request a new feature : [open a ticket](https://apwide.atlassian.net/servicedesk/) * You can also [contact us by email](https://www.apwide.com/company/) * Please [review File Field App](https://marketplace.atlassian.com/plugins/com.apwide.document.file-field/reviews) if you like it 😎 *** ** * ** *** --- version: "latest" variant: "File Field Data Center" language: "en" --- # Java/Groovy API File Field is compatible with all Jira automation apps: [ScriptRunner](https://marketplace.atlassian.com/apps/6820/scriptrunner-for-jira), [Automation for Jira](https://marketplace.atlassian.com/apps/1215460/automation-for-jira-server), [JSU](https://marketplace.atlassian.com/apps/5048/jsu-automation-suite-for-jira-workflows), etc. You can use the FileManager java component to manage your files programmatically from java/groovy scripts. *** ** * ** *** ## Plain Java Example Java import com.apwide.file.api.FileManager; ... import com.atlassian.jira.component.*; // Get FileManager instance FileManager fileManager = ComponentAccessor.getComponent(FileManager.class); // Binary content to upload InputStream inputStream = new ByteArrayInputStream("any content".getBytes(StandardCharsets.UTF_8)); // Name of the file to upload String fileName = "Readme.txt"; // Size limit of file to upload (ex: 10Mo) long maxFileSize = 10*1000*1000; // UPLOAD String fileId = fileManager.upload(fileName, inputStream, maxFileSize); // DONWLOAD InputStream downloadedFile = fileManager.download(fileId); // GET PATH String filePath = fileManager.getPath(fileId); // CHECK IF IT EXISTS boolean exists = fileManager.exists(fileId); // DELETE boolean deleted = fileManager.delete(fileId); *** ** * ** *** ## Script Runner Groovy Example This example script shows how to create/upload 2 files and add them to an existing File Field customfield. N.B. Adding multiple uploaded files into 1 single customfield is supported since **version 3.1.0**. You should always set the value of a File customfield using a unique String: * containing 1 file id. Example: "1568037617780_10000_w3c_home.gif" * or containing multiple file ids separated by a comma. Example: "1568037617780_10000_w3c_home.gif,1568037613455_10000_another_file.gif" Groovy import com.onresolve.scriptrunner.runner.customisers.WithPlugin import com.onresolve.scriptrunner.runner.customisers.PluginModule @WithPlugin("com.apwide.document.file-field") import com.apwide.file.api.FileManager; import com.atlassian.jira.component.*; import java.io.ByteArrayInputStream; import java.io.InputStream; import java.nio.charset.StandardCharsets; @PluginModule FileManager fileManager // Size limit of file to upload (ex: 10Mo) long maxFileSize = 10*1000*1000; // create and upload first file String textFileContent = "My first example file" InputStream inputStream = new ByteArrayInputStream(textFileContent.getBytes(StandardCharsets.UTF_8)) String fileId_1 = fileManager.upload("My First example file.txt", inputStream, maxFileSize) // create and upload second file String textFileContent = "My second example file" InputStream inputStream = new ByteArrayInputStream(textFileContent.getBytes(StandardCharsets.UTF_8)) String fileId_2 = fileManager.upload("My Second example file.txt", inputStream, maxFileSize) // Update the customfield import com.atlassian.jira.issue.Issue import com.atlassian.jira.issue.ModifiedValue import com.atlassian.jira.issue.util.DefaultIssueChangeHolder def issueManager = ComponentAccessor.getIssueManager() def issue = issueManager.getIssueObject("HSP-31") def customFieldManager = ComponentAccessor.getCustomFieldManager() def fileField = customFieldManager.getCustomFieldObjects(issue).find {it.name == "file"} // get current value of the file field for an Issue if you need it (file ids. String with following format: "fileId1,fileId2") def currentFileIds = fileField.getValue(issue) if (fileField) { def changeHolder = new DefaultIssueChangeHolder() // update customfield's value using a String containing file ids separated by a comma fileField.updateValue(null, issue, new ModifiedValue(issue.getCustomFieldValue(fileField), fileId_1 + "," + fileId_2), changeHolder) } *** ** * ** *** ## Copy an Attachment to a File Field custom field This ScriptRunner groovy script shows how to copy an existing attachment to a File Field customfield: Groovy import com.onresolve.scriptrunner.runner.customisers.WithPlugin import com.onresolve.scriptrunner.runner.customisers.PluginModule @WithPlugin("com.apwide.document.file-field") import com.apwide.file.api.FileManager; import com.atlassian.jira.component.*; import com.atlassian.jira.issue.attachment.Attachment import com.atlassian.jira.issue.attachment.FileSystemAttachmentDirectoryAccessor import com.atlassian.jira.issue.Issue import com.atlassian.jira.issue.ModifiedValue import com.atlassian.jira.issue.util.DefaultIssueChangeHolder def attachmentManager = ComponentAccessor.getAttachmentManager() def attachmentDirectoryAccessor = ComponentAccessor.getComponent(FileSystemAttachmentDirectoryAccessor.class) @PluginModule FileManager fileManager // Load the issue you want to update def issueManager = ComponentAccessor.getIssueManager() Issue issue = issueManager.getIssueObject("GOT-1") // find attachment by file name String fileName = "Existing Attachment Name.txt" List lastAttachments = attachmentManager.getAttachments(issue) Attachment attachment = lastAttachments.find({ attachment -> attachment.getFilename().equals(fileName) }) log.warn "Found Attachment: ${attachment}" if (attachment){ // get attachment binary file log.warn "Files found in issue folder: ${attachmentDirectoryAccessor.getAttachmentDirectory(issue).listFiles()}" def file = attachmentDirectoryAccessor.getAttachmentDirectory(issue) .listFiles() .find({ it-> it.getName().equals(""+attachment.id)}) log.warn "File found: ${file}" if (file){ // Size limit of file to upload (ex: 10Mo) long maxFileSize = 10*1000*1000; // upload the attachment binary file to File Field and get its unique id String fileId = fileManager.upload(fileName, new FileInputStream(file), maxFileSize) log.warn "FileId of newly updated file: ${fileId}" // find the target File Field to update def customFieldManager = ComponentAccessor.getCustomFieldManager() def fileField = customFieldManager.getCustomFieldObjects(issue).find {it.name == "Existing File Field customfield name"} log.warn "File Field found: ${fileField}" if (fileField) { def changeHolder = new DefaultIssueChangeHolder() // update customfield's value using a String containing the file id fileField.updateValue(null, issue, new ModifiedValue(issue.getCustomFieldValue(fileField), fileId), changeHolder) log.warn "File field successfully updated with the new fileId" } } } *** ** * ** *** ## Copy File Fields to the Jira attachments field Ram Kumar Aravindakshan (Adaptavist) answered this question on the Jira Community: [How to copy the contents of an Apwide File Field to Jira's general attachment field](https://community.atlassian.com/t5/Marketplace-Apps-Integrations/How-to-copy-the-contents-of-an-Apwide-File-Field-to-Jira-s/qaq-p/1726659) We provide an improved version base on his proposal below. For your requirement, you could try using a ScriptRunner Listener. The IssueCreate event / IssueUpdated event can be used to copy the attachment from the Apwide File Field to the Attachment field either during the creation of the Issue or when the Issue is being updated. Below is a print screen of the Listener configuration: ![https://community.atlassian.com/t5/image/serverpage/image-id/148050i0FD8563F12ADE7C9/image-size/large?v=v2&px=999](https://community.atlassian.com/t5/image/serverpage/image-id/148050i0FD8563F12ADE7C9/image-size/large?v=v2&px=999) Below is a Jira10 working sample code for your reference: import com.atlassian.jira.issue.attachment.Attachment import com.atlassian.renderer.util.FileTypeUtil import com.onresolve.scriptrunner.runner.customisers.WithPlugin import com.onresolve.scriptrunner.runner.customisers.PluginModule @WithPlugin("com.apwide.document.file-field") import com.apwide.file.api.FileManager; import com.atlassian.jira.component.*; import com.atlassian.jira.issue.MutableIssue import com.atlassian.jira.issue.attachment.CreateAttachmentParamsBean import com.apwide.document.file.FileDescriptor import org.apache.commons.io.FilenameUtils @PluginModule FileManager fileManager def issue = event.issue as MutableIssue log.warn "Current Issue: ${issue}" def final APWIDE_FILE_FIELD_NAME = "Resume" // set you own Apwide File Field name here def customFieldManager = ComponentAccessor.customFieldManager def attachmentManager = ComponentAccessor.attachmentManager def loggedInUser = ComponentAccessor.jiraAuthenticationContext.loggedInUser def customField = customFieldManager.getCustomFieldObjectsByName(APWIDE_FILE_FIELD_NAME)[0] log.warn "Apwide customField: ${customField}" def customFieldValue = customField.getValue(issue).toString().split(",") as List log.warn "Apwide customField value: ${customFieldValue}" if (customFieldValue.isEmpty()) return for (fileId in customFieldValue){ log.warn "Current file id: ${fileId}" List existingAttachments = attachmentManager.getAttachments(issue) log.warn("Existing attachments: ${existingAttachments}(number of attachments: ${existingAttachments.size()})") if (fileManager.exists(fileId)){ def filePath = fileManager.getPath(fileId) log.warn "File path: ${filePath}" def fileDescriptor = new FileDescriptor(fileId) log.warn "File descriptor: ${fileDescriptor}" log.warn "File name: ${fileDescriptor.fileName}" log.warn "File type: ${fileDescriptor.fileType}" log.warn "File extension: ${fileDescriptor.fileExtension}" log.warn "Thumbnailable: ${fileDescriptor.thumbnailable}" log.warn "User id: ${fileDescriptor.userId}" log.warn "Timestamp: ${fileDescriptor.timestamp}" def sourceFile = new File(filePath) def attachmentParams = new CreateAttachmentParamsBean.Builder() .file(new File(filePath)) .filename(fileDescriptor.fileName) .author(loggedInUser) .issue(issue) .thumbnailable(fileDescriptor.thumbnailable) .createdTime(new Date(fileDescriptor.timestamp)) .copySourceFile(true) .build() Attachment existingAttachmentWithSameName = existingAttachments.find({Attachment it -> it.getFilename() == fileDescriptor.fileName} ) log.warn "Existing attachment with same name: ${existingAttachmentWithSameName}" if (existingAttachmentWithSameName != null){ log.warn "Already existing attachment with same name" if (existingAttachmentWithSameName.getCreated().getTime() == fileDescriptor.timestamp){ log.warn "Exact same file already exists, do nothing" } else{ log.warn "Delete the existing file with the same name" attachmentManager.deleteAttachment(existingAttachmentWithSameName) log.warn "Attach the new file with the same name" attachmentManager.createAttachment(attachmentParams) } } else{ attachmentManager.createAttachment(attachmentParams) log.warn "File successfully added to attachments!" } } } On Jira9, `CreateAttachmentParamsBean` class was not using the builder pattern and you had to use the constructor style to instantiate the attachment parameters: def attachmentParams = new CreateAttachmentParamsBean( sourceFile, fileDescriptor.fileName, null, loggedInUser, issue, null, fileDescriptor.thumbnailable, null, new Date(fileDescriptor.timestamp), true ) Below are some test print screens: * When the Apwide attachment is added, it is automatically added to Jira's attachment, as well as shown in the image below: ![image-20220605-141510.png](https://file-field.apwide.com/__attachments/a_5021b017c5b7d94759d1e9c451d4482c8758d53641dc959f4b415afd7e10786c/image-20220605-141510.png?cb=8b56ec6cbebda48fbda78919aa7bf8a6) * Although the attachment displays as the Actual file name added when it is stored in the Folder, it will display a timestamp as shown in the image below (which is why the Jira attachment appears to be so): ![image-20220605-141524.png](https://file-field.apwide.com/__attachments/a_5e3b6efcc6eb32aeb915e3daa99c26972006188c14682c4dbce663459c521243/image-20220605-141524.png?cb=83189ac429e8d5d7a7c36a4e1a852245) * However, in the Jira attachments folder, it displays as a regular attachment file as shown below: ![image-20220605-141533.png](https://file-field.apwide.com/__attachments/a_b66278924c1a7d1715adaf34f446eaf06176d9fc1bbbcd5ef4996ffcb5e1b1fa/image-20220605-141533.png?cb=3a2369f1d20d1edae4dc760ee5be8967) *** ** * ** *** ## JavaDoc ### String upload(String fileName, InputStream file, long maxFileSize) Upload file * **Parameters:** * `fileName` --- name of the file * `file` --- file content * `maxFileSize` --- max file size allowed (in bytes) * **Returns:** generated unique id of the uploaded file ### boolean exists(String fileId) Check if file exists * **Parameters:** `fileId` --- unique id of the file * **Returns:** true if file exists, false otherwise ### InputStream download(String fileId) throws FileNotFoundException Donwload file * **Parameters:** `fileId` --- unique id of the file * **Returns:** content of the file * **Exceptions:** `FileNotFoundException` --- if file could not be found ### boolean delete(String fileId) throws FileNotFoundException Delete file * **Parameters:** `fileId` --- unique id of the file * **Returns:** true if file was deleted * **Exceptions:** `FileNotFoundException` --- if file could not be found ### String getPath(String fileId) throws FileNotFoundException Get file path from file id * **Parameters:** `fileId` --- unique id of the file * **Returns:** file path of the file * **Exceptions:** `FileNotFoundException` --- if file could not be found *** ** * ** *** ## Java API Interface Java package com.apwide.file.api; import java.io.FileNotFoundException; import java.io.InputStream; public interface FileManager { /** * Upload file * @param fileName name of the file * @param file file content * @param maxFileSize max file size allowed (in bytes) * @return generated unique id of the uploaded file */ String upload(String fileName, InputStream file, long maxFileSize); /** * Check if file exists * @param fileId unique id of the file * @return true if file exists, false otherwise */ boolean exists(String fileId); /** * Donwload file * @param fileId unique id of the file * @return content of the file * @throws FileNotFoundException if file could not be found */ InputStream download(String fileId) throws FileNotFoundException; /** * Delete file * @param fileId unique id of the file * @return true if file was deleted * @throws FileNotFoundException if file could not be found */ boolean delete(String fileId) throws FileNotFoundException; /** * Get file path from file id * @param fileId unique id of the file * @return file path of the file * @throws FileNotFoundException if file could not be found */ String getPath(String fileId) throws FileNotFoundException; } --- version: "latest" variant: "File Field Data Center" language: "en" --- # REST API ## Download an existing file You must use this endpoint and make a **GET**: GET {server:port}/{your-jira-context}/rest/apwide/document/1.0/file/{issueId}/{fieldId}/{fileId} * **issueId**: numerical id of the issue (ex: 10234) * **fieldId**: key of the apwide custom field (ex: customfield_10345) * **fileId** (since version 3.1.+): id of the file to download (ex: 1544184648025_10000_file-field-1.0.5.jar.zip) N.B. you must be authenticated and your user must have permission to view the issue. Check the general documentation of JIRA API below if you are not familiar with that. ![image-20220605-142726.png](https://file-field.apwide.com/__attachments/a_a6ec7b101f3dd92d8fe442234d62932cb13889d69dcd7d382dc5606be0988f88/image-20220605-142726.png?cb=16243a31f816d8ad94849cb93e7a4a97) *** ** * ** *** ## Upload a new file You must make a POST: POST {server:port}/{your-jira-context}/rest/apwide/document/1.0/file?fileName=YourFileName.example * **Body**: content of your file (text or binary) * **fileName**: the desired file name that will be displayed in JIRA It will then return you the *fileId* . The *fileId* is the unique key of the document. It is also the value that is stored in JIRA as the custom field value. You must keep this *fileId* to update your issues in the next step. ![image-20220605-142813.png](https://file-field.apwide.com/__attachments/a_8ead8583c58115709cd2211bbfd728d2dacdd450c88ecb6dc493ee8055b426d1/image-20220605-142813.png?cb=d500dc1ddd8ff277637817221873a5df) *** ** * ** *** ## Update your File Field Customfield with previously uploaded file(s) You must make a PUT: PUT {server:port}/{your-jira-context}/rest/api/2/issue/{issueIdOrKey} Example of body (single file) : JSON { "fields" : { "customfield_10602": "your generated file id" } } Example of body (multiple files, since **version 3.1.+**) : JSON { "fields" : { "customfield_10602": "generated_file_id_1,generated_file_id_2,generated_file_id_3" } } ![image-20220605-142829.png](https://file-field.apwide.com/__attachments/a_f0034ec9d6842e8d88785cb460fbc0a9cbf99e95a31a5a79d4b81a135ff8dce5/image-20220605-142829.png?cb=e3b764e103d79d8474cff269e8a86daf) *** ** * ** *** ## Download an existing file by its unique ID You must use this endpoint and make a **GET**: GET {server:port}/{your-jira-context}/rest/apwide/document/1.0/file/{documentId} * **documentId**: unique id of the file stored in the customfield (ex: 1544184648025_10000_file-field-1.0.5.jar.zip) **N.B. You must be authenticated and your user must have Jira administration permissions**. Check general documentation of JIRA API below if you are not familiar with that. ![image-20220605-140707.png](https://file-field.apwide.com/__attachments/a_58c7fd8bc03597a038c0f40aee20a2a1ec73eff9e539d30cf979187e549bc51e/image-20220605-140707.png?cb=227efebb24947ff2e5c3db4faece022a) *** ** * ** *** ## Remove an existing file by its unique ID You must use this endpoint and make a **DELETE**: DELETE {server:port}/{your-jira-context}/rest/apwide/document/1.0/file/{documentId} * **documentId**: unique id of the file stored in the customfield (ex: 1544184648025_10000_file-field-1.0.5.jar.zip) **N.B. You must be authenticated and your user must have Jira administration permissions**. Check general documentation of JIRA API below if you are not familiar with that. ![image-20220605-140657.png](https://file-field.apwide.com/__attachments/a_c1f4aa39a7fa9e1abc035ec782c21d4d42170e885dd35db90041be24ae01849f/image-20220605-140657.png?cb=7e14b7750d511d79a47331b71ac32e0b) *** ** * ** *** ## Jira Documentation \& Tools General documentation of JIRA API: Check also this free add-on that is very convenient to browse the REST API of JIRA: **Note that you have to disable "Show only public API's" in order to see API's of third party plugins like Apwide File Fields.** Screenshots above were done with the REST API Browser plugin.