From 70f7faf839a55899e25e8f70996e2d5206a3d697 Mon Sep 17 00:00:00 2001 From: mahendra-mahajan-mendix <90612240+mahendra-mahajan-mendix@users.noreply.github.com> Date: Mon, 9 Dec 2024 19:39:21 +0530 Subject: [PATCH 1/4] Update data-importer-extension.md Update DI documentation to cover - new feature for creating structure and Import mapping using that structure. Using the IMM created using Excel/CSV as source to import data from input files. Also how to edit existing DI documents by uploading a new sample file. --- .../modules/data-importer-extension.md | 97 ++++++++++++++++++- 1 file changed, 95 insertions(+), 2 deletions(-) diff --git a/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md b/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md index e9d13ed9a17..86ffed50008 100644 --- a/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md +++ b/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md @@ -14,6 +14,12 @@ The [Data Importer](https://marketplace.mendix.com/link/component/219833) allows The Data Importer is available in [Studio Pro 10.6](/releasenotes/studio-pro/10.6/) and above. {{% /alert %}} +The Data Importer Document can also be used as a source for creating *Import Mapping* [(https://docs.mendix.com/refguide/import-mappings/)]. This Import Mapping can import data from Excel/CSV file using the *Import With Mapping* [Import with Mapping](https://docs.mendix.com/refguide/import-mapping-action/) activity. + +{{% alert color="info" %}} +This Data Importer Document as a source for Import Mapping is available in [Studio Pro 10.18](/releasenotes/studio-pro/10.18/) and above. +{{% /alert %}} + ### Typical Use Cases The Data Importer extension allows you to import data from Excel and CSV files directly into your app. You can create a Data Importer document to define which columns to import and an NPE to hold the imported data, along with source-to-target mapping. @@ -32,7 +38,6 @@ This extension currently has the following limitations: * Source data can be mapped to one entity only; associations are not currently supported * You cannot map data to an existing NPE; you have to create a new entity as part of mapping * Enumerations are not supported -* Multi-line headers and headers containing new-line characters (\r, \n, \r+\n) are not supported * **String** is the default attribute type (*.csv* only) ### Prerequisites @@ -43,7 +48,7 @@ This extension currently has the following limitations: Download the [Data Importer](https://marketplace.mendix.com/link/component/219833) from the Marketplace and [add it into your app](/appstore/use-content/). -## Data Importer Document +## Data Importer Document (with Implicit Mapping) ### Creating a Data Importer Document {#create-document} @@ -188,6 +193,94 @@ To perform testing, you can do the following actions: {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/local-app-run.png" class="no-border" >}} +## Data Importer Document (as a source for Import Mapping) + +The [Import Mapping](https://docs.mendix.com/refguide/import-mappings/) document and the [Import with Mapping](https://docs.mendix.com/refguide/import-mapping-action/) activity porvide lot of inherent advantages like controlling the commit of objects, flexibility to find or create an object and so on. This new feature of Data Importer document leverages these capabilities by creating a source strucutre which can be used to create Import Mapping. Makers who are comfortable working with Mapping Documents[(https://docs.mendix.com/refguide/mapping-documents/)] can use this feature to address advance use-cases of importing data into Mendix. The section below describes how one can create a structure, create an Import mapping using this structure and finally leveraging the *Import with Mapping* activity in a Microflow to import data into Mendix. + +### Creating a Data Importer Document {#create-document-with-imm} + +To import data, right-click on the module and click **Add other** > **Data Importer**. Name the document, enable the *Use with Import mapping* checkbox, click **OK**, and the new Data Importer document opens. + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/create-DI-doc-with-import-mapping.png" class="no-border" >}} + +### Previewing Structure {#preview-structure} + +Once you have [created the Data Importer document](#create-document-with-imm), click **Select a local file** to upload a sample Excel file (*.xls* or *.xslx*) or CSV file (*.csv*). + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/select-file-for-structure-preview.png" class="no-border" >}} + +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, the sheet name appears in the drop-down +* **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 Structure Elements** to view the structure of data from the file. The data from first row of the source file is shown in the *schema elements* section. Click **Create Structure** and you will be notified that a new structure is generated successfully. + +{{% alert color="warning" %}} Column names that do not adhere to Mendix naming conventions will be autocorrected. {{% /alert %}} + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/preview-data-structure.png" class="no-border" >}} + +### Create Import Mapping {#DI-import-mapping} + +Using the *Data Importer Document* created in the above step, you can proceed to create *Import Mapping*. Right click on your module or folder > **Add other** > **Import mapping**. Give a proper name to the Import mapping document and Click **OK**, you will be now routed to *Select a schema element for Import mapping*. From the **Schema source**, choose the last radio button *Excel/CSV structure* and select the sheet from the Excel file which was uploaded as sample as shown in the figure below. + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/select-schema-elements-for-imm.png" class="no-border" >}} + +You can select ALL the columns by pressing **Check all** or selectively choose the columns that you want to import from the input file. After the selction of columns is completed, you can click **OK** to create *Import Mapping*. + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/create-import-mapping.png" class="no-border" >}} + +From here, you can either choose to map an existing Entity by dragging and dropping an existing Entity from your doamin model via **Connector** tab or you can choose to press **Map automatically** to create a new NPE in your domain model. + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/map-automatically.png" class="no-border" >}} + +If you choose **Map automatically*, then you can go to your *Domain Model* and change the Entity's name and persistence as per your requirement. + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/entity-name-persist-change.png" class="no-border" >}} + +### Import with Mapping Activity in a Microflow {#import-with-mapping-MF} + +As this *Data Importer Document* contains a strucutre that is used as a source for *Import mapping*, we can leverage the **Import with mapping** activity to import data from input file(s). The example below shows how to import data from an Excel file. The same steps are applicable to import data from CSV files. + +1. Create a new microflow with a parameter (FileDocument) and drag the **Import with mapping** activity into it. +2. Double-click the activity and in the *Input* section > **Variable** field, select an input file (Excel or CSV). +3. Select the *Mapping* in the *Import Mapping* section. Select *Range* and *Commit* Radio buttons as per your requirement. +4. In the *Output* section, you can choose *Store in variable* and click **OK**. + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/import-with-mapping-params.png" class="no-border" >}} + +### Run your App {#data-import-with-mapping-app} + +1. Complete the Microflow to show the a page containing Entities commited after the Import activity. +2. Call this Microflow from a button on another page where a FileDocument object is created and has a provision to upload an input file. +3. Run your App locally and provide a file which is exactly like the sample file you had uploaded while creating this Data Importer document and trigger the Microflow. +4. You should see the data from the file being imported and shown on the page's Data Grid. + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/data-imported-from-input-file.png" class="no-border" >}} + + +## Edit Data Importer Document + +You can *Edit* the Data Importer Document, by uploading a new Sample file. This action will erase the existing Mapping or structure elements created for this document and will replace it with new mapping / structure elements. + +### Upload a new file {#edit-DI-document-using-new-file} + +To Edit the Data Importer Document, +1. Double-click the DI document that you want to *Edit*, it will open it in *read-only* mode. +2. Click on the **Update File** button in the top right corner and it will inform you that when a new file is uploaded and changes are saved, existing mapping/structure elements will be erased and will be replaced by new mapping/structure. + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/update-data-importer-doc-confirmation.png" class="no-border" >}} + +4. Click **Update** on the pop-up and then upload the new file. Change the configuration like *Sheet Name*, *Header Row* etc. +5. Clck on **Create Structure** if you find everything in order and the DI Document is updated. + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/data-importer-doc-updated.png" class="no-border" >}} + +Similar steps can be followed to update the DI document which was created with *Implicit Mapping* in first section. + +You can now update the Domain Model entities, MFs, pages and any other downstream documents used or referenced by this Data Importer document to reflect these changes in your App. + ## Known Issues ### Unchecked Columns From 0a59619c797f338fb90e5005c29bedd9ad962c2e Mon Sep 17 00:00:00 2001 From: Maria Shaposhnikova Date: Thu, 12 Dec 2024 10:07:34 +0100 Subject: [PATCH 2/4] High-level review --- .../modules/data-importer-extension.md | 107 ++++++++++-------- 1 file changed, 59 insertions(+), 48 deletions(-) diff --git a/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md b/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md index 86ffed50008..13965351268 100644 --- a/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md +++ b/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md @@ -14,10 +14,10 @@ The [Data Importer](https://marketplace.mendix.com/link/component/219833) allows The Data Importer is available in [Studio Pro 10.6](/releasenotes/studio-pro/10.6/) and above. {{% /alert %}} -The Data Importer Document can also be used as a source for creating *Import Mapping* [(https://docs.mendix.com/refguide/import-mappings/)]. This Import Mapping can import data from Excel/CSV file using the *Import With Mapping* [Import with Mapping](https://docs.mendix.com/refguide/import-mapping-action/) activity. +The Data Importer Document can also be used as a source for creating [Import Mapping] (/refguide/import-mappings/). This Import Mapping can import data from Excel/CSV file using the [Import with Mapping](/refguide/import-mapping-action/) activity. {{% alert color="info" %}} -This Data Importer Document as a source for Import Mapping is available in [Studio Pro 10.18](/releasenotes/studio-pro/10.18/) and above. +This Data Importer Document as a source for Import Mapping is available from [Studio Pro 10.18.0](/releasenotes/studio-pro/10.18/) and above. {{% /alert %}} ### Typical Use Cases @@ -48,7 +48,7 @@ This extension currently has the following limitations: Download the [Data Importer](https://marketplace.mendix.com/link/component/219833) from the Marketplace and [add it into your app](/appstore/use-content/). -## Data Importer Document (with Implicit Mapping) +## Data Importer Document (With Implicit Mapping) ### Creating a Data Importer Document {#create-document} @@ -129,13 +129,13 @@ Once you are satisfied with the changes, click **OK** to save or **Cancel** to d The **Edit Entity** feature is useful for CSV import, as all the columns of a CSV file are marked as String by default, so you can change the data type if necessary. The following table shows the source-to-target data conversion matrix: Input CSV File - + | Source Type | Target- String | Target- Int | Target- Long | Target- Decimal | Target- Boolean | Target- DateTime | | :-------- | :------- | :-------- | :------- | :-------- | :------- | :-------- | | String | Yes | Partial | Partial | Partial | Partial | No | Input Excel File - + | Source Type | Target- String | Target- Int | Target- Long | Target- Decimal | Target- Boolean | Target- DateTime | | :-------- | :------- | :-------- | :------- | :-------- | :------- | :-------- | | String | Yes | Partial | Partial | Partial | Partial | No | @@ -193,15 +193,18 @@ To perform testing, you can do the following actions: {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/local-app-run.png" class="no-border" >}} -## Data Importer Document (as a source for Import Mapping) +## Data Importer Document (as a Source for Import Mapping) -The [Import Mapping](https://docs.mendix.com/refguide/import-mappings/) document and the [Import with Mapping](https://docs.mendix.com/refguide/import-mapping-action/) activity porvide lot of inherent advantages like controlling the commit of objects, flexibility to find or create an object and so on. This new feature of Data Importer document leverages these capabilities by creating a source strucutre which can be used to create Import Mapping. Makers who are comfortable working with Mapping Documents[(https://docs.mendix.com/refguide/mapping-documents/)] can use this feature to address advance use-cases of importing data into Mendix. The section below describes how one can create a structure, create an Import mapping using this structure and finally leveraging the *Import with Mapping* activity in a Microflow to import data into Mendix. +The [Import Mapping](/refguide/import-mappings/) document and the [Import with Mapping](/refguide/import-mapping-action/) activity provide lot of inherent advantages like controlling the commit of objects, flexibility to find or create an object. This new feature of the Data Importer document leverages these capabilities by creating a source structure which can be used to create Import Mapping. Developers who are comfortable working with [Mapping Documents](/refguide/mapping-documents/) can use this feature to address advanced use-cases of importing data into Mendix. The section below describes how you can create a structure and an Import Mapping using this structure and finally leveraging the **Import with Mapping** microflow activity to import data into Mendix. ### Creating a Data Importer Document {#create-document-with-imm} -To import data, right-click on the module and click **Add other** > **Data Importer**. Name the document, enable the *Use with Import mapping* checkbox, click **OK**, and the new Data Importer document opens. +To import data, do the following: -{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/create-DI-doc-with-import-mapping.png" class="no-border" >}} +1. Right-click the module and click **Add other** > **Data Importer**. +2. Name the document and enable the **Use with Import mapping** checkbox. +3. Click **OK** and the new Data Importer document opens. + {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/create-DI-doc-with-import-mapping.png" class="no-border" >}} ### Previewing Structure {#preview-structure} @@ -212,74 +215,82 @@ Once you have [created the Data Importer document](#create-document-with-imm), c 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, the sheet name appears in the drop-down -* **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 Structure Elements** to view the structure of data from the file. The data from first row of the source file is shown in the *schema elements* section. Click **Create Structure** and you will be notified that a new structure is generated successfully. +* **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* -{{% alert color="warning" %}} Column names that do not adhere to Mendix naming conventions will be autocorrected. {{% /alert %}} +Click **Preview Structure Elements** to view the structure of data from the file. The data from first row of the source file is shown in the **schema elements** section. Click **Create Structure** and you will be notified that a new structure is generated successfully. {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/preview-data-structure.png" class="no-border" >}} +{{% alert color="warning" %}} Column names that do not adhere to Mendix naming conventions will be autocorrected. {{% /alert %}} + ### Create Import Mapping {#DI-import-mapping} -Using the *Data Importer Document* created in the above step, you can proceed to create *Import Mapping*. Right click on your module or folder > **Add other** > **Import mapping**. Give a proper name to the Import mapping document and Click **OK**, you will be now routed to *Select a schema element for Import mapping*. From the **Schema source**, choose the last radio button *Excel/CSV structure* and select the sheet from the Excel file which was uploaded as sample as shown in the figure below. +You can proceed to create **Import Mapping** using the **Data Importer Document** created in the step above. Do the following: + +1. Right-click your module or folder > **Add other** > **Import mapping**. +2. Give a proper name to the Import mapping document and Click **OK**. +3. You are now routed to **Select a schema element for Import mapping**. From the **Schema source**, choose the last radio button **Excel/CSV structure**. +4. Select the sheet from the Excel file which has been uploaded as sample as shown in the figure below: + {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/select-schema-elements-for-imm.png" class="no-border" >}} -{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/select-schema-elements-for-imm.png" class="no-border" >}} - -You can select ALL the columns by pressing **Check all** or selectively choose the columns that you want to import from the input file. After the selction of columns is completed, you can click **OK** to create *Import Mapping*. +5. You can either select all the columns by choosing **Check all** or selectively choose the columns that you want to import from the input file. After the selection of columns is completed, you can click **OK** to create **Import Mapping**. -{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/create-import-mapping.png" class="no-border" >}} + {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/create-import-mapping.png" class="no-border" >}} -From here, you can either choose to map an existing Entity by dragging and dropping an existing Entity from your doamin model via **Connector** tab or you can choose to press **Map automatically** to create a new NPE in your domain model. +6. You can now either choose to map an existing entity by dragging and dropping an existing entity from your domain model via the **Connector** tab or you can choose to press **Map automatically** to create a new NPE in your domain model: -{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/map-automatically.png" class="no-border" >}} + {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/map-automatically.png" class="no-border" >}} -If you choose **Map automatically*, then you can go to your *Domain Model* and change the Entity's name and persistence as per your requirement. +7. If you choose **Map automatically**, then you can go to your Domain Model and change the Entity's name and persistence as per your requirement. -{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/entity-name-persist-change.png" class="no-border" >}} + {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/entity-name-persist-change.png" class="no-border" >}} -### Import with Mapping Activity in a Microflow {#import-with-mapping-MF} +### Import With Mapping Activity in a Microflow {#import-with-mapping-MF} -As this *Data Importer Document* contains a strucutre that is used as a source for *Import mapping*, we can leverage the **Import with mapping** activity to import data from input file(s). The example below shows how to import data from an Excel file. The same steps are applicable to import data from CSV files. +As the **Data Importer Document** contains a structure that is used as a source for **Import mapping**, we can leverage the **Import with mapping** microflow activity to import data from input file(s). + +Instructions below show how to import data from an Excel file. The same steps are applicable to import data from CSV files. Do the following: 1. Create a new microflow with a parameter (FileDocument) and drag the **Import with mapping** activity into it. -2. Double-click the activity and in the *Input* section > **Variable** field, select an input file (Excel or CSV). -3. Select the *Mapping* in the *Import Mapping* section. Select *Range* and *Commit* Radio buttons as per your requirement. -4. In the *Output* section, you can choose *Store in variable* and click **OK**. - -{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/import-with-mapping-params.png" class="no-border" >}} +2. Double-click the activity and in the **Input** section > **Variable** field, select an input file (Excel or CSV). +3. Select the **Mapping** in the **Import Mapping** section. Select **Range** and **Commit** options if needed. +4. In the **Output** section, you can choose **Store in variable** and click **OK**. + {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/import-with-mapping-params.png" class="no-border" >}} + +### Before Running Your App {#data-import-with-mapping-app} -### Run your App {#data-import-with-mapping-app} +Before you can run your app, do the following: -1. Complete the Microflow to show the a page containing Entities commited after the Import activity. -2. Call this Microflow from a button on another page where a FileDocument object is created and has a provision to upload an input file. -3. Run your App locally and provide a file which is exactly like the sample file you had uploaded while creating this Data Importer document and trigger the Microflow. -4. You should see the data from the file being imported and shown on the page's Data Grid. - -{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/data-imported-from-input-file.png" class="no-border" >}} +1. Complete the microflow to show a page containing Entities committed after the Import activity. +2. Call this microflow from a button on another page where a FileDocument object is created and has a provision to upload an input file. +3. Run your app locally and provide a file which is exactly like the sample file you have uploaded while creating this **Data Importer** document and trigger the microflow. +4. You should see the data from the file being imported and shown on the page's data grid. +​ {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/data-imported-from-input-file.png" class="no-border" >}} ## Edit Data Importer Document -You can *Edit* the Data Importer Document, by uploading a new Sample file. This action will erase the existing Mapping or structure elements created for this document and will replace it with new mapping / structure elements. +You can **Edit** the **Data Importer** document, by uploading a new sample file. + +{{% alert color="warning" %}}This action will erase the existing mapping or structure elements created for this document and will replace it with new mapping / structure elements.{{% /alert %}} -### Upload a new file {#edit-DI-document-using-new-file} +### Upload a New File {#edit-DI-document-using-new-file} -To Edit the Data Importer Document, -1. Double-click the DI document that you want to *Edit*, it will open it in *read-only* mode. -2. Click on the **Update File** button in the top right corner and it will inform you that when a new file is uploaded and changes are saved, existing mapping/structure elements will be erased and will be replaced by new mapping/structure. +To edit the Data Importer Document, do the following: +1. Double-click the DI document that you want to **Edit**, it opens it in read-only mode. +2. Click the **Update File** button in the top-right corner. It will inform you that when a new file is uploaded and changes are saved, existing mapping/structure elements will be erased and will be replaced by new mapping/structure. -{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/update-data-importer-doc-confirmation.png" class="no-border" >}} + {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/update-data-importer-doc-confirmation.png" class="no-border" >}} -4. Click **Update** on the pop-up and then upload the new file. Change the configuration like *Sheet Name*, *Header Row* etc. -5. Clck on **Create Structure** if you find everything in order and the DI Document is updated. +3. Click **Update** on the pop-up and then upload the new file. Change the configuration like **Sheet Name**, **Header Row** etc. +5. Click **Create Structure** to update the DI Document. -{{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/data-importer-doc-updated.png" class="no-border" >}} + {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/data-importer-doc-updated.png" class="no-border" >}} -Similar steps can be followed to update the DI document which was created with *Implicit Mapping* in first section. +Similar steps can be followed to update the DI document which was created with **Implicit Mapping** in the [Creating a Data Importer Document](#create-document-with-imm) section. -You can now update the Domain Model entities, MFs, pages and any other downstream documents used or referenced by this Data Importer document to reflect these changes in your App. +You can now update the domain model entities, microflows,, pages and, any other documents used or referenced by this Data Importer document to reflect these changes in your app. ## Known Issues From 5f2aa5975d61c20466a40e46de30a6cb42cf7603 Mon Sep 17 00:00:00 2001 From: quinntracy Date: Fri, 13 Dec 2024 11:59:49 +0100 Subject: [PATCH 3/4] Proofread --- .../modules/data-importer-extension.md | 43 +++++++++++-------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md b/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md index 13965351268..4c88042ab5a 100644 --- a/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md +++ b/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md @@ -8,16 +8,16 @@ aliases: ## Introduction -The [Data Importer](https://marketplace.mendix.com/link/component/219833) allows you to import data from an Excel or comma-separated value (CSV) file. You can choose which sheet and columns to import, preview the data, and create a non-persistable entity (NPE) in your domain model that corresponds to your input. Then, you can import data into your app using the [Import Data from File](/refguide/import-data-from-file/) activity. - {{% alert color="info" %}} The Data Importer is available in [Studio Pro 10.6](/releasenotes/studio-pro/10.6/) and above. {{% /alert %}} -The Data Importer Document can also be used as a source for creating [Import Mapping] (/refguide/import-mappings/). This Import Mapping can import data from Excel/CSV file using the [Import with Mapping](/refguide/import-mapping-action/) activity. +The [Data Importer](https://marketplace.mendix.com/link/component/219833) allows you to import data from an Excel or comma-separated value (CSV) file. You can choose which sheet and columns to import, preview the data, and create a non-persistable entity (NPE) in your domain model that corresponds to your input. Then, you can import data into your app using the [Import Data from File](/refguide/import-data-from-file/) activity. + +The Data Importer Document can also be used as a source for creating [Import Mapping](/refguide/import-mappings/). This import mapping can import data from Excel/CSV file using the [Import with Mapping](/refguide/import-mapping-action/) activity. {{% alert color="info" %}} -This Data Importer Document as a source for Import Mapping is available from [Studio Pro 10.18.0](/releasenotes/studio-pro/10.18/) and above. +The Data Importer document as a source for import mapping is available from [Studio Pro 10.18.0](/releasenotes/studio-pro/10.18/) and above. {{% /alert %}} ### Typical Use Cases @@ -195,15 +195,16 @@ To perform testing, you can do the following actions: ## Data Importer Document (as a Source for Import Mapping) -The [Import Mapping](/refguide/import-mappings/) document and the [Import with Mapping](/refguide/import-mapping-action/) activity provide lot of inherent advantages like controlling the commit of objects, flexibility to find or create an object. This new feature of the Data Importer document leverages these capabilities by creating a source structure which can be used to create Import Mapping. Developers who are comfortable working with [Mapping Documents](/refguide/mapping-documents/) can use this feature to address advanced use-cases of importing data into Mendix. The section below describes how you can create a structure and an Import Mapping using this structure and finally leveraging the **Import with Mapping** microflow activity to import data into Mendix. +The [Import Mapping](/refguide/import-mappings/) document and the [Import with Mapping](/refguide/import-mapping-action/) activity provide inherent advantages, like controlling the commit of objects, and the flexibility to find or create an object. This new feature of the Data Importer document leverages these capabilities by creating a source structure, which can be used to create import mappings. If you are comfortable working with [Mapping Documents](/refguide/mapping-documents/), you can use this feature to address advanced use cases of importing data into Studio Pro. The section below describes how to create a structure, an import mapping using this structure, and leveraging the **Import with Mapping** microflow activity to import data into Studio Pro. ### Creating a Data Importer Document {#create-document-with-imm} To import data, do the following: 1. Right-click the module and click **Add other** > **Data Importer**. -2. Name the document and enable the **Use with Import mapping** checkbox. +2. Name the document and enable the **Use with Import Mapping** checkbox. 3. Click **OK** and the new Data Importer document opens. + {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/create-DI-doc-with-import-mapping.png" class="no-border" >}} ### Previewing Structure {#preview-structure} @@ -212,13 +213,13 @@ Once you have [created the Data Importer document](#create-document-with-imm), c {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/select-file-for-structure-preview.png" class="no-border" >}} -You can choose which sheet to import data from and specify the header row and starting data row. +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, the sheet name appears in the drop-down -* **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 file has multiple worksheets, the sheet name appears in the drop-down +* **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 Structure Elements** to view the structure of data from the file. The data from first row of the source file is shown in the **schema elements** section. Click **Create Structure** and you will be notified that a new structure is generated successfully. +Click **Preview Structure Elements** to view the data structure from the file. The data from the first row of the source file is shown in the **Schema elements** section. Click **Create Structure** and you will be notified that a new structure is generated successfully. {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/preview-data-structure.png" class="no-border" >}} @@ -226,23 +227,27 @@ Click **Preview Structure Elements** to view the structure of data from the file ### Create Import Mapping {#DI-import-mapping} -You can proceed to create **Import Mapping** using the **Data Importer Document** created in the step above. Do the following: +Create the import mapping using the Data Importer document created in the step above by doing the following: -1. Right-click your module or folder > **Add other** > **Import mapping**. -2. Give a proper name to the Import mapping document and Click **OK**. -3. You are now routed to **Select a schema element for Import mapping**. From the **Schema source**, choose the last radio button **Excel/CSV structure**. -4. Select the sheet from the Excel file which has been uploaded as sample as shown in the figure below: +1. Right-click your module or folder and select **Add other** > **Import mapping**. +2. Name the import mapping document, then click **OK**. You are then routed to **Select a schema element for import mapping**. +3. From the **Schema source**, choose **Excel/CSV structure**. +4. Select the sheet from the Excel file that has been uploaded as a sample, as shown in the image below: + {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/select-schema-elements-for-imm.png" class="no-border" >}} -5. You can either select all the columns by choosing **Check all** or selectively choose the columns that you want to import from the input file. After the selection of columns is completed, you can click **OK** to create **Import Mapping**. +5. Select the columns you want to import. You can either select all the columns by choosing **Check all** or select individual columns. +6. Click **OK** to create the **Import Mapping**. {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/create-import-mapping.png" class="no-border" >}} -6. You can now either choose to map an existing entity by dragging and dropping an existing entity from your domain model via the **Connector** tab or you can choose to press **Map automatically** to create a new NPE in your domain model: +7. You can now choose to: + 1. Map an existing entity by dragging and dropping an entity from your domain model via the **Connector** tab + 2. Click **Map automatically** to create a new NPE in your domain model: {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/map-automatically.png" class="no-border" >}} -7. If you choose **Map automatically**, then you can go to your Domain Model and change the Entity's name and persistence as per your requirement. +8. If you choose **Map automatically**, you can open the domain model and change the entity's name and persistence, as per your requirement. {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/entity-name-persist-change.png" class="no-border" >}} From 51d0593b7048eedb43046cbff7a58154553ba848 Mon Sep 17 00:00:00 2001 From: quinntracy Date: Fri, 13 Dec 2024 12:07:52 +0100 Subject: [PATCH 4/4] Proofread --- .../modules/data-importer-extension.md | 44 +++++++++++-------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md b/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md index 4c88042ab5a..60ae4e52ee9 100644 --- a/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md +++ b/content/en/docs/appstore/use-content/platform-supported-content/modules/data-importer-extension.md @@ -253,49 +253,55 @@ Create the import mapping using the Data Importer document created in the step a ### Import With Mapping Activity in a Microflow {#import-with-mapping-MF} -As the **Data Importer Document** contains a structure that is used as a source for **Import mapping**, we can leverage the **Import with mapping** microflow activity to import data from input file(s). +As the Data Importer document contains a structure that is used as a source for import mapping, you can leverage the **Import with mapping** microflow activity to import data from input file(s). -Instructions below show how to import data from an Excel file. The same steps are applicable to import data from CSV files. Do the following: +The instructions below show how to import data from an Excel (or CSV) file. 1. Create a new microflow with a parameter (FileDocument) and drag the **Import with mapping** activity into it. -2. Double-click the activity and in the **Input** section > **Variable** field, select an input file (Excel or CSV). -3. Select the **Mapping** in the **Import Mapping** section. Select **Range** and **Commit** options if needed. -4. In the **Output** section, you can choose **Store in variable** and click **OK**. +2. Double-click the activity. +3. In the **Input** section, in the **Variable** field, select an input file (Excel or CSV). +4. Select the mapping in the **Import Mapping** section. +5. Select **Range** and **Commit** options, if needed. +6. In the **Output** section, you can choose **Store in variable**, then click **OK**. + {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/import-with-mapping-params.png" class="no-border" >}} ### Before Running Your App {#data-import-with-mapping-app} Before you can run your app, do the following: -1. Complete the microflow to show a page containing Entities committed after the Import activity. -2. Call this microflow from a button on another page where a FileDocument object is created and has a provision to upload an input file. -3. Run your app locally and provide a file which is exactly like the sample file you have uploaded while creating this **Data Importer** document and trigger the microflow. -4. You should see the data from the file being imported and shown on the page's data grid. -​ {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/data-imported-from-input-file.png" class="no-border" >}} +1. Complete the microflow to show a page containing the entities committed after the import activity. +2. Call this microflow from a button on another page where a *FileDocument* object is created and has a provision to upload an input file. +3. Run your app locally and provide a file which is exactly like the sample file you have uploaded while creating this Data Importer document, then trigger the microflow. +You should see the data from the file being imported and shown on the page's data grid. + +​ {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/data-imported-from-input-file.png" class="no-border" >}} ## Edit Data Importer Document -You can **Edit** the **Data Importer** document, by uploading a new sample file. +You can edit the Data Importer document by uploading a new sample file. -{{% alert color="warning" %}}This action will erase the existing mapping or structure elements created for this document and will replace it with new mapping / structure elements.{{% /alert %}} +{{% alert color="warning" %}}This action will erase the existing mapping or structure elements created for this document, and will replace it with new mapping and structure elements.{{% /alert %}} ### Upload a New File {#edit-DI-document-using-new-file} -To edit the Data Importer Document, do the following: -1. Double-click the DI document that you want to **Edit**, it opens it in read-only mode. -2. Click the **Update File** button in the top-right corner. It will inform you that when a new file is uploaded and changes are saved, existing mapping/structure elements will be erased and will be replaced by new mapping/structure. +To edit the Data Importer document, do the following: + +1. Double-click the Data Importer document that you want to **Edit**. The document opens in read-only mode. +2. Click **Update File** in the top-right corner. You will receive notification that when a new file is uploaded and changes are saved, existing mapping/structure elements will be erased and will be replaced by new mapping/structure. {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/update-data-importer-doc-confirmation.png" class="no-border" >}} -3. Click **Update** on the pop-up and then upload the new file. Change the configuration like **Sheet Name**, **Header Row** etc. -5. Click **Create Structure** to update the DI Document. +3. Click **Update**, then upload the new file. +4. Change the configuration, such as **Sheet Name** and **Header Row**. +5. Click **Create Structure** to update the document. {{< figure src="/attachments/appstore/platform-supported-content/modules/data-importer-extension/data-importer-doc-updated.png" class="no-border" >}} -Similar steps can be followed to update the DI document which was created with **Implicit Mapping** in the [Creating a Data Importer Document](#create-document-with-imm) section. +Similar steps can be followed to update the Data Importer document, which was created with **Implicit Mapping** in the [Creating a Data Importer Document](#create-document-with-imm) section. -You can now update the domain model entities, microflows,, pages and, any other documents used or referenced by this Data Importer document to reflect these changes in your app. +You can now update the domain model entities, microflows, pages, and any other documents used or referenced by this Data Importer document to reflect the changes in your app. ## Known Issues