Uploading Files And Images

Most applications need documents attached to records: a signed contract on a deal, scanned delivery notes on an order, a photograph on a damage report, a CV on an applicant. This chapter covers every part of that — getting a file into the application, seeing it once it is there, replacing it, removing it, and what to do when an upload will not work.

What This Is

A file field is a field on a record that holds one or more files. An image field is the same thing for pictures, with the extra behavior that it shows you the picture rather than a link.

You will meet files in four places:

• On a record's form, when you create or edit it. This is where uploading happens.
• On a record's detail screen, where saved files appear as download links or picture previews.
• In lists, where a file or picture field can be one of the columns.
• In the File repository, a separate screen that shows every file the application holds, if your application has that screen and you are allowed to open it.

How each field behaves depends on how your administrator set it up. Two file fields in the same application can look completely different from each other, and that is normal.

Why It Matters

A file attached to a record is part of that record's story. It is also the part most easily lost: the file travels to storage while you are still filling in the form, but it only becomes part of the record when you save the record. Most of the trouble people have with attachments comes from that gap, so it is worth understanding before you upload anything important.

Which Uploader You Get

There are two quite different upload experiences, decided per field by your administrator. You cannot tell which one you will get before you open the form, so it helps to recognize both.

The Uploader Panel (The Common One)

This is the default. The field shows its label at the top, any files already attached below that, and a button at the bottom. The button's wording depends on what the field accepts:

Clicking the button slides open a panel between the label and the list of files — a bordered box, roughly the height of a few form rows, with a large drop area inside it. That panel is the uploader. Clicking the button again slides it shut; it does not throw away what is inside.

Some fields are set up to have the panel already open when the form loads. That is a per-field setting, not something you choose.

The Plain File Box And The "Erase?" Tick

The other rendering is an ordinary browser file box — the kind with a small button that opens your computer's file picker and shows the chosen file name next to it. There is no drop area, no progress bar and no panel.

When you edit a record whose plain-box field already holds a file, you see two extra things:

• A link under the box with a small document icon and the current file's name. Clicking it opens the file in a new browser tab.
• An "Erase?" checkbox. Ticking it and saving removes the current file and leaves the field empty. It only appears when the field is not required and there is something to erase.

On a plain box that takes a single file, choosing a new file and saving replaces the current one. Nothing is sent until you save the form — the whole file travels with the form submission, which is why a large file on a plain box can make saving feel slow or fail outright.

Example An HR record has a Photo field rendered as a plain box. The employee's old photo is linked under it. To swap the photo, the HR officer picks the new file and clicks Save — one action, one save. To remove the photo entirely without adding a new one, they tick Erase? and save.

A Variant With A "Leave Empty To Keep Current" Note

A small number of fields are set up for stricter document handling. They always use the plain box, take a single file, and show the note "Leave empty to keep current." underneath while you edit. That is exactly what it means: leave the box alone and the existing file stays. These fields also offer the Erase? tick when they are not required.

Using The Uploader Panel

Getting Files Into The Panel

Two ways, and they can be mixed:

1. Drag files onto the panel from your desktop or a folder window. The drop area highlights as your files pass over it.
2. Click inside the panel to browse your computer with the standard file picker. You can select several files at once there if the field accepts more than one.

Each file you add appears in the panel with a small preview (for pictures), its name and its size, and a control to take it back out again.

The panel will not hold more files than the field allows. If the field takes a single file, a second one is refused with a short message rather than added.

Starting The Upload

By default nothing is sent until you press the panel's upload button, which sits at the bottom of the panel and names how many files it will send. Until you press it, the files are only selected, not transferred.

Some fields are set up to start uploading the moment a file is added. If you see progress bars begin by themselves, that is what has happened, and there is nothing you need to press.

Watching Progress

Each file gets its own progress bar with the transfer speed and an estimate of the time left.

