Working with Document Change

In this article

Introduction

In this page we will be going through all the possible operations that can be done using the Banana API Document Change in order to modify in any way our accounting document. Every time we are going to write Javascript code which will produce a JSON File containing all the changes we want to make on the Banana accounting file.

JSON File

A JSON (Javascript Object Notation) File is a particular type of file that let us store and transmit data objects, more in particular we are going to use them to describe which elements of the accounting file we want to change and in what the changes consists.

To have a more complete view on how JSON files are used in Banana and on their structure for various operations, you can always visit the following page: Banana Document Change.

Add Operation

In this section we are going to see how to add some transactions in Banana using the command add, the following function can be added to our code by simply changing the name "transactionRowOperation()" when it's invoked in our Main Program with "transactionRowAdd()".

Steps to add rows:

  1. Define row object
  2. choose which operation we are going to perform, in this case "add"
  3. Define the fields we are going to add in our row, in this case "Date" and "Description".
  4. Create an Array which will contain all the rows we want to add, and then push to the Array those rows.
  5. Define the table in which we are going to make changes in Banana.
  6. Initialise JSON document object.
  7. add changes to the object.

function transactionRowAdd(){
    //row operation
    var row = {};
    row.operation = {};
    row.operation.name = "add";

    //row fields
    row.fields = {};
    row.fields["Date"] = getCurrentDate();
    row.fields["Description"] = "This is the row you just added";

    //rows
    var rows = [];
    rows.push(row);

    //table
    var dataUnitTransactions = {};
    dataUnitTransactions.nameXml = "Transactions";
    dataUnitTransactions.data = {};
    dataUnitTransactions.data.rowLists = [];
    dataUnitTransactions.data.rowLists.push({"rows":rows});

    //document
    var jsonDoc = initDocument();
    jsonDoc.data.document.dataUnits.push(dataUnitTransactions);

    return jsonDoc;
}

It is worth mentioning that after have defined the row.operation.name = "add" if we also define row.operation.sequence = "n" we are going to perform an Insert Operation, adding the new row after the nth row in the Transactions table.

Delete Operation

In this section we are going to see how to delete some transactions in Banana using the command delete, the following function can be added to our code by simply changing the name "transactionRowOperation()" when it's invoked in our Main Program with "transactionRowDelete()".

Steps to delete rows:

  1. Define row object
  2. Choose which operation we are going to perform, in this case "delete"
  3. Define in row.operation.sequence = "n" where n is the row that we want to delete from the table.
  4. Create an Array which will contain all the rows we want to delete, and then push to the Array those rows.
  5. Define the table in which we are going to make changes in Banana.
  6. Initialise JSON document object.
  7. add changes to the object.

function transactionRowDelete(){
    //row operation
    var row = {};
    row.operation = {};
    row.operation.name = "delete";
    row.operation.sequence = "5";

    //rows
    var rows = [];
    rows.push(row);

    //table
    var dataUnitTransactions = {};
    dataUnitTransactions.nameXml = "Transactions";
    dataUnitTransactions.data = {};
    dataUnitTransactions.data.rowLists = [];
    dataUnitTransactions.data.rowLists.push({"rows":rows});

    //document
    var jsonDoc = initDocument();
    jsonDoc.data.document.dataUnits.push(dataUnitTransactions);

    return jsonDoc;
}

Modify Operation

In this section we are going to see how to modify some transactions in Banana using the command modify, the following function can be added to our code by simply changing the name "transactionRowOperation()" when it's invoked in our Main Program with "transactionRowModify()".

Steps to modify rows:

  1. Define row object
  2. Choose which operation we are going to perform, in this case "modify"
  3. Define in row.operation.sequence = "n" where n is the row that we want to modify from the table.
  4. Define the fields we are going to modify in our row, in this case "Description".
  5. Create an Array which will contain all the rows we want to modify, and then push to the Array those rows.
  6. Define the table in which we are going to make changes in Banana.
  7. Initialise JSON document object.
  8. add changes to the object.

function transactionRowModify(){
    //row operation
    var row = {};
    row.operation = {};
    row.operation.name = "modify";
    row.operation.sequence = "5";

    //row fields
    row.fields = {};
    row.fields["Description"] = "This description is edited using Document Change";

    //rows
    var rows = [];
    rows.push(row);

    //table
    var dataUnitTransactions = {};
    dataUnitTransactions.nameXml = "Transactions";
    dataUnitTransactions.data = {};
    dataUnitTransactions.data.rowLists = [];
    dataUnitTransactions.data.rowLists.push({"rows":rows});

    //document
    var jsonDoc = initDocument();
    jsonDoc.data.document.dataUnits.push(dataUnitTransactions);

    return jsonDoc;
}

