# Libraries

Use Libraries to browse and manage shared libraries, folders, and files, then continue
file work from the record that uses a linked file.

## Libraries at a glance

A library is a shared top-level container for organising folders and files. A folder is a
container inside a library, and a file is an item stored in either container. Libraries is
the shared file surface for these items. In PAMS, open Libraries from the **Data** group to
reach the all-files view.

| If you need to… | Go to |
|---|---|
| Understand the conditions that affect what you see | [Before you start](#before-you-start) |
| Browse libraries, folders, and files | [Find and navigate library contents](#find-and-navigate-library-contents) |
| Choose the right maintenance operation | [Create and maintain libraries and files](#create-and-maintain-libraries-and-files) |
| Create a shared library | [Create a library](#create-a-library) |
| Create a folder | [Create a folder](#create-a-folder) |
| Upload a file | [Upload a file](#upload-a-file) |
| Change or remove an existing item | [Edit, open, download, rename, or delete an item](#edit-open-download-rename-or-delete-an-item) |
| Work with files attached to a sales job | [Activities and attachments on a sales job](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/sales-job-activities-and-files) |
| Work with files attached to an MRQ | [Comments, files, and history on an MRQ](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/mrq-comments-files-and-history) |
| Find reference data used by a link | [Reference list](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/reference-list-data) |

## Before you start

Libraries is available as a shared file surface when your subscription includes it.
Your subscription, permissions, saved library contents, and selected records determine
which controls and items appear.

**Prerequisites**

- Have access to the PAMS Data group.
- Know which library or folder should contain the item.
- Have the file name, links, and comment ready when the upload requires them.

If your subscription does not include Libraries, PAMS shows subscription-upgrade content
instead of the file surface. Otherwise, PAMS shows the file toolbar and file surface.
**New Library** appears when the current history contains one item. **New Folder** and
**Upload** depend on the current library context, so they do not appear in every location.

The shared files surface also appears inside parent record screens through the document
popup. The parent record owns that linked-file workflow; Libraries covers the shared file
surface itself.

> **Note:** A missing control can reflect subscription or context rather than a deleted
> feature. Open the relevant library or folder before looking for **New Folder** or
> **Upload**.

## Find and navigate library contents

The Libraries contents view lets you move from libraries into folders and inspect files
in either a tile view or a list view.

**Prerequisites**

- Have a subscription and permissions that expose the file surface.

**Steps**

1. Open Libraries from the Data group.
2. Confirm that the page is the all-files view by checking the `All` readout.
3. Choose a library or folder to move into its contents.

   ![The Libraries page with the All readout and the main file controls](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/48825752d28671a2c896068e49461352.png)

4. Use the view that matches your task.

   | If you need to… | Use |
   |---|---|
   | Browse visual tiles and use the library search box | Tile view; enter a term in the search box with the placeholder `Keyword to Search...` |
   | Compare item details in columns | List view; select **Switch View** |
   | Retrieve older cloud content | **Get old cloud** |
   | Reload the current file list | **Refresh** |

5. In list view, use the visible columns **Name**, **Type**, `Size (B)`, **Tags**, and
   **Modified** to identify an item.

   ![The list view with Name, Type, Size (B), Tags, and Modified columns](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/a10b3d873d2f0cd6f0103398ba5e4cf9.png)

6. Open a library or folder to continue through the hierarchy.
7. Select the item action that matches the item type.

   | Item type | Available item actions |
   |---|---|
   | File | **Open**, **Add/Remove tags**, **Download**, and **Delete** |
   | Folder or library | **Rename** and **Delete** |

8. Select **Refresh** when you need the current list reloaded.

   ![The refreshed Libraries list and its current route](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/0690694c7efb69a0bc932b7aadcd86af.png)

**Result:** You are in the selected library or folder, with its contents shown in the
chosen view. Continue with [Create and maintain libraries and files](#create-and-maintain-libraries-and-files)
when you need to add or change an item.

## Create and maintain libraries and files

Use a library or folder as the place where files belong, then use the item actions for file
details and links.

| If you need to… | Start with |
|---|---|
| Create a top-level shared container | **New Library** |
| Add a container inside the current library | **New Folder** |
| Add one or more files | **Upload**, then **Browse** |
| Add a comment or link while working in a popup | **Add** or **Link** |
| Change file metadata | **Edit**, **Save**, or **Cancel** |
| Download a file | **Download** |
| Change file tags | **Add/Remove tags** |
| Change a folder or library name | **Rename** |
| Remove an item | **Delete** |
| Select an upload file | **Browse** |
| Export from the declared export modal | **Export** |

| Shared popup action | **Save**, **Cancel**, **Upload**, **No**, **Yes**, **Ok**, or **Don't Save** |

Choose the procedure that matches the change you need to make.

### Create a library

**Prerequisites**

- Be on Libraries in a context where **New Library** is available.
- Have the library name and the intended role settings ready.

**Steps**

1. Select **New Library**.
2. In the New Library panel, enter the required name in **Library name**.
3. Review the **Roles** area.

   ![The New Library panel with Library name and the Roles grid](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/26f40ed5348ee649edbceb9a5043337e.png)

4. Use the **Roles** checkbox when you need to select the role area.
5. Select **OK** in the New Library panel when the role selection requires it.
6. Select **Save** to submit the library.
7. If you do not want to create the library, select **Cancel**.

   While the request is processed, PAMS shows `Please wait while PAMS is creating your Library...`.
   If the name duplicates an existing library, PAMS shows `Library Name Already Exists`.
   After a completed request, PAMS shows `Your request was completed successfully`.

**Result:** The New Library panel closes after cancellation or after the save request is
submitted. Continue with [Create a folder](#create-a-folder) or [Upload a file](#upload-a-file)
to add contents.

### Create a folder

**Prerequisites**

- Open the library where the folder belongs.
- Confirm that **New Folder** is available in the current library context.

**Steps**

1. Select **New Folder**.
2. Enter the folder name in the text box with the placeholder `Enter Folder Name..`.
3. Select **Save**.
4. If you decide not to create the folder, select **Cancel**.

   The name is required and pattern-validated. PAMS can show `This Field Is Required` or
   `Just '_'‘-''.' And '&' Characters Accepted`. A duplicate folder name produces
   `Folder Name Already Exists`. During the save request, PAMS shows `Please wait while PAMS is saving your files...`.
   PAMS can also show `Check mandatory field(s)` when required fields are incomplete.
   A completed save shows `Data Saved Successfully`.

**Result:** The folder request is submitted or the New Folder panel is cancelled. Continue
with [Upload a file](#upload-a-file) to add a file to the folder.

### Upload a file

Uploading adds one or more selected files to the current library or folder and lets you
associate links and a comment.

**Prerequisites**

- Open the library or folder where the files belong.
- Have one or more files ready to select.
- Have a file name and any links or comment you want to add.

**Steps**

1. Select **Upload**.
2. Select **Browse** and choose one or more files.
3. Enter the required value in **File Name**.
4. Select a value in **Links** when the file must point to an application record.
5. Enter a comment in **Comment** when you need to preserve additional information.
6. Select **Add** to add the comment.
7. Select **Link** to add the selected link to the file.
8. Select **Upload** or **Save** to submit the upload.
9. If you decide not to upload the file, select **Cancel**.

   PAMS accepts multiple files in the file uploader. It can show `Please Select a file to Upload`,
   `File Nmae is Required`, `File already Exist`, or `File must have atlest one link`.
   During processing, it shows `Please wait while PAMS is saving your files...`.

**Result:** The upload panel is submitted or cancelled, with any validation message shown
beside the condition that stopped submission. Continue with [Edit, open, download, rename,
or delete an item](#edit-open-download-rename-or-delete-an-item) to manage the item.

### Edit, open, download, rename, or delete an item

Item actions let you inspect a file, change its metadata, retrieve it, rename a container,
or remove an item from the current list.

**Prerequisites**

- Locate the existing item in the current library or folder.
- Identify whether the item is a file, folder, or library from **Type**.

**Steps**

1. Select the action that matches the item type.

   | Item type or task | Action |
   |---|---|
   | Open a file | **Open** |
   | Change file tags | **Add/Remove tags** |
   | Download a file | **Download** |
   | Rename a folder or library | **Rename** |
   | Change item details | **Edit**, then change the name or the **Comment** area |
   | Change file links | Use the **Links** area in the edit-file or edit-file-links state |
   | Submit an edit | **Save** |
   | Leave an edit unchanged | **Cancel** |
   | Remove an item | **Delete** |

   PAMS can show `{{Target}} Name is required` when an edited name is empty. It can show
   `Please wait while PAMS is updating your files...` during an update and
   `Please wait while PAMS is deleting your files...` during deletion. A completed save or
     update shows `Data Saved Successfully`; a completed deletion shows `Data Deleted Successfully`.

**Result:** The selected operation is submitted, or the edit is cancelled. The relevant
completion or loading message appears when the operation reaches that point. Continue with
[Refresh or retrieve older cloud files](#refresh-or-retrieve-older-cloud-files) to update
the current list.

### Refresh or retrieve older cloud files

**Refresh** reloads the current list. **Get old cloud** starts a separate older-cloud
retrieval path.

**Prerequisites**

- Open Libraries at the list you want to refresh or retrieve.

**Steps**

1. Select **Refresh** to reload the current list.
2. Select **Get old cloud** when you need to start older-cloud retrieval.

   PAMS can show
   `Please wait while PAMS is getting your files...` or `Please wait while PAMS is downloading your files...`
   while file retrieval is in progress.

**Result:** The current list is refreshed, or the older-cloud retrieval request is started.
The older-cloud result is separate from the current-list refresh. Continue with [Set library
roles](#set-library-roles) when you need to review access.

## Set library roles

Library roles describe which role can view, create folders, edit, delete, upload, or
download within a library.

**Prerequisites**

- Select the library whose role permissions you need to review.
- Have permission to open its Roles surface.

**Steps**

1. Open the selected library's action menu.
2. Select the library's **Roles** action.
3. Review the role grid by its columns.

   | Column | Permission represented |
   |---|---|
   | **Roles name** | The role being reviewed |
   | **View** | Viewing permission |
   | **New folder** | Folder-creation permission |
   | **Edit** | Editing permission |
   | **Delete** | Deletion permission |
   | **Upload** | Upload permission |
   | **Download** | Download permission |

4. Use the role controls that appear in the library roles surface to review or change the
   selected permissions.

**Result:** The library roles surface is open with the role names and permission columns
visible. If a file operation does not complete, continue with [When a file operation goes
wrong](#when-a-file-operation-goes-wrong).

## When a file operation goes wrong

Use the message on screen to identify whether the operation needs a value, a valid name,
a unique item, a file, or a link.

| What you see | What it means | What to do |
|---|---|---|
| `This Field Is Required` | A required name field is empty | Enter the missing library, folder, or file name, then select **Save**. |
| `Just '_'‘-''.' And '&' Characters Accepted` | The entered name fails the name pattern | Replace the name with a value accepted by the name rule. |
| `Check mandatory field(s)` | One or more mandatory fields are incomplete | Check each required field before selecting the committing action. |
| `Library Name Already Exists` | The library name duplicates an existing library | Enter a different library name. |
| `Folder Name Already Exists` | The folder name duplicates an existing folder | Enter a different folder name. |
| `Please Select a file to Upload` | No upload file was selected | Select a file with `Browse`. |
| `File Nmae is Required` | The upload file name is empty | Enter a value in **File Name**. |
| `File already Exist` | The file already exists | Review the current contents before submitting another upload. |
| `File must have atlest one link` | The file has no required link | Add a link with **Links**, **Add**, and **Link**. |
| The Libraries surface is replaced by subscription-upgrade content | Your subscription does not include Libraries | Contact the PAMS administrator about the subscription that provides Libraries. |
| No dialog, message, saved value, or stage/status change appears | The operation did not produce a visible completion outcome | Check the current list and the selected library or folder before repeating the operation. |

If a control is absent, check the current subscription and library context. When the file
is linked to a record, use the operation's owning record page.

## Continue with linked files

The **Link** action adds a selected link to a file. Linked-file work can continue from
parent record screens that include the shared files component; those records own the
record-specific workflow, while Libraries owns the shared file surface.

Continue with [Activities and attachments on a sales job](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/sales-job-activities-and-files),
[Comments, files, and history on an MRQ](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/mrq-comments-files-and-history), or the
[Reference list](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/reference-list-data) page for reference data used by a **Links**
selection.
