Introduction to File Parsers – QBench LIMS Help Center

What is a File Parser?

A File Parser is a custom JavaScript template saved in QBench that can parse common files and process the file data to modify or create entities within QBench.

Creating a basic File Parser:

In this basic tutorial, we will go through the steps to update a batch worksheet using a file parser.

Set up:

Worksheet Setup:

Create a new Worksheet and add this code in the “Configuration” tab:

Input1: __(input, input1)__<br>
Input2: __(input, input2)__<br>
Input3: __(input, input3)__<br>
Calculation: __(calculation, calc1, input1 + input2 + input3)__<br>

Save the Worksheet as a new version and make the version active.

Batch Setup:

Create a new Batch.
Add the new Worksheet we created to the Batch and Save.

The Worksheet on the Batch should have 3 empty inputs.
Remember your Batch ID as we will need it in the next setup.

Import File Setup:

Create a file on your local machine called “import.csv”.
Add this data to your “import.csv” file and save.

batch_id	input1	input2	input3
YOUR_BATCH_ID	1	2	3

NOTE: Make sure to replace “YOUR_BATCH_ID” with the ID from the Batch you created in the previous step.

File Parser Creation:

Create a new File Parser.
In the “Configuration” tab, there should be some template code pre-filled in the code editor that will look like this

importScripts('https://d30nr38ylt5b32.cloudfront.net/v1.0.0/file_parser.js');
importScripts('https://d731z7k534aiw.cloudfront.net/v1.0.0/qbjs.js');

// Documentation for QBJS: https://qbjs.docs.qbench.net

run(() => {

    const qbConsole = QB.console; // Object to write to the console
    const qbProgressBar = QB.progressBar; // Object to control the progress bar
    const files = QB.files; // Array of files selected to upload

try {
    // Your code here...

    /* ---------------------------------- */
    /* Example Code */
    qbProgressBar.setPercentage(0);
    qbConsole.clear();

    qbConsole.log('Begin process...');
    qbConsole.log(`Files to process: ${files.length}`);
    qbProgressBar.setPercentage(50);
    setTimeout(() => {
        qbProgressBar.setPercentage(100);
        qbConsole.log('Finished!');

        // Notifies QBench that the script finished successfully
        // NOTE: should be included in every file parser script
        QB.success();
    }, 3000);
    /* ---------------------------------- */ 
} catch(e) {
    // Notifies QBench that the script finished with an error
    // NOTE: should be included in every file parser script
    qbConsole.log(`ERROR: ${e.message}`);
    QB.error();
    }
});

First, let’s initialize the console and the progress bar that the user will be viewing.

Replace everything in the “try” block with this code block:

const BatchService = new QBBatchService;
qbProgressBar.setPercentage(0);
qbConsole.clear();
qbConsole.log('Begin process...');
qbConsole.log(`Files to process: ${QB.files.length}`);

This will set the progress bar percentage to 0, clear the console, and write some basic logs letting the user know that the process has begun.
This also creates an instance of the “QBBatchService” class from our “qbjs.js” import. This “BatchService” instance will be used to update our Batch Worksheet.
Next, we need to process the data from our “import.csv” file.

NOTE: This file will be accessible from the “QB.files” variable.
Under our “qbConsole.log()” calls, let’s add this code block to get the data from our file:

const BatchService = new QBBatchService;
qbProgressBar.setPercentage(0);
qbConsole.clear();
qbConsole.log('Begin process...');
qbConsole.log(`Files to process: ${QB.files.length}`);

QB.files[0].text().then(fileData => {
   fileData = fileData.split('\n');

   let headers = fileData[0].split(',');
   let data = fileData[1].split(',');
   let batchId = data[0];
   let input1 = data[1];
   let input2 = data[2];
   let input3 = data[3];

});

With this code, we will have:

Our Batch ID that we created in the Batch Setup stage saved in a variable called “batchId”.
The headers from our CSV file saved in an Array called “headers”.
The values from our CSV file saved in 3 variables called “input1”, “input2” and “input3”.

Now, we can construct that Worksheet Data Payload to update the Batch Worksheet.

Create a new javascript object variable called "worksheetData" like so:

