From f78e64bac97de8ce76cadfc23a35aad821e2b96f Mon Sep 17 00:00:00 2001 From: Karuna Vengurlekar Date: Fri, 11 Sep 2026 16:02:29 +0530 Subject: [PATCH 1/4] Create new doc --- .../docs/refguide/modeling/integration/data-importer.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 content/en/docs/refguide/modeling/integration/data-importer.md diff --git a/content/en/docs/refguide/modeling/integration/data-importer.md b/content/en/docs/refguide/modeling/integration/data-importer.md new file mode 100644 index 00000000000..c21ca2935c5 --- /dev/null +++ b/content/en/docs/refguide/modeling/integration/data-importer.md @@ -0,0 +1,9 @@ +--- +title: "Data Importer" +url: /refguide/data-importer/ +weight: 40 +description: "Describes how to use the Data Importer in Studio Pro to import data from Excel and CSV files" +#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. +--- + +## Introduction From adff054bc2ab141895eee9b27421e914a15eb6a9 Mon Sep 17 00:00:00 2001 From: Karuna Vengurlekar Date: Fri, 11 Sep 2026 17:29:46 +0530 Subject: [PATCH 2/4] Add first draft --- .../modeling/integration/data-importer.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/content/en/docs/refguide/modeling/integration/data-importer.md b/content/en/docs/refguide/modeling/integration/data-importer.md index c21ca2935c5..00e78f682ac 100644 --- a/content/en/docs/refguide/modeling/integration/data-importer.md +++ b/content/en/docs/refguide/modeling/integration/data-importer.md @@ -7,3 +7,90 @@ description: "Describes how to use the Data Importer in Studio Pro to import dat --- ## Introduction + +Data Importer lets you define how data from Excel and CSV files is interpreted in your Mendix app. You create a Data Importer document based on a representative input file. + +The document can be used in two ways: + +* With Import Data from File to import the file into a generated non-persistable entity. +* As a source for an Import Mapping, which gives you more control over how imported data is mapped to Mendix objects. + +## Creating a Data Importer Document + +Right-click the module you want to add the Data Importer document to and click **Add other** > **Data Importer**. + +Name the document, then click **OK**, and the new Data Importer document opens. + +{{% alert color="info" %}} You need to run the app first to configure the file settings.{{% /alert %}} + +## Previewing Data + +Once you have created the Data Importer document, click Select a local file to import an Excel file (.xls or .xslx) or CSV file (.csv). + +### Previewing Excel Data + +Click Select a local file to import an Excel file (.xls or .xslx). + +Select or drop the file in the Select Source File field. An Excel workbook can have single or multiple sheets; you can choose which sheet to import data from and specify the header row and starting data row. + +* Sheet Name – name of the worksheet from where data needs to be imported; if the Excel has multiple worksheets, their names will appear in the dropdown +* Header Row No. – row number of the file header; the default is 1 +* Read Data From Row No. – starting line for reading data; the default is 2 + +Click Preview Source Data & Entity to view the data from the file. The first 10 data rows from the source file are shown in the data preview section. If there are less than 10 data rows in the sample file, only the available rows are shown. The column names correspond to the attribute name within the entity, and the sheet name is used to define the entity. + +All the columns are automatically selected (checked) for import. You can uncheck the columns you do not want to use. At the bottom of the table, you see the target data type of the attribute, which is based on the cell-type defined in the Excel file's first data row. If any data types are incorrect, check the cell-type of the first data row and adjust the definition accordingly. + +{{% alert color="warning" %}} +Column names that do not adhere to Mendix naming conventions will be autocorrected. For Number cell-types, the target Mendix type is mapped to Decimal to accommodate to integers and decimals. +{{% /alert %}} + +### Previewing CSV Data + +Select or drop the CSV file in the Select Source File window. CSV import supports multiple combinations of separator/delimiter, quote, and escape characters. It also supports importing files where the header row is absent. + +Specify the values for all four configurations (Delimiter, Quote Character, Escape Character, and Add Header Row): + +* Delimiter (Separator) – current supported delimiters are comma, semicolon, pipe, and tab; the default is comma +* Quote Characters – current supported quote characters are single and double quotes; the default is double quotes +* Escape Characters – current supported escape characters are backslash, single, and double quotes; the default is double quotes +* Add Header Row – specify if you want to add a header row or if the header row is already part of the CSV file; the default is the header row already included in file + +Click Preview Source Data & Entity to view the data from the file. The first ten rows from the source file are shown in the data preview section. The file name is used to define the entity (NPE), but this can be edited. The column names correspond to the attribute name within the entity. + +All the columns are selected (checked) by default. You can uncheck the columns you do not want to import. At the bottom of the table, you can see the target data type of the attribute, which defaults to String. + +{{% alert color="warning" %}} +Column names that do not adhere to Mendix naming conventions will be autocorrected. +{{% /alert %}} + +## Creating Import Mapping + +Once your document is created, you can see the structure element is ready to use for the import mapping. For more information, see [Import Mapping](/refguide/import-mappings/). + +## Editing an Entity + +You can edit the entity in the Entity Preview section. The Data Importer supports various ways to: + +* Edit the name of resultant entity +* Edit the name of the attribute (or attributes) of the entity +* Edit the data type of a given attribute + +Click Edit at top-right corner of Entity Preview. This will render a pop-up window where you can change the name of the entity. You can also change the name of the attribute; Original Name is the name of the column from input file and Attribute Name will be the new name that you want to assign to this column. You can also change the data type of this attribute by selecting a relevant value from the drop-down as shown below. + +Once you are satisfied with the changes, click OK to save or Cancel to discard your changes. + +{{% alert color="warning" %}} + +* Enum is not supported as a target data type +* Runtime exceptions can occur if the input data cannot be converted into desired the target data type for various reasons (for example, invalid data, data truncation, casting etc.) + +{{% /alert %}} + +## Creating an Entity + +When you are done editing the entity, click Create Entity > OK. This will create the entity in your domain model. You will also see a confirmation message that an entity has been created in the domain model and is ready to use. + +When the entity is created, you can view the mapping of the source columns to the target entity attributes. + +The Data Importer document creation is complete and can be used to import data in a microflow. From 77855226e6dbe5d3e91be5c01c670daa2be2a151 Mon Sep 17 00:00:00 2001 From: Karuna Vengurlekar Date: Mon, 21 Sep 2026 18:30:57 +0530 Subject: [PATCH 3/4] Add more sections --- .../modeling/integration/data-importer.md | 118 ++++++++++++++---- 1 file changed, 97 insertions(+), 21 deletions(-) diff --git a/content/en/docs/refguide/modeling/integration/data-importer.md b/content/en/docs/refguide/modeling/integration/data-importer.md index 00e78f682ac..ff5ebfad8de 100644 --- a/content/en/docs/refguide/modeling/integration/data-importer.md +++ b/content/en/docs/refguide/modeling/integration/data-importer.md @@ -25,38 +25,38 @@ Name the document, then click **OK**, and the new Data Importer document opens. ## Previewing Data -Once you have created the Data Importer document, click Select a local file to import an Excel file (.xls or .xslx) or CSV file (.csv). +Once you have created the Data Importer document, click **Upload File** to import an Excel file (.xls or .xslx) or CSV file (.csv). ### Previewing Excel Data -Click Select a local file to import an Excel file (.xls or .xslx). +Upload an Excel file (.xls or .xslx) as source file. -Select or drop the file in the Select Source File field. An Excel workbook can have single or multiple sheets; you can choose which sheet to import data from and specify the header row and starting data row. +Select or drop the file in the **Select file from local**. An Excel workbook can have single or multiple sheets; you can choose which sheet to import data from and specify the details below to configfure the file settings: -* Sheet Name – name of the worksheet from where data needs to be imported; if the Excel has multiple worksheets, their names will appear in the dropdown -* Header Row No. – row number of the file header; the default is 1 -* Read Data From Row No. – starting line for reading data; the default is 2 +* **Sheet Name** – name of the worksheet from where data needs to be imported; if the Excel has multiple worksheets, their names will appear in the dropdown +* **Header Row No.** – row number of the file header; the default is 1 +* **Read Data From** – starting line for reading data; the default is 2 -Click Preview Source Data & Entity to view the data from the file. The first 10 data rows from the source file are shown in the data preview section. If there are less than 10 data rows in the sample file, only the available rows are shown. The column names correspond to the attribute name within the entity, and the sheet name is used to define the entity. +Click **Preview Data** to view the data from the file. The first 10 data rows from the source file are shown in the data preview section. If there are less than 10 data rows in the sample file, only the available rows are shown. The column names correspond to the attribute name within the entity, and the sheet name is used to define the entity. All the columns are automatically selected (checked) for import. You can uncheck the columns you do not want to use. At the bottom of the table, you see the target data type of the attribute, which is based on the cell-type defined in the Excel file's first data row. If any data types are incorrect, check the cell-type of the first data row and adjust the definition accordingly. {{% alert color="warning" %}} -Column names that do not adhere to Mendix naming conventions will be autocorrected. For Number cell-types, the target Mendix type is mapped to Decimal to accommodate to integers and decimals. +Column names that do not adhere to Mendix naming conventions will be autocorrected. For Number cell-types, the target Mendix type is mapped to Decimal to accommodate the integers and decimals. {{% /alert %}} ### Previewing CSV Data -Select or drop the CSV file in the Select Source File window. CSV import supports multiple combinations of separator/delimiter, quote, and escape characters. It also supports importing files where the header row is absent. +Select or drop the CSV file as a source file. CSV import supports multiple combinations of separator/delimiter, quote, and escape characters. It also supports importing files where the header row is absent. -Specify the values for all four configurations (Delimiter, Quote Character, Escape Character, and Add Header Row): +Specify the values for all file setting configurations below: -* Delimiter (Separator) – current supported delimiters are comma, semicolon, pipe, and tab; the default is comma -* Quote Characters – current supported quote characters are single and double quotes; the default is double quotes -* Escape Characters – current supported escape characters are backslash, single, and double quotes; the default is double quotes -* Add Header Row – specify if you want to add a header row or if the header row is already part of the CSV file; the default is the header row already included in file +* **Delimiter (Separator)** – current supported delimiters are comma, semicolon, pipe, and tab; the default is comma +* **Quote Characters** – current supported quote characters are single and double quotes; the default is double quotes +* **Add Header Row** – specify if you want to add a header row or if the header row is already part of the CSV file; the default is the header row already included in the file +* **Escape Character** – current supported escape characters are backslash, single, and double quotes; the default is double quotes -Click Preview Source Data & Entity to view the data from the file. The first ten rows from the source file are shown in the data preview section. The file name is used to define the entity (NPE), but this can be edited. The column names correspond to the attribute name within the entity. +Click **Preview Data** to view the data from the file. The first ten rows from the source file are shown in the data preview section. The file name is used to define the entity (NPE), but this can be edited. The column names correspond to the attribute name within the entity. All the columns are selected (checked) by default. You can uncheck the columns you do not want to import. At the bottom of the table, you can see the target data type of the attribute, which defaults to String. @@ -66,31 +66,107 @@ Column names that do not adhere to Mendix naming conventions will be autocorrect ## Creating Import Mapping -Once your document is created, you can see the structure element is ready to use for the import mapping. For more information, see [Import Mapping](/refguide/import-mappings/). +Once your document is created, you can see the structure is ready at **Structure elements** section. For your advanced use cases, you can now use the document for the import mapping. For more information, see [Import Mapping](/refguide/import-mappings/). ## Editing an Entity -You can edit the entity in the Entity Preview section. The Data Importer supports various ways to: +Optionally, you can edit and create an entity to import the data for simple use cases. You can edit the entity in the **Entity Preview** section. The Data Importer supports various ways to: * Edit the name of resultant entity * Edit the name of the attribute (or attributes) of the entity * Edit the data type of a given attribute -Click Edit at top-right corner of Entity Preview. This will render a pop-up window where you can change the name of the entity. You can also change the name of the attribute; Original Name is the name of the column from input file and Attribute Name will be the new name that you want to assign to this column. You can also change the data type of this attribute by selecting a relevant value from the drop-down as shown below. +Click the edit icon ({{% icon name="pencil" %}}) at bottom-right corner of **Entity Preview**. This will render a pop-up window where you can change the **Name** of the entity. You can also change the **Attribute Name**; **Original Name** is the name of the column from input file and **Attribute Name** will be the new name that you want to assign to this column. You can also change the **Data Type** of this attribute by selecting a relevant value from the drop-down as shown below. -Once you are satisfied with the changes, click OK to save or Cancel to discard your changes. +{{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/edit-csv-entity.png" class="no-border" width="600" >}} + +Once you are satisfied with the changes, click **OK** to save or **Cancel** to discard your changes. {{% alert color="warning" %}} * Enum is not supported as a target data type -* Runtime exceptions can occur if the input data cannot be converted into desired the target data type for various reasons (for example, invalid data, data truncation, casting etc.) +* Runtime exceptions can occur if the input data cannot be converted into desired target data type for various reasons (for example, invalid data, data truncation, casting etc.) {{% /alert %}} ## Creating an Entity -When you are done editing the entity, click Create Entity > OK. This will create the entity in your domain model. You will also see a confirmation message that an entity has been created in the domain model and is ready to use. +When you are done editing the entity, click **Create Entity**. This will create the entity in your domain model. You will also see a confirmation message that an entity has been created in the domain model and is ready to use. When the entity is created, you can view the mapping of the source columns to the target entity attributes. The Data Importer document creation is complete and can be used to import data in a microflow. + +## Building Your App + +The newly-created Data Importer document allows you to periodically import data from an Excel or CSV file that is generated by another app or system. + +### Creating Custom Activity + +Find the **Import data from file** activity under **Integration activities** in the **Toolbox** and view its properties. For more information, see [Import Data from File](/refguide/import-data-from-file/). + +### Building the Pages + +The **Import data from file** custom activity needs an input file to import data from. The example below builds a page where a `System.FileDocument` is uploaded and fed to the custom activity. + +1. Open the home page and add a button and name it *Upload Customer Data*. +2. Double-click the button and in the **Events** field under the **On click** drop-down, select **Create object** to create a `System.FileDocument` entity. +3. Pass the control to a new page (**UploadCustomerData**) where the file is uploaded. + + {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/home-page-button.png" class="no-border" width="600" >}} + +4. On the **UploadCustomerData** page, include a data view for the *FileDocument* and include a 'File Manager' to assist with a file upload. + + {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/data-view-file-manager.png" class="no-border" width="600" >}} + +5. Open the **Toolbox** and add a **Call microflow button**. + +6. Click **New** and name the microflow *Import Customer Data*. You also see **FileDocument** in the parameters section; make sure this box is checked to include it as a parameter and click **OK**. + +{{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/add-parameter.png" class="no-border" width="600" >}} + +### Configuring the Import data from file Activity in a Microflow + +{{% alert color="info" %}} +The steps below are shown using an Excel input file with its corresponding Data Importer document. You can substitute an Excel document with a CSV document to import data from CSV input files. +{{% /alert %}} + +1. In the created microflow, drag the **Import data from file** activity into it. You can find this activity in the **Toolbox** under **Integration activities**. + + {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/integration-activity.png" class="no-border" width="600" >}} + +2. When the **Import data from file** activity is added into microflow, you see three errors in the console: + + {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/custom-activity.png" class="no-border" width="600" >}} + + To address these errors, double-click the activity and in the **File** field, choose the input file that is passed from the file upload page to this microflow as a parameter. + +3. In the **Data Importer document** field, click **Select** and choose the Data Importer document you want to use. + + {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/choose-data-importer-template.png" class="no-border" width="600" >}} + + After selecting the Data Importer document, the **Return type** and **Variable name** auto-populates. You can change the name of the output variable if you wish. + +4. Click **OK**. The custom activity is configured and all the errors will resolve. + + {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/configured-custom-activity.png" class="no-border" width="600" >}} + +5. Add an **Aggregate list** activity and configure it to count the size of the 'CustomerList', which is returned from the previous activity. + + {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/aggregate-list.png" class="no-border" width="600" >}} + +6. Configure a **Show message** activity. You can use a template message and a parameter, such as in the example below. + + {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/show-message-with-list-size.png" class="no-border" width="600" >}} + +7. Set '$CustomerList' as the return value from the **Import data from file** activity to be used later. Your completed microflow should look like the image below. + + {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/example-microflow.png" class="no-border" width="600" >}} + +8. Deploy your app locally. Browse and upload an input file, which is similar to the file that was used as a template while creating Data Importer document. +9. Check that you see a message that states **Imported xx rows from input file into a list of NPEs**. + + {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/local-app-run.png" class="no-border" width="600" >}} + +You have successfully configured and used the Data Importer extension. You can extend this as per your requirements. For example, you can convert the list of NPEs into persistable entities by providing a message definition, or use each loop construct and individually create and commit entities into your database. + From b07f1020bf766bde9acb27015a88dbb2ad767116 Mon Sep 17 00:00:00 2001 From: Karuna Vengurlekar Date: Tue, 22 Sep 2026 19:09:44 +0530 Subject: [PATCH 4/4] Add feedback --- .../modeling/integration/data-importer.md | 150 +++++------------- 1 file changed, 37 insertions(+), 113 deletions(-) diff --git a/content/en/docs/refguide/modeling/integration/data-importer.md b/content/en/docs/refguide/modeling/integration/data-importer.md index ff5ebfad8de..c757d7b8926 100644 --- a/content/en/docs/refguide/modeling/integration/data-importer.md +++ b/content/en/docs/refguide/modeling/integration/data-importer.md @@ -2,7 +2,7 @@ title: "Data Importer" url: /refguide/data-importer/ weight: 40 -description: "Describes how to use the Data Importer in Studio Pro to import data from Excel and CSV files" +description: "Describes how to use Data Importer in Studio Pro to import data from Excel and CSV files" #If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. --- @@ -12,161 +12,85 @@ Data Importer lets you define how data from Excel and CSV files is interpreted i The document can be used in two ways: -* With Import Data from File to import the file into a generated non-persistable entity. +* With **Import Data from File** activity, to import the file into a generated non-persistable entity. * As a source for an Import Mapping, which gives you more control over how imported data is mapped to Mendix objects. ## Creating a Data Importer Document -Right-click the module you want to add the Data Importer document to and click **Add other** > **Data Importer**. +To create a Data Importer document, follow the steps below: -Name the document, then click **OK**, and the new Data Importer document opens. +1. Right-click the module where you want to add the Data Importer document, then click **Add other** > **Data Importer**. +2. Enter a name for the document, then click **OK** -{{% alert color="info" %}} You need to run the app first to configure the file settings.{{% /alert %}} +The new Data Importer document opens. -## Previewing Data +{{% alert color="warning" %}}Run the app before you configure the file settings or preview data.{{% /alert %}} -Once you have created the Data Importer document, click **Upload File** to import an Excel file (.xls or .xslx) or CSV file (.csv). +## Previewing Data -### Previewing Excel Data +Once you have created the Data Importer document, click **Upload File** in **Select file from local** to import an Excel file (.xls or .xslx) or CSV file (.csv). -Upload an Excel file (.xls or .xslx) as source file. +### Previewing Excel -Select or drop the file in the **Select file from local**. An Excel workbook can have single or multiple sheets; you can choose which sheet to import data from and specify the details below to configfure the file settings: +Upload an Excel file (.xls or .xslx) as source file. An Excel workbook can have single or multiple sheets; you can choose which sheet to import data from and specify the details below to configfure the file settings: -* **Sheet Name** – name of the worksheet from where data needs to be imported; if the Excel has multiple worksheets, their names will appear in the dropdown -* **Header Row No.** – row number of the file header; the default is 1 -* **Read Data From** – starting line for reading data; the default is 2 +* **Sheet Name** – name of the worksheet to import. If the workbook has multiple worksheets, their names appear in the drop-down list. +* **Header Row No.** – row number of the file header; the default is *1* +* **Read Data From** – a row where data reading starts; the default is *2* -Click **Preview Data** to view the data from the file. The first 10 data rows from the source file are shown in the data preview section. If there are less than 10 data rows in the sample file, only the available rows are shown. The column names correspond to the attribute name within the entity, and the sheet name is used to define the entity. +Click **Preview Data** to view the data from the selected file. -All the columns are automatically selected (checked) for import. You can uncheck the columns you do not want to use. At the bottom of the table, you see the target data type of the attribute, which is based on the cell-type defined in the Excel file's first data row. If any data types are incorrect, check the cell-type of the first data row and adjust the definition accordingly. +Data Importer creates the data structure based on the first ten rows of the source file and displays it in the **Structure elements** section. If the file settings do not provide valid data, an error is displayed. Click the edit icon ({{% icon name="pencil" %}}) at bottom-right corner of the structure elements table to modify **Custom Name** or **Primitive Type**. {{% alert color="warning" %}} -Column names that do not adhere to Mendix naming conventions will be autocorrected. For Number cell-types, the target Mendix type is mapped to Decimal to accommodate the integers and decimals. +Column names that do not adhere to Mendix naming conventions are autocorrected. For Number cell-types, the target Mendix type is mapped to **Decimal** to support both integers and decimals. {{% /alert %}} -### Previewing CSV Data +### Previewing CSV -Select or drop the CSV file as a source file. CSV import supports multiple combinations of separator/delimiter, quote, and escape characters. It also supports importing files where the header row is absent. +Select or drop the CSV file as a source file. CSV import supports multiple combinations of separator or delimiter, quote, and escape characters. It also supports files without a header row. -Specify the values for all file setting configurations below: +Configure the following settings: -* **Delimiter (Separator)** – current supported delimiters are comma, semicolon, pipe, and tab; the default is comma -* **Quote Characters** – current supported quote characters are single and double quotes; the default is double quotes -* **Add Header Row** – specify if you want to add a header row or if the header row is already part of the CSV file; the default is the header row already included in the file -* **Escape Character** – current supported escape characters are backslash, single, and double quotes; the default is double quotes +* **Delimiter (Separator)** – Supported delimiters are comma, semicolon, pipe, and tab. The default is comma. +* **Quote Characters** – Supported quote characters are single and double quotes. The default is double quotes. +* **Add Header Row** – Specify whether you want to add a header row or whether the CSV file already includes one. By default, the file already includes a header row. +* **Escape Character** – Supported escape characters are backslash, single quotes, and double quotes. The default is double quotes. -Click **Preview Data** to view the data from the file. The first ten rows from the source file are shown in the data preview section. The file name is used to define the entity (NPE), but this can be edited. The column names correspond to the attribute name within the entity. +Click **Preview Data** to view the data from the selected file. -All the columns are selected (checked) by default. You can uncheck the columns you do not want to import. At the bottom of the table, you can see the target data type of the attribute, which defaults to String. +Data Importer creates the data structure based on the first ten rows of the source file and displays it in the **Structure elements** section. If the file settings do not provide valid data, an error is displayed. Click the edit icon ({{% icon name="pencil" %}}) at bottom-right corner of the structure elements table to modify **Custom Name** or **Primitive Type**. {{% alert color="warning" %}} -Column names that do not adhere to Mendix naming conventions will be autocorrected. +Column names that do not follow Mendix naming conventions are autocorrected. {{% /alert %}} -## Creating Import Mapping +## Using in Import Mapping -Once your document is created, you can see the structure is ready at **Structure elements** section. For your advanced use cases, you can now use the document for the import mapping. For more information, see [Import Mapping](/refguide/import-mappings/). +After the document and its **Structure elements** are created, you can use the document in an import mapping by selecting **Schema source** as **Excel/CSV Structure**. For more information, see [Import Mappings](/refguide/import-mappings/). ## Editing an Entity -Optionally, you can edit and create an entity to import the data for simple use cases. You can edit the entity in the **Entity Preview** section. The Data Importer supports various ways to: +Optionally, you can edit and create an entity to import the data for simple use cases. You can edit the entity in the **Entity Preview** section. -* Edit the name of resultant entity -* Edit the name of the attribute (or attributes) of the entity -* Edit the data type of a given attribute +Click the edit icon ({{% icon name="pencil" %}}) at bottom-right corner of **Entity Preview**. In the dialog box, you can change the **Name** of the entity. You can also rename attributes. **Original Name** shows the name of the column in the input file, and **Attribute Name** is the new name you want to assign to that column. You can change the data type of an attribute by selecting a value from the drop-down list. Click **OK** to save your changes, or click **Cancel** to discard them. -Click the edit icon ({{% icon name="pencil" %}}) at bottom-right corner of **Entity Preview**. This will render a pop-up window where you can change the **Name** of the entity. You can also change the **Attribute Name**; **Original Name** is the name of the column from input file and **Attribute Name** will be the new name that you want to assign to this column. You can also change the **Data Type** of this attribute by selecting a relevant value from the drop-down as shown below. +In the **Entity Preview**, select which columns to import by selecting or unselecting the checkbox next to each attribute. {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/edit-csv-entity.png" class="no-border" width="600" >}} Once you are satisfied with the changes, click **OK** to save or **Cancel** to discard your changes. {{% alert color="warning" %}} - -* Enum is not supported as a target data type -* Runtime exceptions can occur if the input data cannot be converted into desired target data type for various reasons (for example, invalid data, data truncation, casting etc.) - +**Enum** is not supported as a target data type. Runtime exceptions can occur if the input data cannot be converted to the target data type, for example because of invalid data, data truncation, or casting issues. {{% /alert %}} ## Creating an Entity -When you are done editing the entity, click **Create Entity**. This will create the entity in your domain model. You will also see a confirmation message that an entity has been created in the domain model and is ready to use. - -When the entity is created, you can view the mapping of the source columns to the target entity attributes. - -The Data Importer document creation is complete and can be used to import data in a microflow. - -## Building Your App - -The newly-created Data Importer document allows you to periodically import data from an Excel or CSV file that is generated by another app or system. - -### Creating Custom Activity - -Find the **Import data from file** activity under **Integration activities** in the **Toolbox** and view its properties. For more information, see [Import Data from File](/refguide/import-data-from-file/). - -### Building the Pages - -The **Import data from file** custom activity needs an input file to import data from. The example below builds a page where a `System.FileDocument` is uploaded and fed to the custom activity. - -1. Open the home page and add a button and name it *Upload Customer Data*. -2. Double-click the button and in the **Events** field under the **On click** drop-down, select **Create object** to create a `System.FileDocument` entity. -3. Pass the control to a new page (**UploadCustomerData**) where the file is uploaded. - - {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/home-page-button.png" class="no-border" width="600" >}} - -4. On the **UploadCustomerData** page, include a data view for the *FileDocument* and include a 'File Manager' to assist with a file upload. - - {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/data-view-file-manager.png" class="no-border" width="600" >}} - -5. Open the **Toolbox** and add a **Call microflow button**. - -6. Click **New** and name the microflow *Import Customer Data*. You also see **FileDocument** in the parameters section; make sure this box is checked to include it as a parameter and click **OK**. - -{{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/add-parameter.png" class="no-border" width="600" >}} - -### Configuring the Import data from file Activity in a Microflow - -{{% alert color="info" %}} -The steps below are shown using an Excel input file with its corresponding Data Importer document. You can substitute an Excel document with a CSV document to import data from CSV input files. -{{% /alert %}} - -1. In the created microflow, drag the **Import data from file** activity into it. You can find this activity in the **Toolbox** under **Integration activities**. - - {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/integration-activity.png" class="no-border" width="600" >}} - -2. When the **Import data from file** activity is added into microflow, you see three errors in the console: - - {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/custom-activity.png" class="no-border" width="600" >}} - - To address these errors, double-click the activity and in the **File** field, choose the input file that is passed from the file upload page to this microflow as a parameter. - -3. In the **Data Importer document** field, click **Select** and choose the Data Importer document you want to use. - - {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/choose-data-importer-template.png" class="no-border" width="600" >}} - - After selecting the Data Importer document, the **Return type** and **Variable name** auto-populates. You can change the name of the output variable if you wish. - -4. Click **OK**. The custom activity is configured and all the errors will resolve. - - {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/configured-custom-activity.png" class="no-border" width="600" >}} - -5. Add an **Aggregate list** activity and configure it to count the size of the 'CustomerList', which is returned from the previous activity. - - {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/aggregate-list.png" class="no-border" width="600" >}} - -6. Configure a **Show message** activity. You can use a template message and a parameter, such as in the example below. - - {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/show-message-with-list-size.png" class="no-border" width="600" >}} - -7. Set '$CustomerList' as the return value from the **Import data from file** activity to be used later. Your completed microflow should look like the image below. - - {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/example-microflow.png" class="no-border" width="600" >}} - -8. Deploy your app locally. Browse and upload an input file, which is similar to the file that was used as a template while creating Data Importer document. -9. Check that you see a message that states **Imported xx rows from input file into a list of NPEs**. +When you are done editing the entity, click **Create Entity**. This creates the entity in your domain model and displays a confirmation message. The data importer document is then ready to be used in [Import Data from File](/refguide/import-data-from-file/) to import data. - {{< figure src="/attachments/refguide/modeling/integration/use-platform-supported-content/use-the-data-importer/local-app-run.png" class="no-border" width="600" >}} +## Using in `Import Data from File` Activity -You have successfully configured and used the Data Importer extension. You can extend this as per your requirements. For example, you can convert the list of NPEs into persistable entities by providing a message definition, or use each loop construct and individually create and commit entities into your database. +Once you have created an entity, you can now use the Data Importer document in [Import Data from File](/refguide/import-data-from-file/) activity and import the data in the list of NPEs. +You can extend this as per your requirements. For example, convert the list of NPEs into persistable entities by providing a message definition, or use each loop construct and individually create and commit entities into your database.