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.
Files to Prepare
- 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, 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.
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 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.