Files are sent one at a time. If you add twelve files, the first one uploads while the rest wait their turn, then the second, and so on. This is deliberate and cannot be changed. It means a batch of large files takes as long as all of them added together, and it means a stuck file holds up the ones behind it.

Files above roughly 30 MB are broken into pieces and sent piece by piece. This is invisible except that the progress bar for such a file moves in steps rather than smoothly, and that a failed piece is retried by itself rather than restarting the whole file.

Pausing, Canceling And Retrying

• Canceling one file: the small cross on its row takes it out. If it had already finished uploading, the application also deletes what was uploaded, so the cross is a real removal and not just a tidy-up of the list.
• Retrying: a file that fails shows an error state on its own row with a retry control. Use it rather than removing the file and adding it again — the rest of the batch is unaffected.
• Pausing: while a file is in flight the panel may also offer a pause control on its row. If it does, pausing holds the transfer and the same control resumes it. A pause only lasts as long as the page stays open.

The application retries a failing transfer a few times by itself, with short gaps, before it gives up and shows you an error. A row that seems to hang for a few seconds may simply be mid-retry.

The Green List — What "Uploaded" Really Means

As each file finishes, a green row with a small cloud-and-tick icon appears underneath the panel, outside it, carrying the file's name. That green list is the important one. It means:

This file has reached storage. It is not on the record yet.

The file becomes part of the record when you save the form. After the save, the file moves up into the field's own list of files and is marked with a small green new badge so you can see what this save added.

If you leave the form without saving — closing the pop-up, navigating away, clicking Cancel — the green rows are discarded and nothing is attached. Uploading on its own does not count as an unsaved change, so the pop-up's usual "you may lose unsaved changes" prompt does not appear unless you also edited some other field. The file itself stays in storage but is attached to nothing, and no screen will show it to you again.

So: never treat the green row as "done". Save the record.

If The Form Reloads While You Are Working

Some forms redraw themselves when you change certain fields (a status, a category), because other fields depend on the answer. When that happens, the green list is rebuilt from what the server already holds, so uploads that had finished are not lost. Each rebuilt row gains a small red cross so you can still take a file back out.

Uploads that were still in progress at that moment are a different matter — see below.

Leaving In The Middle Of An Upload

The application does not warn you when you navigate away, close the tab or close the window while an upload is running. The browser will not ask "are you sure". The transfer simply stops, and nothing is attached.

The same is true of anything that replaces the form on screen while a transfer is running.

There is no resume after a reload. Coming back to the form gives you an empty uploader; you start the file again from the beginning. Keep the tab open and the computer awake until the green rows appear, particularly for large files on a slow connection.

Uploads Left Unfinished Expire

An upload that is started but never saved onto a record does not wait for you indefinitely.

• The permission your browser is given to write one file to storage lasts about an hour from the moment that file starts transferring. A single transfer still running after that fails. This only bites very large files on very slow connections.
• A file that uploaded successfully but was never saved onto a record is forgotten after a while. Saving the form long afterwards can then save the record with the field empty and without any error message.

The practical rule: add files, upload them and save within one sitting. If a form has been sitting open for a long time, reload the page and upload again rather than trusting the green rows.

Example A project manager opens a Contract record before lunch, drags in a 40 MB signed PDF and waits for its green row, then gets pulled into meetings and leaves the tab open overnight. The next morning they click Save. The record saves, no error appears, and the Contract field is empty. The fix is to reload the record's form and upload the PDF again — and this time save straight away.

What You Are Allowed To Upload

Kinds Of Files

• Image fields accept pictures only. Dragging a spreadsheet onto an image field is refused immediately, in the panel, before anything is sent.
• Document fields normally accept anything, unless your administrator built the form with a specific list of accepted kinds. Custom-built forms are the one place where a list of allowed types can be set, so if a document field is refusing your file type, that form was configured that way on purpose.

The panel does not spell the rules out before you start. In practice you discover a restriction by hitting it.

Size

Any file field can be given a maximum size by your administrator. The limit is not shown anywhere until you exceed it.

