# Documents Import

Source: https://docs.astalty.com.au/guide/imports/documents-import

> Prepare a requested bulk Document import for Astalty to run.

## Overview

The Documents import is available on request and is not self-service. Astalty runs it after reviewing your mapping CSV and document files. Contact <imports@astalty.com.au> to arrange the transfer and confirm any applicable service details.

## Files to Prepare

1. A mapping CSV with one row per Document.
2. The Document files in the same folder structure used by **document\_path**.

Download the current example from **Settings > Imports > Create Import > Documents > Download Example File**. Create the referenced Users and Participants first.

## Mapping File Columns

Required columns are **target\_reference\_type**, **target\_reference**, and **document\_path**.

Optional columns are **document\_name**, **date**, **expiry**, **record\_type**, **record\_reference**, **categories**, **status**, and **external\_id**.

### Target Reference Type and Target Reference

Supported target types are:

| Value                         | Reference               |
| ----------------------------- | ----------------------- |
| **participant\_ndis\_number** | Participant NDIS Number |
| **participant\_id**           | Astalty Participant ID  |
| **participant\_external\_id** | Participant External ID |
| **user\_email**               | User email address      |
| **user\_id**                  | Astalty User ID         |

An unresolved target gives the row an **Invalid Target** result. It is not attached to another record automatically.

### Document Name and Document Path

**document\_name** is the title shown in Astalty. If blank, the source file name without its extension is used. **document\_path** is relative to the transfer root and must exactly identify the supplied file.

### Linked Record, Expiry and Reference

- **expiry** uses *dd/mm/yyyy* and is recorded on a Participant Record or User Record linked to the Document. The Record Type must support expiry.
- **record\_reference** is saved as the Reference on a linked Record. For a new Document, supplying it without **expiry** creates a non-expiring linked Record when the Record Type allows it. It is not a Document match key; use **external\_id** when repeated imports should identify the same Document.
- **record\_type** supplies the linked Record Type name. If blank, Astalty uses **document\_name**, or the source file name when both are blank.
- If no type has that name, Astalty creates one. It is expiring when rows for that type supply an expiry, and non-expiring when they only supply a record reference. Rows for the same Record Type cannot mix entries with and without expiry, including rows matched to an earlier import.
- An existing expiring Record Type requires **expiry**. An existing non-expiring Record Type cannot accept **expiry**. For new Documents, Astalty rejects the mapping file when the row and an existing type do not agree, so fix the expiry or use a different type before the import. If the type is archived, the Document still imports but the linked Record is not created and the row records a warning.
- For a new linked Record, Astalty records the User who starts the requested import as its creator. If none was supplied, it uses the account Admin. This is separate from the Participant or User identified by **target\_reference**.

### Matching an Existing Document

Use **external\_id** to identify the same source Document across repeated imports. When it matches an earlier import, Astalty reuses the Document instead of importing the file again. The requested matching mode decides whether supported metadata stays unchanged, fills blank values or updates. Astalty does not copy or change a matched Document owned by another target.

**Skip it** leaves the matched Document and its linked Records unchanged. To apply a reference or expiry to a matched Document, request **Fill in empty fields** or **Update with the file's values**.

> **Check the linked Record before updating a matched Document**
>
> When a row supplies **expiry**, Astalty looks for an attached expiring Record with the requested **record\_type**. If it cannot find one, it can update another expiring Record already attached to the Document, including that Record's Reference when no attached Record matches the requested type. Changing **record\_type** in the file does not guarantee a new Record of that type.
>
> If several linked Records share the requested type, Astalty updates the first matching Record rather than asking which one you intended. It does not update all matching Records.
>
> For a matched Document with existing linked Records, choose **Skip it** until Astalty has reviewed the mapping and the Records that would be updated. This also applies when you need a different Record Type.

When a matched Document needs a new linked Record, compatibility with an existing Record Type is checked during import. A mapping file can pass validation but still produce a warning and no new linked Record if the expiry is missing, the type does not accept expiry or the type is archived. Review the row warnings in [Import Results](https://docs.astalty.com.au/guide/imports/import-results) and correct the reference, expiry or Record Type before trying again.

### Example Mapping Rows

| target\_reference\_type   | target\_reference         | document\_name | document\_path                  | date       | expiry     | record\_type        | record\_reference | categories | status   | external\_id |
| ------------------------- | ------------------------- | -------------- | ------------------------------- | ---------- | ---------- | ------------------- | ----------------- | ---------- | -------- | ------------ |
| participant\_ndis\_number | 430123456                 | Support Plan   | files/john/support-plan.pdf     | 12/07/2024 | 12/07/2025 | Support Plan        | PLAN-2024         | Care Plan  | active   | legacy-1001  |
| user\_email               | <coordinator@example.com> | Induction Pack | users/coordinator/induction.pdf | 01/08/2024 |            | Employment Contract | CONTRACT-7        | Onboarding | archived | legacy-1002  |

## Limitations

- **document\_path** is limited to 150 characters. It cannot start or end with a forward slash, contain a doubled slash, contain a parent-directory path segment, or use a backslash.
- **target\_reference**, **document\_name**, **record\_type**, **record\_reference**, **external\_id**, and each comma-separated category name are limited to 255 characters.
- **date** and **expiry** accept day/month/year values.
- **status** accepts *active* or *archived*, without regard to capitalisation.
- The mapping CSV needs all required headers and at least one data row.
- Each mapped path must correspond to a supplied file. A missing file fails that row.
- A row failure does not reverse Documents imported successfully by other rows. Document imports do not provide **Download Failed Rows**.

## Import Process

Contact <imports@astalty.com.au> to agree on secure transfer. Astalty validates the map, resolves targets, imports ready rows in background chunks, and reports each row as imported, updated, invalid target, or failed. Retrying with the same **external\_id** supports safe matching; omitting it gives Astalty no cross-import source identifier for that Document.