> **Source:** https://knowledge.leegality.com/document-execution/workflows/v4/excel-upload/custom-mapping
> **Site:** Leegality Knowledge Base — https://knowledge.leegality.com
> **About:** Leegality is a document execution platform covering eSigning, stamps, NeSL, workflows, and REST API integration.
> **Navigation:** Every article on this site has a plain-text version at `<article-url>.txt` (this format). To get an index of all articles with their `.txt` links, read: https://knowledge.leegality.com/llms.txt
> **AI Guide:** For instructions on how to navigate this knowledge base as an AI agent, read: https://knowledge.leegality.com/ai-readable.txt

---
# Custom Mapping

Custom Mapping lets you upload your own spreadsheet instead of the Leegality Excel template. You match each Leegality column header to a column in your spreadsheet once, and every later upload to that workflow uses the same mapping.

Custom Mapping is set per workflow, from the workflow details page. To open it, see Open the workflow details page.

## Create a custom mapping

1. On the workflow details page, click the **Custom Mapping** icon.
2. Upload your spreadsheet. (Supported formats: **.xls** and **.xlsx**.)
3. Click **Proceed**.

    The mapping screen opens. The left column lists the **Leegality Excel Column Headers**, written in the same format as the v4 API parameters (for example, `pack.packName`). The right column has a dropdown for each, listing the headers found in your spreadsheet.

4. For each Leegality column header you want to use, select the matching header from your spreadsheet in the dropdown.
5. Save the mapping:
    - **Save as Draft** — save your progress and come back later. You do not have to finish the mapping in one go.
    - **Save & Activate** — save the mapping and start using it for uploads.

> **Info — Start your data from row 2**
>
> Once a custom mapping is active, your spreadsheet only needs a single header row. Start entering pack data from **row 2**.

### Find fields on the mapping screen

The mapping screen groups headers into **Pack Details**, **Document Details**, and **Invitee Details**, and shows how many fields are mapped so far (for example, *7 of 31 fields mapped*). To find a field quickly:

- Search for a header in **Search column headers**.
- Use the **Field Type** filter to show only **unmapped fields**, only **conflicting** fields, or a single group such as **Pack Details**, **Document Details**, **Invitee Details**, or **CC Details**.

## Manage an existing mapping

Click the **Custom Mapping** icon on the workflow details page again. You get three options:

- **Edit Existing Mapping** — change the mapping that is currently active.
- **Start Afresh** — delete the existing mapping and create a new one from scratch.
- **Delete Mapping** — permanently remove the custom mapping.

## Add new columns to a mapping

If your spreadsheet gains a new column, you can map it without redoing the mappings you already have.

1. Click the **Custom Mapping** icon, and select **Edit Existing Mapping**.
2. Click **Upload Excel** at the top of the mapping screen.
3. Upload a spreadsheet that contains your **new columns plus all the columns you already mapped**, and click **Proceed**.
4. Map the new columns, and save the mapping.

### If previously mapped columns are missing

If the new spreadsheet is missing a column that was already mapped, Leegality warns you before continuing and lists the missing headers.

- **Go Back** — upload a spreadsheet that still has those headers. Your existing mappings are kept.
- **Proceed Anyway** — continue with the new spreadsheet. The mappings that used the missing columns become **conflicting** mappings.

A banner on the mapping screen shows how many mappings are conflicting. To resolve them:

1. In the **Field Type** filter, select **Show only conflicting**. Each conflicting mapping is marked **Not in the new Excel**.
2. Click **Dismiss** on each conflicting mapping.
3. Map those fields to columns in the new spreadsheet, if needed.

> **Warning**
>
> You must dismiss every conflicting mapping before you can save.

## Drafts of an active mapping

If you edit an active mapping and click **Save as Draft**, the workflow keeps two versions:

- **The active mapping** — still used for uploads.
- **The draft mapping** — your unsaved changes.

To put the draft into use, open it and click **Save & Activate**. To discard it, click **Revert to Activated**. This returns the mapping to the active version.

<!-- TODO: confirm that uploads made while a draft exists use the active mapping, and what happens to uploads if a workflow has only a draft mapping (never activated). -->