Independently of that, the machine hosting your application has its own ceiling on files sent through the plain file box (the second rendering). That ceiling is set by whoever runs the application, not inside the application, so nobody can tell you the number from the screen. Its symptom is a save that fails oddly or a field that simply comes back empty — that is one of the reasons the uploader panel is the better rendering for large files.

When A File Is Refused

A file the panel will not accept is rejected on your computer, before it is sent. You get a short message naming the file and the rule it broke — too large, wrong kind, or too many files for this field — and the file is not added to the list.

On the plain file box the check happens differently: the form comes back with an error under the field, typically saying the file is too large and naming the maximum allowed, or — on an image field — saying the file must be a picture in one of the usual picture formats.

What To Do About A Refused File

In rough order of how much trouble each one is:

1. Check what you actually picked. Photo libraries and scanners produce surprising formats; a file named scan.pdf on your desktop can be a different type inside.
2. Reduce the size. Re-export a PDF at a lower quality, or resize a photograph. A phone photograph is often several times larger than anything the record needs.
3. Put it in a zip. If the block was on the file type, an archive is a different type and is often smaller too — though your colleagues will have to unzip it to read it.
4. Split it. If the field accepts several files, three smaller PDFs may pass where one large one did not.
5. Ask your administrator to raise the limit. The size limit is a single setting on the field. Widening the list of accepted types is only possible on custom-built forms. Tell them which field, on which record type, and what you were trying to attach.

Pictures: Previews And Thumbnails

When you add a picture to the uploader panel, the panel shows you a preview of it straight away. That preview is made in your browser and proves only that the file is a picture.

Once saved, an image field on the record shows a thumbnail — a smaller copy the application generates when the picture is stored. Thumbnails are made to fit a size your administrator chose for the whole application. Several pictures in one field are shown side by side at half width each.

Clicking a thumbnail on a record opens the picture enlarged over a darkened page rather than in a new tab. Pictures open one at a time, even when the field holds several — there is no gallery to page through, so close the overlay and click the next thumbnail. Close it with the cross, by clicking the dark background, or with Esc.

A few things worth knowing:

• A broken-image icon where a thumbnail should be, while the picture itself still opens correctly, means the small copy was never produced. The original is safe. Report it, because it will not fix itself.
• Some image fields are set to compress pictures before uploading, which re-encodes them to a smaller web format. If a photograph comes out smaller or in a different format than the one on your disk, that is why.
• How pictures and file links appear in list screens — the height they are capped at, what a designated thumbnail column does — is covered in Cards, Lists And File Lists.

Managing What Is Already Attached

Opening And Downloading

On a record, each stored document appears as a link with a small cloud-download icon and the file's name. Clicking it opens the file in a new browser tab. Whether your browser displays the file or downloads it depends on the file type and on your browser's own settings — that choice is not the application's.

Removing A File

Next to a file you are allowed to change, a small red trash icon appears.

Treat it with care. Clicking it:

• removes the file with no confirmation dialog,
• normally deletes the stored file for good, and
• saves the change to the record immediately, without waiting for you to save the form.

There is no undo. Clicking Cancel on the form afterwards does not bring the file back. If you are inside an edit form and you remove a file, that removal has already happened.

Two related quirks:

• On a field that is required and holds only one file, the trash icon may still be shown inside the edit form, and the row may even fade out when you click it — but the removal is refused, and the file is back after a refresh. Attach the replacement first, then remove the old one.
• On a field that holds several files, removing one leaves the others untouched.

Replacing A File

There is no dedicated "replace" control. Replacing means uploading, and the result depends on the field:

That difference catches people out. If you meant to swap one of several attachments, upload the new one, save, then delete the old one with its trash icon.

Several Files And Their Order

When a field holds more than one file and you are allowed to change it, each row gets a grip handle on its left. Dragging a row up or down changes the order the files are stored in, which is the order everyone else sees them in.

