- Administration
- Imports
- Documents Import
Documents Import
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.
What We Need
- A mapping CSV with one row per Document.
- 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, 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.
expiry uses dd/mm/yyyy. Astalty records imported expiry dates in a Participant Record or User Record linked to the Document. The Record Type must support expiry. For a new linked Record, Astalty uses the User who starts the requested import as its creator, or the account Admin if no User was supplied when the import was created. This creator is separate from the Participant or User identified by the row's target reference, and you do not provide it in the mapping CSV.
When creating a linked Record, record_type supplies its Record Type name. If blank, Astalty uses document_name, or the source file name without its extension when document_name is also blank. Astalty creates an expiring Record Type if no type has that name. If a type with that name exists but does not expire, the Document still imports and Astalty records a warning instead of the expiry. An update to an existing expiring Record uses that Record's type.
external_id identifies the source Document across Document imports. When the same external ID was imported earlier, Astalty reuses that Document rather than importing the binary again. Depending on the matching mode used for the requested import, supported metadata may remain unchanged, fill empty values, or update. A match owned by somebody else is not copied or changed for the new target.
Example Mapping Rows
| target_reference_type | target_reference | document_name | document_path | date | expiry | record_type | categories | status | external_id |
|---|---|---|---|---|---|---|---|---|---|
| participant_ndis_number | 430123456 | Support Plan | files/john/support-plan.pdf | 12/07/2024 | 12/07/2025 | Support Plan | Care Plan | active | legacy-1001 |
| user_email | coordinator@example.com | Induction Pack | users/coordinator/induction.pdf | 01/08/2024 | 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, 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.