Appearance
Import Engine
PinkApple's Import Engine lets you upload spreadsheet data, validate it before anything is created, and then submit it into the same business workflows used by manual entry.
The Import Engine is designed for high-volume onboarding and operational setup where entering one record at a time would be too slow.
When Import Is Available
The Import action only appears when:
- your role has the required permission for that entity
- the entity has an enabled import flow
- you are on the relevant operational page
If the import button is missing, confirm your permissions first.
How The Flow Works
The Import Engine uses a staged workflow:
| Step | What you do | What the system does |
|---|---|---|
| Context | Select any required context such as client type or product | Resolves the correct template structure and validation rules |
| Download Template | Download the generated spreadsheet | Builds a template using the backend import schema |
| Upload | Upload the completed spreadsheet | Parses the file and prepares it for validation |
| Review | Inspect counts and row-level errors | Stages the batch and validates every row without creating records yet |
| Submit | Confirm the import | Sends the validated batch to the existing create procedure or service |
INFO
Validation does not create records. Records are only created after you click Submit Import.
Validation vs Submit
Validation
During validation, PinkApple:
- reads the spreadsheet
- checks required columns and formats
- validates enum and lookup-driven values
- stages the import batch
- returns row-level errors for review
If there are row errors, correct the spreadsheet and upload it again.
Submit
During submit, PinkApple:
- reloads the staged batch
- rebuilds the final create payload
- re-validates the batch server-side
- sends the batch into the normal entity create flow
That means import uses the same business rules as manual creation.
Approval Behaviour
The Import Engine does not create a separate approval workflow.
If the underlying entity's CREATE operation is configured for approval, the submitted batch is routed into the existing approval process after import submission. If approval is not required, the records are created directly.
Spreadsheet Rules
Always follow these rules when preparing an import file:
- Use the downloaded template for the selected context.
- Do not rename, reorder, or delete template headers.
- Enter one record per row unless the template explicitly says otherwise.
- Use the Excel dropdown options for enum-backed columns.
- Keep identifiers such as phone numbers, account numbers, and reference values as text.
- Do not paste formatted tables, merged cells, or formulas into the template.
- Fill only the columns generated for that specific import.
TIP
If a column looks like a phone number, member number, or account number, format the Excel cell as Text before entering data.
Common Errors
| Issue | Likely cause | What to do |
|---|---|---|
| Required field missing | A required column is blank | Fill the missing value and upload again |
| Invalid dropdown value | The typed value does not match the allowed options | Use the dropdown in the template and re-save |
| Header not recognised | The template was edited manually or an old template was reused | Download a fresh template and move your data into it |
| Duplicate record on submit | The data passes format validation but conflicts with existing system records | Correct the conflicting data and resubmit |
| Approval pending after submit | The underlying CREATE operation requires approval | Review progress in the normal approval queue |
Tips
- Start with a small test file before uploading a large batch.
- Use the Review step to fix all row errors before submission.
- Download a new template whenever you change the import context.
- If custom fields are required for an entity, they appear in the generated template automatically.