The new order is saved the moment you drop the row. You do not submit anything, and there is no undo.

One exception: dragging on a create form, before the record exists, does nothing permanent. Save the record first, then set the order.

When The Controls Are Not There

If a file is shown as a plain link, with no trash icon and no grip handle, you are not allowed to change that field. Other people on other roles may see those controls on the same screen. That is normal and is covered in Roles, Groups And Permissions.

Who Can Open A File Link

Unless your administrator turned on short-lived links for that field, the address of a stored file is a plain, permanent web address. Anyone who has that address can open the file, whether or not they can sign in to your application. Treat file links you paste into emails or chat as public.

Where short-lived links are switched on, the opposite problem appears: the links on a page go stale after about an hour, and clicking one on a page you left open all morning gives you an error from the storage service instead of the file. Reload the record and click again.

Pictures And Files Inside A Rich-Text Box Or A Comment

Rich-text fields and the comment box on a record have their own, separate way of taking files, using the small toolbar above the writing area:

• The picture button inserts a picture into the text.
• The attach-file button (tooltip "Attach file") opens your computer's file picker and, when the upload finishes, inserts the file as a small attachment block in the text with a link to it. A thin blue progress bar appears in the editor while the file goes.
• Pasting a picture straight from the clipboard — a screenshot you just took, for instance — does not work. Save it as a file first, then use the button.

Pictures added this way are shrunk and re-encoded before they are sent: down to a maximum width of about a thousand pixels. A large screenshot will therefore appear slightly softer than the original. Animated GIFs are left alone. This applies to rich-text and comment uploads only, not to image fields.

If one of these uploads fails you get a small browser alert box saying something short like "Upload failed" or "Upload error". Retry; if it keeps failing, the causes are the same as for the uploader panel.

The discussion panel itself is covered in Comments And Mentions.

The File Repository

Some applications have a File repository screen, usually in the administrative part of the navigation. It is a browser over every file the application holds, both files attached to records and files that stand on their own.

Whether it exists at all, and whether you can open it, is decided per application and per role. If you cannot see it in the navigation, it is either not part of your application or not part of your role — there is no message telling you which.

What The Screen Shows

• A folder panel down the left, with a home folder at the top and the current folder's neighbors and children below it. You can drag its right edge to make it wider.
• A toolbar with breadcrumbs showing where you are, a search box (placeholder "File name…"), a filter button, and a switch between Cards, List and Table display.
• The files themselves, each with an icon, its name as a link, a badge reading Standalone or Attached, its size, the date it was last changed, and where it lives.

Standalone means the file was uploaded into the repository itself and belongs to no record. Attached means it is a file on a record's field; the location column then links to the record it belongs to and names the field, and clicking it opens that record.

Files are shown 100 to a page.

Finding A File

Type into the search box to match on file name only. The search always covers the whole repository, ignoring the folder you are standing in, so a search result may be somewhere quite different from where you were looking. It matches on a fragment of the name, so deliv finds delivery-note-4471.pdf.

The filter button narrows the list to files attached to a particular kind of record, and then to a particular field on it. The field list stays disabled until you have picked the kind of record.

Both the search and the filter replace the breadcrumbs with chips describing what is active, each with a cross to clear it.

Uploading Into The Repository

The Upload files button opens a window with the same uploader panel, already open and set to start uploading as soon as you add files.

The critical part is the end: press Finish, not Close. Finish is what turns the uploaded files into repository entries in the folder you were standing in. Pressing Close after uploading leaves the files nowhere — exactly the same trap as leaving a record form without saving.

A successful finish shows a confirmation message. If a file took too long to get there, you may instead see "Upload session expired. Please retry the upload.", which means what it says.

Organizing

