Introduction to File Parsers

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!