# Custom fields

## Custom fields

Custom fields are configurable fields that appear on selected PAMS pages.

| If you need to… | Go to |
|---|---|
| Open the configuration area before choosing a maintenance page | [Configuration dashboard](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-home) |
| Choose the PAMS page whose fields you maintain | [Open Custom fields](#open-custom-fields) |
| Read the fields available on the selected page | [Understand the preview and field tables](#understand-the-preview-and-field-tables) |
| Add or change a field | [Add and save a field](#add-and-save-a-field) |
| Check recorded configuration changes | [Review Last Modifications](#review-last-modifications) |
| Resolve a blocked or unclear field action | [When field maintenance does not work](#when-field-maintenance-does-not-work) |
| Use the configured fields on a sales record | Sales job record |

## Before you start

Custom-field maintenance depends on your subscription, access level, and the information you want
to place on the selected page.

The Custom fields maintenance surface is available when the subscription feature is included. When
it is not included, PAMS shows the upgrade surface instead of the maintenance controls.

Edit actions appear when your permission check returns editable access. View the page with the
access level that permits editing before you plan to add, change, or remove a field.

Have these choices and values ready:

| Information | Where you use it |
|---|---|
| The page to customize | **Choose page you want to customize** |
| The field format | **Data type** |
| The text users see for the field | **Label** |

The page choices are `Account`, `LG`, `Purchase`, and `Sales`. The available data types are `Date`,
`Number`, `Text`, and `Yes_No`.

**Data type** and **Label** are required in the field editor. A required field has a required
marker beside it.

## Open Custom fields

Choose the PAMS page whose configurable fields you want to maintain.

**Prerequisites**

- The subscription feature is included.
- You have editable access for field maintenance.

**Steps**

1. Open the [Configuration dashboard](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-home) in PAMS.
2. Open **Choose page you want to customize**.
3. Select the page you want to maintain.

   | If you need to maintain fields for… | Select |
   |---|---|
   | Account pages | `Account` |
   | Letter-of-guarantee pages | `LG` |
   | Purchase pages | `Purchase` |
   | Sales pages | `Sales` |

   ![Select the page whose fields you maintain](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/c9f469a1f0c6cf715e941564f5a5b6aa.png)

4. Confirm that the selected page's preview appears.

**Result:** Custom fields is open from the Configuration dashboard, the selected page is shown in
**Choose page you want to customize**, and its preview is available.

## Understand the preview and field tables

The preview shows the fields available on the selected PAMS page, grouped into the page areas that
PAMS presents for that selection. Use it to locate the area where a custom field belongs before you
open the field editor.

For the selected **Sales** page, the preview showed these fields:

| Field 1 | Field 2 | Field 3 |
|---|---|---|
| `Branch` | `Sales Responsible` | `Product Type` |
| `Job Title` | `Time Frame` | `End User` |
| `Estimated Value` | `In Branch Currency` | `File No.` |
| `Client` | `Vendor` | `Client Inquiry Number` |
| `Inquiry Date` | `Bid Due Date` | `Requested Offer Type` |
| `Offer No.` | `Offer Type` | `Offer Date` |
| `Validity Period` | `Delivery Time` | `Delivery Term` |
| `Payment Method` | `Payment Period` | `Client Order No.` |
| `Vendor Order No.` | `Order Date` | `Order Activation Date` |
| `L/C Number` | `Shahawy Extra` | |

These fields appeared in more than one preview section:

| First repeated field | Second repeated field | Third repeated field |
|---|---|---|
| `Client` | `Vendor` | `Bid Due Date` |
| `Delivery Time` | `Delivery Term` | `Payment Method` |
| `Payment Period` | | |

The preview appears after you select a page.

![Locate preview sections and field actions](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/28d33f272556523622e10e268c1617ca.png)

Work from the field names and sections shown in the preview. The preview content depends on the page
you select and the configuration for that page. `Which Section` is not available as a choice on this
screen. When you have located the section, continue with [Add and save a field](#add-and-save-a-field).

## Add and save a field

Add a custom field when the selected page needs another labelled value. Edit an existing field when
its label needs changing; an existing field's **Data type** is disabled while it is edited.

Use the appropriate path:

| If you need to… | Start with… |
|---|---|
| Add a field | **Add custom field** in the preview section where the field belongs |
| Change a field's label | Select the existing field, then **Update custom field** |

**Prerequisites**

- Custom fields is open with the target page selected.
- You know the field's **Data type** and **Label**.
- You have editable access.

### Add a new field

1. Select **Add custom field** in the preview section where the field belongs.
2. Open **Data type**.
3. Select the data type that matches the value.

   | If the field stores… | Select |
   |---|---|
   | A calendar date | `Date` |
   | A numeric value | `Number` |
   | Free text | `Text` |
   | A yes/no value | `Yes_No` |

   ![Choose the field's data type](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/775d5c7384292e312d8e5c1ed8070c2c.png)

4. Enter the text users should see in **Label**.
5. Select **Save**.

   When the new field is saved, PAMS uses the message `Saved`.

6. Check the preview for the new label.

**Result:** The new field is submitted, and the preview is the place to check whether its label
appears.

### Change an existing field

1. Select the existing field in the preview.
2. Select **Update custom field**.
3. Enter the revised text in **Label**.
4. Select **Save**.

   When the existing field is updated, PAMS uses the message `Field updated successfully`.

5. Check the preview for the revised label.

**Result:** The changed label is submitted, and the preview is the place to check the revised field.

Select **Save and Close** when you want to save a field change and leave the maintenance page in the
same action.

After checking the preview, continue with [Review Last Modifications](#review-last-modifications) or
[When field maintenance does not work](#when-field-maintenance-does-not-work).

![Enter a data type and label in the field editor](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/e15499b0363772afe4844dca16bfd5b3.png)

## Review Last Modifications

**Last Modifications** is the audit-history area for actions recorded against custom-field
maintenance. It is available when both `companyId` and the log-module identifier are present.

**Prerequisites**

- Custom fields is open.
- The company and log-module identifiers are available.

**Steps**

1. Select **Last Modifications**.
2. Read the audit history in chronological order.

The audit-log text says: `The audit log provides you with a chronological sequence of actions performed by the users`.

**Result:** The audit-history area is open with the recorded actions presented as a chronological
sequence.

If a field action is blocked or unclear, continue with [When field maintenance does not work](#when-field-maintenance-does-not-work).

## When field maintenance does not work

Use the message on screen to distinguish a value that needs correction from an action that the
current subscription or access level does not permit.

| What you see or cannot select | What it means | What to do |
|---|---|---|
| `This field is required` | A required field in the editor is empty. | Enter a value in **Data type** or **Label**, then submit the form again. |
| `repeated field` | A field with the same data type and label already exists in the same section. | Change **Data type** or **Label**, then submit the form again. |
| **Choose page you want to customize** is unavailable and the upgrade surface appears. | The subscription feature is not included. | Contact the person who manages your PAMS subscription. |
| Edit actions are unavailable. | The permission check did not return editable access. | Sign in with access that permits field editing, or contact your administrator. |
| `Error occurred while saving field` | The save action returned a save error. | Check the field values and submit the save action again. |
| `Error occurred while updating field` | The update action returned an update error. | Check the revised label and submit the update again. |
| `Error occurred while removing field` | The remove action returned a removal error. | Do not treat the field as removed; resolve the error before continuing. |
| A close action asks whether to save changes. | The page has unsaved changes. | Choose a leave-page choice in [Continue after maintaining fields](#continue-after-maintaining-fields). |
| **Which Section** is not available. | That choice is not available on this screen. | Choose the preview section that PAMS presents. |

The field editor also provides **Ultimate delete this field** for an edited field and **Delete** to
remove a saved field after confirmation. A successful removal uses the message `Field removed successfully`.

## Continue after maintaining fields

Leave the maintenance page after you check the field preview or decide whether to keep the change.

**Prerequisites**

- A field editor or the Custom fields page is open.
- You know whether to keep or discard unsaved changes.

**Steps**

1. Select **Close** when you want to leave the field editor.
2. If PAMS asks `Do you want to save your changes?`, select the appropriate choice.

   | If you need to… | Select |
   |---|---|
   | Leave without saving | **Don't Save** |
   | Save before leaving | **Save** |
   | Remain in the editor | **Cancel** |

3. Select **Close** when you want to leave the maintenance page after the field editor is closed.

**Result:** The selected leave-page choice is applied, and you can continue from the Configuration
dashboard or the page that uses the configured fields.

After maintaining fields, use Sales job record to see where fields configured for the Sales page are
used. Return to the [Configuration dashboard](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-home) when you need to choose
another configuration area.