• Folders: create one with the New folder button or the small plus in the folder panel. Rename, move and delete them from the small menu that appears on a folder row. Deleting a folder does not delete its files, and the confirmation tells you they will be moved to the parent folder. A folder that still contains sub-folders cannot be deleted; empty it first.
• Moving and renaming files: use the menu on a file row, select several files and use the move button, or drag a file row onto a folder in the left panel or onto a breadcrumb. Dragging is mouse-only; it does not work by touch.
• Selecting files: the per-row checkboxes are invisible until you hover over the row, so only the select-all box above the list is visible at rest. Hover, tick what you want, and the bar above the list changes to show how many are selected along with move and delete buttons.
• Pinning: if your role allows it, a file or folder can be pinned, which locks it — pinned items cannot be moved, renamed or deleted, and their icon gains a lock. This is the way to protect something everyone relies on.

Deleting From The Repository

• A standalone file asks "Delete this file? This cannot be undone." and is then gone.
• An attached file warns you that it belongs to a record and names the record and the field, and tells you that deleting it will clear that field. Confirming does both.
• Deleting several at once quietly skips attached files. Only standalone files are removed. The count in the message that appears afterwards is the only clue that fewer files went than you selected. Delete attached files one at a time.

Can You Attach An Existing Repository File To A Record?

Not from a record's form. There is no picker on a file field that browses the repository, so a file already in the repository has to be uploaded again to the field that needs it. The repository is a place to find and organize files rather than a library you attach from.

If your work depends on reusing the same documents across many records, that is worth raising with your administrator as a requirement.

Display Settings That Surprise People

• Sizes are shown in plain bytes, with no conversion. A 2 MB file reads as a seven-digit number.
• Dates use a day-month-year format with dots, such as 5. 3. 2026, regardless of your language.
• The repository shows no picture thumbnails. Every file, pictures included, gets the same generic file icon.
• The Cards / List / Table choice is remembered for your current session on this device only.

Worked Example: Three Scanned Delivery Notes On An Order

An order clerk has just scanned three delivery notes and needs them on order SO-2291.

1. Open the order and put it into edit mode, or use whichever action button on the record adds attachments. The Delivery notes field accepts several files and shows a Choose files button.
2. Click Choose files. The uploader panel slides open.
3. Drag all three scans onto the panel in one go. Three rows appear with their names and sizes. One of them is 45 MB, because the scanner was set to a high resolution.
4. Press the panel's upload button. The first file uploads while the other two wait. The 45 MB scan moves in steps and takes noticeably longer than the others.
5. The 45 MB scan fails partway with an error on its row. The clerk clicks retry on that row only. It succeeds the second time.
6. Three green rows with cloud-and-tick icons now sit under the panel. Nothing is on the order yet.
7. Save the order. The three files move into the field's own list, each with a small green new badge.
8. Fix the order. The scans went in alphabetically, but note 2 should be second and it is currently third. The clerk drags its grip handle up one row. That change is saved on the drop; no second save is needed.
9. Note 1 has to be rescanned because the first page was crooked. The clerk uploads the new scan — which is added alongside the others, not in place of them — saves, and then clicks the red trash icon on the old copy. It disappears immediately and permanently: no confirmation, no undo.

What would have gone wrong at each hazard: closing the pop-up at step 6 would have lost all three files silently; leaving the tab during step 4 would have aborted the transfer with no warning; and clicking the trash icon at step 9 on the wrong row would have been unrecoverable.

When An Upload Will Not Work

Clicking The Button Does Nothing, Or Opens An Empty Box

The uploader is fetched from the public internet when a page needs it. On a corporate network with a strict proxy or filter — or behind an aggressive ad blocker — that fetch is blocked, and the panel is never built. What you see is a button that toggles an empty area, with no error message anywhere naming the cause.

Tell-tale signs that this is what is happening: icons missing across the whole application, date fields showing as plain text boxes, and charts rendering blank. Those things come from the same place. If all of them are broken at once, it is the network, not the application.

What to tell your administrator: "The file uploader, the date pickers and the icons are all not loading on our network. Something is blocking the external resources the application fetches. Can we allow them through, or host them internally?" There is more on this pattern in When Something Goes Wrong.

