com.isomorphic.tools

## Class BatchUpload

- java.lang.Object
- - com.isomorphic.base.Base
  - - com.isomorphic.tools.BatchUpload

-     public class BatchUpload
      extends Base

  This class implements the server side of the BatchUploader tool. See the client-side docs for full details of this feature. NOTE: this feature is only available with a Power or better license.

- - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `DSResponse` | `batchUpload(DSRequest dsRequest)` Takes an DSRequest sent by the BatchUploader UI component, which contains an uploaded CSV file and target DataSource, and returns a DSResponse containing the rows validated against the target DataSource.
    `DSResponse` | `parseUploadData(DSRequest dsRequest)` Parses inbound `DSRequest` and returns `DSResponse` containing parsed uploaded data or error message if parsing failed.
    `DSResponse` | `validateUploadData(DSResponse dsResponse)` Validates provided records against the target DataSource and returns DSResponse containing records to be imported and validation errors (if any).

- - ### Method Detail

    - #### batchUpload

          public DSResponse batchUpload(DSRequest dsRequest)
                                 throws java.lang.Exception

      Takes an DSRequest sent by the BatchUploader UI component, which contains an uploaded CSV file and target DataSource, and returns a DSResponse containing the rows validated against the target DataSource.

      This API may only be used by the BatchUploader UI component. It is documented solely to allow pre- or post-processing checks to be added as a substitute DMI for the default DMI declared in `batchUpload.ds.xml`.

      For checks involving the uploaded file, the binary field name is always "file" (so getUploadedFileStream("file") allows access to the uploaded CSV InputStream, just as it would for any other binary field named "file").

      For adding custom validation checks that could not be covered by standard per-field validation, subclass `DataSource` you are using and override `DataSource.validate(Map, ErrorReport)`.

      There are scenarios when mentioned earlier pre- and post-processing approach is not enough. For example if uploaded data needs to be transformed in a certain way before initial validation. In this case, instead of calling `batchUpload()` method from a custom DMI, you should first call `BatchUpload.parseUploadData(DSRequest)` to get access to the `DSResponse` holding uploaded data and make any transformations needed. Then pass this `DSResponse` holding transformed (may be as well unchanged) data to the `BatchUpload.validateUploadData(DSResponse)` method, which will validate data against target DataSource and produce DSResponse for the BatchUploader UI. See example of how custom DMI may look like. Note that example also shows how to obtain dataSource name, which may be useful if performed transformations are dataSource specific:

           public DSResponse batchUpload(DSRequest dsRequest) throws Exception {
               BatchUpload batchUpload = new BatchUpload();

               // parse data and get the result Map
               DSResponse response = batchUpload.parseUploadData(dsRequest);
               Map respData = response.getDataMap();

               // do not proceed to validation if parsing failed
               if (respData.containsKey("errorMessage")) return response;

               // get dataSource name
               Map values = dsRequest.getValues();
               String dataSourceName = (String) values.get("dsName");

               // get upload data
               List<Map> uploadData = (List<Map>) respData.get("gridRows");

               // perform data manipulations
               ...

               // validate data and return
               return batchUpload.validateUploadData(response);
           }

      NOTE: the BatchUploader feature as a whole is only available with a Power or better license.

      Parameters:
        `dsRequest` - inbound DSRequest containing the uploaded CSV file
      Returns:
        DSResponse containing the rows parsed from CSV, with validation errors if any
      Throws:
        `java.lang.Exception` - if an exception occurs during validation

    - #### parseUploadData

          public DSResponse parseUploadData(DSRequest dsRequest)
                                     throws java.lang.Exception

      Parses inbound `DSRequest` and returns `DSResponse` containing parsed uploaded data or error message if parsing failed. These can be accessed via `DSResponse.getData()`, which in this case will always be a `Map` holding error message under the `"errorMessage"` key and parsed data under the `"gridRows"` key.

      Note: in order to keep BatchUploader UI working as expected, do not change the top-level structure of this `Map`.

      Parameters:
        `dsRequest` - inbound DSRequest containing the uploaded CSV file
      Returns:
        DSResponse containing parsed upload data from CSV
      Throws:
        `java.lang.Exception` - if an exception occurs during parsing

    - #### validateUploadData

          public DSResponse validateUploadData(DSResponse dsResponse)
                                        throws java.lang.Exception

      Validates provided records against the target DataSource and returns DSResponse containing records to be imported and validation errors (if any).
      Parameters:
        `dsResponse` - returned by `BatchUpload.parseUploadData(DSRequest)` holding parsed upload data
      Returns:
        DSResponse containing the rows parsed from CSV, with validation errors if any
      Throws:
        `java.lang.Exception` - if an exception occurs during validation