const BatchService = new QBBatchService;
qbProgressBar.setPercentage(0);
qbConsole.clear();
qbConsole.log('Begin process...');
qbConsole.log(`Files to process: ${QB.files.length}`);

QB.files[0].text().then(fileData => {
   fileData = fileData.split('\n');
      
   let headers = fileData[0].split(',');
   let data = fileData[1].split(',');
   let batchId = data[0];
   let input1 = data[1];
   let input2 = data[2];
   let input3 = data[3];

   let worksheetData = {
       input1: {
           value: input1
       },
       input2: {
           value: input2
       },
       input3: {
           value: input3
       },
   }

});

Finally, we will utilize the “BatchService” class that we instantiated earlier to update the Batch worksheet:

const BatchService = new QBBatchService;
qbProgressBar.setPercentage(0);
qbConsole.clear();
qbConsole.log('Begin process...');
qbConsole.log(`Files to process: ${QB.files.length}`);

QB.files[0].text().then(fileData => {
   fileData = fileData.split('\n');

   let headers = fileData[0].split(',');
   let data = fileData[1].split(',');
   let batchId = data[0];
   let input1 = data[1];
   let input2 = data[2];
   let input3 = data[3];

   let worksheetData = {
       input1: {
           value: input1
       },
       input2: {
           value: input2
       },
       input3: {
           value: input3
       },
   }

   BatchService.updateWorksheet({
       batchId: batchId,
       worksheetData: worksheetData,
       success: () => {
           qbConsole.log(`Batch ID: ${batchId} worksheet has been updated!`);
           qbProgressBar.setPercentage(100);
           qbConsole.log(`Finished!`);
           QB.success();
       },
       error: QB.error
   });
});

NOTE: Notice at the end of the success callback we call “QB.success()”, this tells QBench that your file parser has completed successfully.
After these steps have been completed, your finished file parser template should look like this:

importScripts('https://d30nr38ylt5b32.cloudfront.net/v1.0.0/file_parser.js');
importScripts('https://d731z7k534aiw.cloudfront.net/v1.0.0/qbjs.js');

// Documentation for QBJS: https://qbjs.docs.qbench.net

run(() => {
  try {

       const qbConsole = QB.console; // Object to write to the console
       const qbProgressBar = QB.progressBar; // Object to control the progress bar
       const files = QB.files; // Array of files selected to upload

       const BatchService = new QBBatchService;
       qbProgressBar.setPercentage(0);
       qbConsole.clear();
       qbConsole.log('Begin process...');
       qbConsole.log(`Files to process: ${QB.files.length}`);

       QB.files[0].text().then(fileData => {
           fileData = fileData.split('\n');

           let headers = fileData[0].split(',');
           let data = fileData[1].split(',');
           let batchId = data[0];
           let input1 = data[1];
           let input2 = data[2];
           let input3 = data[3];

           let worksheetData = {
               input1: {
                   value: input1
               },
               input2: {
                   value: input2
               },
               input3: {
                   value: input3
               },
           }

           BatchService.updateWorksheet({
               batchId: batchId,
               worksheetData: worksheetData,
               success: () => {
                   qbConsole.log(`Batch ID: ${batchId} worksheet has been updated!`);
                   qbProgressBar.setPercentage(100);
                   qbConsole.log(`Finished!`);
                   QB.success();
               },
               error: QB.error
           });
       });
  } catch(e) {
      // Notifies QBench that the script finished with an error
      // NOTE: should be included in every file parser script
      qbConsole.log(`ERROR: ${e.message}`);
      QB.error();
  }
});

Save the file parser as a new Version and make that version Active.

Running the File Parser:

Now that you’ve set up your File Parser, you should be able to import the data from your “import.csv” file to update your Batch Worksheet.

Click on the new upload button in the Navbar (located on the right side of the Navbar).
Select your File Parser template that we created.
Choose the “import.csv” file that we also created.
Hit “Submit”.
Once the File Parser has completed, refresh the Batch page to view the updated data in the Worksheet!

If you setup a Trigger under the Configuration tab, you can run the File Parser by satisfying the trigger requirements. For example, if your trigger is "When file is added to Test attachments" and the filename should end with ".csv", you can upload an Attachment to a Test with the filename "import.csv" to run this File Parser. This also works via the API. See the Attachment API documentation for details