Package com.isomorphic.tools

# Class BatchUpload

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

All Implemented Interfaces:
  `com.isomorphic.base.IAutoConfigurable`

public class BatchUpload extends com.isomorphic.base.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

  Modifier and Type
  Method
  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 Details

  - ### batchUpload

    public DSResponse batchUpload(DSRequest dsRequest) throws 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 `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 `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:
      `Exception` - if an exception occurs during validation

  - ### parseUploadData

    public DSResponse parseUploadData(DSRequest dsRequest) throws 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:
      `Exception` - if an exception occurs during parsing

  - ### validateUploadData

    public DSResponse validateUploadData(DSResponse dsResponse) throws 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 `parseUploadData(DSRequest)` holding parsed upload data
    Returns:
      DSResponse containing the rows parsed from CSV, with validation errors if any
    Throws:
      `Exception` - if an exception occurs during validation