Meanwhile, a field rendered as a plain file box still works, because it does not need the uploader.

The Upload Starts And Then Fails, With No Explanation

The panel reports failures without saying why. The three common causes, in order of likelihood:

1. You are not allowed to attach files to that field. A permission refusal looks exactly like a generic upload failure. If every file fails immediately on one particular field but uploads fine elsewhere, this is almost certainly it.
2. The transfer ran past its hour. A single file has about an hour to reach storage once it starts moving. Reload the page and try again on a faster connection, or send a smaller file.
3. The connection dropped partway. Use the retry control on the failed row.

The Upload Is Very Slow

Files go one at a time, and large ones go in pieces. There is nothing to tune from your side. Practical measures: upload fewer files at once, upload from a wired or stronger connection, reduce the size at source (scan at a lower resolution, export a lighter PDF), and keep the tab in the foreground with the machine awake.

If you must send something very large, expect to sit with it. There is no background upload and no resume.

The File Saved, But Its Link Goes Nowhere

Occasionally the storage service is busy at the moment a file is saved. The file is queued and stored a little later by the application itself. Until that happens, the link on the record leads nowhere. Wait a few minutes and reload the record. If it is still dead an hour later, report it.

The Record Saved But The File Is Not There

Two known causes:

• The upload had expired before you saved (see above). Nothing is attached and nothing is reported.
• On a required file field using the uploader panel, the form does not actually enforce that a file is present. You can save such a record with the field empty. Check the field after saving, particularly on records you will not look at again.

A File Is Missing From The File Repository

Attached files are added to the repository automatically as records are saved, but that step can fail quietly. The file itself is fine — it is on its record — but it does not show up when you browse or search the repository. Ask your administrator to rebuild the repository index; the control for that is only available to the most privileged account.

Tips And Gotchas

• Green means uploaded, not attached. Save the record. In the repository, press Finish.
• The trash icon has no confirmation and no undo, and it saves the record as it goes.
• Reordering saves on drop. Do not drag files around to "see what it looks like".
• Multi-file fields add, they never replace. Upload the new file, then delete the old one.
• Nothing warns you about an unsaved upload when you leave. Not when navigating away, not when closing the tab, not when an upload is running.
• There is no resume. A reload starts every unfinished file from zero.
• Never trust a long-open form. Reload before uploading if the page has been sitting there.
• File links are usually public. Anyone with the address can open the file.
• Removing a file from the uploader panel after it has uploaded really deletes it from storage. That is the right way to undo an upload you had not saved yet.
• A file uploaded and then abandoned is invisible waste. It is not on any record and not in the repository; nobody can find it or clean it up from the screens.

What To Ask Your Administrator For

Nothing on this page is something you can change yourself. These are the requests worth making; most of them are a single setting on the field:

• "Can this field accept larger files?" — name the field, the record type, and the size you need.
• "Can this field accept ?" — only answerable on custom-built forms, where the list of accepted kinds is a setting. An image field always accepts pictures only.
• "Can this field take several files instead of one?" — or the reverse.
• "Can the uploader be open when the form loads?" — saves a click on fields used constantly.
• "Can uploads start automatically when I add a file?" — removes the separate upload press.
• "Can pictures on this field be compressed automatically?" — useful where people attach phone photographs.
• "Can file links on this field expire?" — the answer to "our attachments are readable by anyone with the link".
• "Can we have access to the File repository?" — it is a separately licensed screen, granted per role.
• "Can you rebuild the file repository index?" — when a file exists on a record but cannot be found in the repository.
• "Can I attach an existing repository file to a record?" — today you cannot; it is worth registering as a need.

A fuller catalog is in What To Ask Your Administrator For.

Related Chapters

• The Fields You Will Meet
• Creating And Editing Records
• Pop-Up Windows
• Cards, Lists And File Lists
• When Something Goes Wrong