Build a Bulk Upload Module

This guide walks you through building a UI module that lets Creators upload a CSV file and import its records into a Data Model in bulk. The module handles the full sequence: generating an upload URL, uploading the file, running the import, and checking job status, all from a single button click.

Download the example module bundle to use as a starting point. After importing, replace every placeholder before using the module:

Prerequisites

• Creator or Express Administrator access to your workspace.

• A target Data Model to receive the imported records.

• A CSV file with data matching your Data Model's field structure.

• Familiarity with the Plug-In, Decisions, and File components.

Module Overview

Organize the module into three field groups: for initialization logic, for the Creator-facing UI, and for the backend Plug-In component sequence.

The example Property IDs in this guide use a plugin prefix (for example, pluginExport) for clarity. The platform default for Plug-In components is plug — see Property ID Naming Conventions.

How to read settings tables

The tables below describe each configurable option as it shows in the platform. Values are formatted as follows: inline code — a value to type exactly as shown | Bold — a value selected from a drop-down, radio button, tab, or choice chip | ON/OFF — toggle state | ✓ — checkbox checked | ☐ — checkbox unchecked

Set Up the Field Groups

Create three field groups in the module to keep components organized.

Create the Supporting Fields

Add the following fields to fgConfig. These fields carry data between components throughout the upload and import sequence.

Configure initOnload

The initOnload Initializer component fires when the module first loads and triggers the pluginListSubmission Plug-In component to populate the existing records view.

1. Add an Initializer component to fgOnLoad.

2. Configure the following settings:

   Setting	Value
   Property ID	initOnload
   Trigger Type	New Submission

3. Configure the Outputs:

   #	Property ID	Type	Value
   1	pluginListSubmission	Trigger	GO

Configure pluginListSubmission

The pluginListSubmission Plug-In component loads existing records from the target module when the page renders. It is triggered by the initOnload Initializer component and has no outputs. The platform writes the response data directly to any connected display components.

1. Add a Plug-In component to fgOnLoad after initOnload.

2. Configure the following settings:

   Setting	Value
   Property ID	pluginListSubmission
   Trigger Type	Manual
   Endpoint URL	https://{environment}.unqork.io/fbu/uapi/system/getSubmissions
   Method

3. Configure the Inputs:

   #	Property ID	Value
   1	moduleId	'REPLACE_WITH_MODULE_ID'
   2	fields	'REPLACE_WITH_FIELDS' (comma-separated field names to return, for example 'firstName,lastName,email')

Configure fileUpload

The fileUpload File component captures the CSV the Creator selects. After a file is chosen, it triggers the ruleFileUpload Decisions component to enable the import button.

1. Add a File component to fgUI.

2. Configure the following settings:

   Setting	Value
   Property ID	fileUpload
   Label	Upload File
   Accepted File Types	.csv

3. Under Triggers, set the Post Upload drop-down to ruleFileUpload.

Configure ruleFileUpload

The ruleFileUpload Decisions component checks whether a file has been selected and enables the btnBulkImport Button component when is present. It is triggered by the fileUpload File component after each file selection.

1. Add a Decisions component to fgUI after fileUpload.

2. Configure the following settings:

   Setting	Value
   Property ID	ruleFileUpload
   Trigger Type	Manual

3. Configure the Inputs:

   #	Property ID	Alias	Type
   1	fileUpload	A	Exact

4. Configure the Outputs:

   #	Property ID	Type
   1	btnBulkImport	Disabled

5. Add row in the Decision grid:

   fileUpload	btnBulkImport_disabled
   (wildcard)	=IF(LEN(A)>0,'no','yes')

Configure btnBulkImport

The btnBulkImport Button component starts the upload and import sequence. It starts disabled and is enabled by the ruleFileUpload Decisions component a file is selected. On successful validation, it triggers the pluginGenerateUploadLink Plug-In component.

1. Add a Button component to fgUI after ruleFileUpload.

2. Configure the following settings:

   Setting	Value
   Property ID	btnBulkImport
   Label	Bulk Import
   Action	Validate
   Initial State	Disabled

3. Under Triggers, set the On Validation Success drop-down to pluginGenerateUploadLink.

Configure btnRefresh

The btnRefresh Button component lets the Creator manually re-check import job status. It triggers the pluginGetJobDetails Plug-In component on click, and the ruleCheckStatus Decisions component enables it a job is running. It starts disabled.

1. Add a Button component to fgUI above fileUpload.

2. Configure the following settings:

   Setting	Value
   Property ID	btnRefresh
   Label	Refresh
   Action	Event
   Initial State	Disabled

3. Under Triggers, set the On Click drop-down to pluginGetJobDetails.

Configure initSuccess

The initSuccess Initializer component sets the response field to Success when the import completes. It is triggered by components that confirm a successful outcome.

1. Add an Initializer component to fgConfig.

2. Configure the following settings:

   Setting	Value
   Property ID	initSuccess
   Trigger Type	Manual

3. Configure the Outputs:

   #	Property ID	Type	Value
   1	response	Value	Success

Configure initError

The initError Initializer component sets the response field to Fail when something goes wrong. All Plug-In components in fgConfig reference it as their error handler.

1. Add an Initializer component to fgConfig after initSuccess.

2. Configure the following settings:

   Setting	Value
   Property ID	initError
   Trigger Type	Manual

3. Configure the Outputs:

   #	Property ID	Type	Value
   1	response	Value	Fail

Configure pluginGenerateUploadLink

The pluginGenerateUploadLink Plug-In component gets a pre-signed URL for uploading the file to the Unqork Cloud. It is triggered by the btnBulkImport Button component. On success, it triggers the pluginUploadFile Plug-In component.