Replace Operation

In this section we are going to see how to replace some transactions in Banana using the command replace, the following function can be added to our code by simply changing the name "transactionRowOperation()" when it's invoked in our Main Program with "transactionRowReplace()".

Steps to replace rows:

  1. Define row object
  2. Choose which operation we are going to perform, in this case "replace"
  3. Define in row.operation.sequence = "n" where n is the row that we want to replace from the table.
  4. Define the fields we are going to modify in our row, in this case "Description".
  5. Create an Array which will contain all the rows we want to modify, and then push to the Array those rows.
  6. Define the table in which we are going to make changes in Banana.
  7. Initialise JSON document object.
  8. add changes to the object.

function transactionRowReplace(){
    //row operation
    var row = {};
    row.operation = {};
    row.operation.name = "replace";
    row.operation.sequence = "5";

    //row fields
    row.fields = {};
    row.fields["Description"] = "We have replaced the old transaction with this one";

    //rows
    var rows = [];
    rows.push(row);

    //table
    var dataUnitTransactions = {};
    dataUnitTransactions.nameXml = "Transactions";
    dataUnitTransactions.data = {};
    dataUnitTransactions.data.rowLists = [];
    dataUnitTransactions.data.rowLists.push({"rows":rows});

    //document
    var jsonDoc = initDocument();
    jsonDoc.data.document.dataUnits.push(dataUnitTransactions);

    return jsonDoc;
}

We can see how the structure for Replace and Modify operation is more or less the same, the difference is the fact that when we perform a Modify only the field we choose are modified and all the other parts of the row remain the same as before, instead while we perform a Replace, all the field are changed with the one we defined in the functions, and if we have not defined any value for some fields, those will be empty.

Move Operation

In this section we are going to see how to replace some transactions in Banana using the command replace, the following function can be added to our code by simply changing the name "transactionRowOperation()" when it's invoked in our Main Program with "transactionRowMove()".

Steps to move rows:

  1. Define row object
  2. Choose which operation we are going to perform, in this case "move"
  3. Define row.operation.sequence = "n" where n is the row that we want to move from the table.
  4. Define row.operation.moveTo = "n" where n is the row where we want to move in.
  5. Create an Array which will contain all the rows we want to modify, and then push to the Array those rows.
  6. Define the table in which we are going to make changes in Banana.
  7. Initialise JSON document object.
  8. add changes to the object.

function transactionRowMove(){
    //row operation
    var row = {};
    row.operation = {};
    row.operation.name = "move";
    row.operation.sequence = "5";
    row.operation.moveTo = "8";
    
    //row fields
    row.fields = {};

    //rows
    var rows = [];
    rows.push(row);

    //table
    var dataUnitTransactions = {};
    dataUnitTransactions.nameXml = "Transactions";
    dataUnitTransactions.data = {};
    dataUnitTransactions.data.rowLists = [];
    dataUnitTransactions.data.rowLists.push({"rows":rows});

    //document
    var jsonDoc = initDocument();
    jsonDoc.data.document.dataUnits.push(dataUnitTransactions);

    return jsonDoc;
}

Initialise Document

From the above functions that we are always returning a JSON document, in order to initialise it we have to define the following parameters for the object:


function initDocument() {
    var jsonDoc = {};
    jsonDoc.format = "documentpatch";
    jsonDoc.data.document = {};
    jsonDoc.data.document.fileVersion = "1.0.0";
    jsonDoc.data.document.dataUnits = [];
    jsonDoc.creator = {};
    jsonDoc.creator.executionDate = getCurrentDate();
    jsonDoc.creator.executionTime = getCurrentTime();
    jsonDoc.creator.name = Banana.script.getParamValue('id');
    jsonDoc.creator.version = "1.0";
    return jsonDoc;
}

Helper Functions

As we can see from the code above from the section Initialise Document, there are few undefined functions called getCurrentDate() and getCurrentTime(), we can proceed defining them in the program as:


function getCurrentDate() {
    var d = new Date();
    var datestring = d.getFullYear() + ("0" + (d.getMonth() + 1)).slice(-2) + ("0" + d.getDate()).slice(-2);
    return Banana.Converter.toInternalDateFormat(datestring, "yyyymmdd");
}

function getCurrentTime() {
    var d = new Date();
    var timestring = ("0" + d.getHours()).slice(-2) + ":" + ("0" + d.getMinutes()).slice(-2);
    return Banana.Converter.toInternalTimeFormat(timestring, "hh:mm");
}

 

This documentation is outdated

The most complete and up-to-date documentation is the one of Banana Accounting Plus: Try it now

Share this article: Twitter | Facebook | LinkedIn | Email