1. Add a Plug-In component to fgConfig.

2. Configure the following settings:

   Setting	Value
   Property ID	pluginGenerateUploadLink
   Trigger Type	Manual
   Endpoint URL	https://{environment}.unqork.io/fbu/uapi/bulkOperations/uploadLink
   Method	POST

3. No Inputs are required for this endpoint.

4. Configure the Outputs:

   #	Property ID	Value
   1	uploadLink	uploadLink

5. Under Triggers, set the Post Trigger drop-down to pluginUploadFile and the Error Handler drop-down to initError.

Configure pluginUploadFile

The pluginUploadFile Plug-In component posts the file bytes to the pre-signed URL using multipart/form-data. It is triggered by the pluginGenerateUploadLink Plug-In component. On success, it triggers the pluginBulkImportRecord Plug-In component. The endpoint URL is built dynamically from the uploadLink field.

1. Add a Plug-In component to fgConfig after pluginGenerateUploadLink.

2. Configure the following settings:

   Setting	Value
   Property ID	pluginUploadFile
   Trigger Type	Manual
   Endpoint URL	/api{{data.uploadLink}}
   Method	POST
   Multipart	ON

3. Configure the Headers:

   #	Property ID	Value
   1	Connect-Type	multipart/form-data

4. Configure the Inputs:

   #	Property ID	Value
   1	file	fileUpload[0]['url']

   Enable Resolve Base64 on the file input so the platform sends the file bytes rather than the base64 string.

5. Configure the Outputs:

   #	Property ID	Value
   1	fileKey	fileKey

6. Under Triggers, set the Post Trigger drop-down to pluginBulkImportRecord and the Error Handler drop-down to initError.

Configure pluginBulkImportRecord

The pluginBulkImportRecord Plug-In component calls the Import endpoint using the fileKey from the upload step. It is triggered by the pluginUploadFile Plug-In component. On success, it triggers the pluginGetJobDetails Plug-In component to begin polling.

1. Add a Plug-In component to fgConfig after pluginUploadFile.

2. Configure the following settings:

   Setting	Value
   Property ID	pluginBulkImportRecord
   Trigger Type	Manual
   Endpoint URL	https://{environment}.unqork.io/fbu/uapi/bulkOperations/import
   Method	POST

3. Configure the Inputs:

   #	Property ID	Value
   1	dataModelOrModuleId	'REPLACE_WITH_MODULE_ID'
   2	fallbackRecordOwner	currentUser['email']
   3	fileFormat	'CSV'
   4	fileLocation	fileKey
   5	name	fileUpload[0]['name']
   6	storeInData	'true'

4. Configure the Outputs:

   #	Property ID	Value
   1	status	data.status
   2	jobId	id

5. Under Triggers, set the Post Trigger drop-down to pluginGetJobDetails and the Error Handler drop-down to initError.

Configure pluginGetJobDetails

The pluginGetJobDetails Plug-In component checks the status of the import job. It is triggered by the pluginBulkImportRecord Plug-In component on success, and by the btnRefresh Button component when the Creator clicks it manually. On completion, it triggers the ruleCheckStatus Decisions component.

1. Add a Plug-In component to fgConfig after pluginBulkImportRecord.

2. Configure the following settings:

   Setting	Value
   Property ID	pluginGetJobDetails
   Trigger Type	Manual
   Endpoint URL	https://{environment}.unqork.io/fbu/uapi/bulkOperations/jobs/{{data.jobId}}
   Method	GET

3. Configure the Outputs:

   #	Property ID	Value
   1	status	data.status

4. Under Triggers, set the Post Trigger drop-down to ruleCheckStatus.

All BDO endpoints in this module use the bulkOperations  (camelCase, no hyphen).

Configure ruleCheckStatus

The ruleCheckStatus Decisions component reads the job status written by the pluginGetJobDetails Plug-In component, triggers a pop-up message, and enables the btnRefresh Button component while the job is running. When the job reaches completed, it clears and resets fgUI so the Creator can start another upload.

1. Add a Decisions component to fgConfig after pluginGetJobDetails.

2. Configure the following settings:

   Setting	Value
   Property ID	ruleCheckStatus
   Trigger Type	Manual

3. Configure the Inputs:

   #	Property ID	Alias	Type
   1	jobId	A	Exact
   2	status		Exact

4. Configure the Outputs:

   #	Property ID	Type
   1	btnRefresh	Disabled
   2	fgUI	Pop Message
   3	fgUI	Multi

5. Add row per job status in the Decision grid:

   Status	btnRefresh_disabled	fgUI_popMessage	fgUI_multi
   created	=IF(LEN(A)>0,'no','yes')	Import started.
   inProgress	=IF(LEN(A)>0,'no','yes')	Import in progress.
   completed	=IF(LEN(A)>0,'no','yes')	Import complete.	clear.reset
   partiallyCompleted	=IF(LEN(A)>0,'no','yes')	Import partially complete.
   canceled	=IF(LEN(A)>0,'no','yes')	Import canceled.
   failed	=IF(LEN(A)>0,'no','yes')	Import failed.

   The formula in the disabled column uses A (the jobId alias). The clear.reset multi-action on completed clears fgUI and resets the form for the next upload.

Test the Module

1. Open the module in Preview.

2. Select a CSV file using the Upload File component. The Bulk Import button enables when a file is present.

3. Click Bulk Import.

4. Click Refresh until the pop-up message reads Import complete.

5. Open the submission using the platform's submission inspection method. See Debugger for how to access submission data from Express View.

6. Confirm the jobId and status fields contain the expected values.

7. Navigate to the target Data Model's Record Collection to verify the imported records appear.