MENU

Connector-Adaptor-MYOB-AccountRight-(version-2013-2016)

The Connector's MYOB AccountRight adaptor supports connecting to the AccountRight Enterprise Resource Planning (ERP) system, which is developed by MYOB Technology Pty Ltd. The adaptor supports obtaining data from the system for versions 2013 and higher that are hosted locally or within MYOB's Cloud.

Topics

  1. Prerequisites
  2. Overview of Data Connectivity
  3. Adaptor Setup
  4. MYOB AccountRight Setup
  5. General Settings Configuration
  6. Adaptor Data Exports
  7. Data Export URL Hooks
  8. Data Export JSON Record Traversal
  9. Data Export Field JSON Functions
  10. Adaptor Routines

Prerequisites

Please make sure you have read through the Get Started/Overview before continuing down this document.

Also make sure you understand the concepts of:

Overview of Data Connectivity

The adaptor connects to a MYOB AccountRight installation through 2 different ways, based on if the AccountRight company file is locally hosted in MYOB AccountRight software installed on a computer, or else if the AccountRight company file is hosted within MYOB's Cloud platform. The AccountRight company file contains all the accounting data and settings for a single business.

Locally Hosted AccountRight Installation

If the AccountRight company file is hosted on a computer controlled by a business, then the adaptor connects to the AccountRight software through the use of AccountRight's "MYOB Add-on Connector" software which comes bundled with the AccountRight installation. The adaptor talks to the Add-on Connector using the HTTP protocol, making requests to its API (Application Programming Interface). Specifically the adaptor is configured to read and write data from version 2 of MYOB's AccountRight API, which is a RESTful webservice that supports the OData standards for querying/writing data from a webservice. The adaptor is granted permission to talk to the MYOB Add-on Connector service by logging in as an AccountRight user to a chosen Company File.

MYOB AccountRight adaptor system dialog

The adaptor imports and exports data by sending HTTP requests that contain JSON (JavaScript Object Notation) documents to the MYOB Add-on Connector service. Unlike SQL based relational databases, JSON documents support storing data in hierarchical structures (as opposed to table structures). To be able to obtain data in JSON documents functions have been built into the adaptor that allow traversing a JSON document to obtain different field data for each exported record.

MYOB Cloud Hosted AccountRight Installation

If the AccountRight company file is hosted on MYOB's Cloud platform then the adaptor connects to the AccountRight company file over the internet through the API (Application Programming Interface) controlled by the MYOB's Cloud platform. The adaptor talks to the API using the HTTP protocol, making requests to its API (Application Programming Interface). Specifically the adaptor is configured to read and write data from version 2 of MYOB's AccountRight API, which is a RESTful webservice that supports the OData standards for querying/writing data from a webservice. The adaptor is granted permission to talk to the MYOB API service by logging in as an AccountRight user to a chosen Company File, after first authenticating itself to the API through the use of Access tokens. The adaptor first uses a Redirect Oauth Token to obtain an Access Oauth Token by making a call to MYOB's cloud API. Once the adaptor is able to successfully obtain an Access Token then it can make a request to export or import data into the AccountRight company file hosted on MYOB's cloud platform.

In order to obtain Redirect Oauth Token as well as make requests to the MYOB cloud platform API/developer credentials must be set up in MYOB's cloud, either by MYOB partners, or by purchasing a developer license from MYOB. Once these credentials have been set up, then a person who can login to MYOB's my.myob.com.au portal to access the AccountRight company file software needs to grant access to the developer/API software to allow it to get access to a business's company file. A URL is called from the my.myob.com.au to obtain an Access Code (a one time use code). This code can then be set within the adaptor's "MYOB Cloud Access Utility" window to generate a Redirect Oauth Token, which can be saved to the adaptor. The adaptor continually uses the Redirect Oauth Token to generate new Access Oauth Token each time a data export or data import is called on the hosted AccountRight company file. A new Access Token is created each time a data import or data export is called since the Access Tokens only last for a very short period of time (typically 20 minutes).

Another point to note is that the AccountRight Company file can be accessed and hosted from different domains within MYOB's cloud. Because of this the adaptor needs to be given the exact domain that the CompanyFile is hosted on, and may needed to be updated on a regular basis if MYOB continually changes domains that company files are hosted on. You can use the "MYOB Cloud Access Utility" window within the adaptor's Settings window to also determine the domain that a company file is hosted on within MYOB's cloud.

MYOB AccountRight adaptor system dialog

The adaptor imports and exports data by sending HTTP requests that contain JSON (JavaScript Object Notation) documents to the MYOB Add-on Connector service. Unlike SQL based relational databases, JSON documents support storing data in hierarchical structures (as opposed to table structures). To be able to obtain data in JSON documents functions have been built into the adaptor that allow traversing a JSON document to obtain different field data for each exported record.

Adaptor Setup

To create a new MYOB AccountRight adaptor follow these steps:

  1. Open the Connector application by clicking on its icon in the desktop or within the Windows start menu.
  2. Within the application, under the Adaptors and Messages tab in the Adaptors panel, in the drop down select the option MYOB AccountRight version 2013-2016.
  3. In the Key field give the adaptor a unique value that no other adaptors have set.
  4. Click the Add button to create the adaptor. A row will be added to the adaptors in the table below the button.

Once the adaptor has been created:

  • click on the Adaptor button against the new adaptor row to configure how the adaptor connects with the TOTECS Ecommerce platform and/or Squizz.com platform.
  • Click the Exports/Routines button, to schedule when data exports and routines are run for the adaptor.
  • Click the Settings button to configure how the adaptor talks to the MYOB AccountRight system and obtains data.

MYOB AccountRight Setup

To allow the adaptor to talk to a MYOB AccountRight installation, the following needs to be setup within the AccountRight installation:

  • Install the MYOB Add-on Connector.
    • This should come bundled with the AccountRight installation, and may only require starting to get working.
    • Configure a port that the Connector should run on and configure any Windows Firewalls to allow other software to connect to the port.
  • Within AccountRight do the following
    • create items for each of the surcharges that can be expected to be imported within sales orders. Eg. WEB_FREIGHT, WEB_CC_SURCHARGE, WEB_MIN_ORDER
    • (Optional) Create customer cards for accounts that cover the general public ordering, such as WEB_RETAIL, and WEB_TRADE
    • Designate a custom item field that will be used to denote that an item can be exported.
    • Designate a custom item field that will be used to assign a category path to a product.

General Settings Configuration

Below are all the settings within the adaptor's General Settings window that enable connectivity between the adaptor and the MYOB AccountRight API connector service.

Setting Description
AccountRight Data Source Settings
AccountRight API URL Address The URL of the address that allows HTTP access to the MYOB Add-on Connector webservice, or at the location where the AccountRight company file is hosted within the MYOB Cloud platform. By default for self hosted installations this would be http://localhost:8080/AccountRight on the machine where MYOB AccountRight was installed. Otherwise for cloud hosted files, use the "MYOB Cloud Access Utility" within the adaptor's settings form to find out the URL of where the company file is hosted.
Company File GUID The unique identifier of the company file in the MYOB AccountRight installation. This can be found by calling the webservice's URL that is set in the "AccountRight API URL Address" setting.
AccountRight User Name Name of the user within the AccountRight installation that the adaptor logs in with, It's recommended that this user is specifically created only for the adaptor.
AccountRight User Password Password of the user within the AccountRight installation that the adaptor logs in with,
MYOB Developer Key The unique developer key that is issued by MYOB to allow the use of the MYOB Add-on Connector webservice. This key can only be obtained from organisations who are a part of MYOB's developer program. For TOTECS customers contact TOTECS to obtain this key, otherwise contact your MYOB consultant, or MYOB itself to obtain this key.
AccountRight Environment Determines how the adaptor should try to read/write data based on where the AccountRight company file is hosted.
MYOB Cloud Authentication URL Set it to the URL that is used to authenticate and access the MYOB AccountRight Cloud using its Oauth protocol. Set URL based on documentation at http://developer.myob.com/api/accountright/api-overview/authentication/
MYOB Developer Redirect URL Set it to the same URL that is was set up with the Developer/API credentials within MYOB's cloud. This URL is required to generate the Access Token needed to access the Company File hosted on MYOB's cloud.
MYOB Developer Password Password associated within the developer/API credentials set within MYOB's cloud. This password is used to obtain access to the cloud.
MYOB Cloud Refresh Token Token issued from MYOB's cloud and is repeatedly used to obtain access to MYOB's cloud and generate the required Oauth access token, used to obtain data from the associated hosted company file. This Refresh Token is a long lived token.
Sales Order Import Settings
Order Category Unique identifier that is associated to a order category, which is assigned to each sales order when imported. Set a GUID identifier found from within the Add-on API, or else leave empty.
Order Delivery Status Set the default delivery status against a sales order when its imported into AccountRight.
Use Order Product Description in Orders Tick if the product descriptions in sales orders are imbedded into the imported MYOB AccountRight sales orders, or otherwise let AccountRight set the product descriptions itself.
Order Comment Prefix Text Set text that is placed at the beginning of the comment that is embedded within imported MYOB AccountRight sales order.
Show Sales Rep. In Comment Tick if the sales order comments should also show the sales rep who is assigned to the order.
Sales Rep. Comment Prefix Text Set text that is placed at the beginning of the sales rep comment that is embedded within imported MYOB AccountRight sales order.
Show User Name In Comment Tick if the sales order comments should also show the user name of the Ecommerce user who was assigned to the imported order.
User Name Comment Prefix Text Set text that is placed at the beginning of the user name comment that is embedded within imported MYOB AccountRight sales order.
Import Sales Order As Set if a sales order is imported into MYOB AccountRight as a sales order, or as an invoice.
Sales Order Freight Surcharge Code Set a code of the surcharge in the order that denotes that the surcharge is freight related. When a sales order is imported into MYOB AccountRight, surcharges matching this code will be used to calculate freight applied against the order and will be shown as its own calculation. All other surcharges will be imported as item lines.
Sales Order Import Payment Settings
Order Payment Deposit GL Account Set a unique identifier of the general ledger account that sales order payments, and customer account payments will be applied against. This value should be a GUID identifier that can be found by making a request to the AccountRight API's generalledger/account/ endpoint to find the ID of the applicable account.
Import Order Pricing Tax Inclusive If tick then when sales orders are imported into AccountRight all pricing is imported as tax inclusive, as opposed to tax exclusive. This setting may alter how MYOB prices the order.
Set Payment Terms For Each Order If ticked then when sales orders are imported into AccountRight the same payment terms as set against the order, based on the settings below. If not ticked (recommended) then AccountRight will apply the payment terms based on the terms set against the customer assigned to the sales order.
Payment Is Due Sets the payment terms of when an imported sales order must be paid by. Only used if the "Set Payment Terms For Each Order" setting is ticked.
Discount Days Sets for how many days a discount can apply against an imported sales order if paid within the given days. Only used if the "Set Payment Terms For Each Order" setting is ticked.
Balance Due Days/Date Sets either the date of the month, or the number of days that an imported sales orders must be paid within, based on the chosen Payment Terms. Only used if the "Set Payment Terms For Each Order" setting is ticked.
% Discount For Early Payment Sets the percentage amount that is discounted off an imported sales order total if its paid within the specified discount days period. Only used if the "Set Payment Terms For Each Order" setting is ticked.
% Monthly Change For Late Payment Sets the percentage amount that is added to an imported sales order total if it has not been paid within the payment terms period. Only used if the "Set Payment Terms For Each Order" setting is ticked.
Purchase Order Import Settings
Order Category Unique identifier that is associated to a order category, which is assigned to each purchase order when imported. Set a GUID identifier found from within the Add-on API, or else leave empty.
Order Delivery Status Set the default delivery status against a purchase order when its imported into AccountRight.
Use Order Product Description in Orders Tick if the product descriptions in purchase orders are imbedded into the imported MYOB AccountRight purchase orders, or otherwise let AccountRight set the product descriptions itself.
Order Comment Prefix Text Set text that is placed at the beginning of the comment that is embedded within imported MYOB AccountRight purchase order.
Show Purchaser In Comment Tick if the purchase order comments should also show the purchaser who is assigned to the order.
Purchaser Comment Prefix Text Set text that is placed at the beginning of the purchaser comment that is embedded within imported MYOB AccountRight purchase order.
Show User Name In Comment Tick if the purchase order comments should also show the user name of the Ecommerce user who was assigned to the imported order.
User Name Comment Prefix Text Set text that is placed at the beginning of the user name comment that is embedded within imported MYOB AccountRight purchase order.
Import Purchase Order As Set if a purchase order is imported into MYOB AccountRight as a purchase order, or as a bill.
Purchase Order Freight Surcharge Code Set a code of the surcharge in the order that denotes that the surcharge is freight related. When a purchase order is imported into MYOB AccountRight, surcharges matching this code will be used to calculate freight applied against the order and will be shown as its own calculation. All other surcharges will be imported as item lines.
Import Order Pricing Tax Inclusive If tick then when purchase orders are imported into AccountRight all pricing is imported as tax inclusive, as opposed to tax exclusive. This setting may alter how MYOB prices the order.

Adaptor Data Exports

Below are all the settings within the adaptor's General Settings window that enable connectivity between the adaptor and the MYOB AccountRight API connector service.

Data Export Description
Category Products Obtains a list of products that each are assigned to a pipe delimited list of category names. Each of the unique category names are added to a list containing ESDRecordCategory records. Additionally a list of products is assigned to each relevent category record, and placed into a ESDocumentCategory document which exported out in its final state to the Ecommerce system.
Customer Account Addresses Obtain a list of addresses that are assigned to customer accounts (Customer Card). The data is placed within an ESDRecordCustomerAccountAddress record when exported. The record data is all placed into an ESDocumentCustomerAccountAddress document which is exported in its final state to the Ecommerce System.
Customer Account Enquiry Credit Lines Obtains a list of lines within a credit record that is associated to a given customer account (Customer Card). The line data is placed within ESDRecordCustomerAccountEnquiryCreditLine records, which is placed within a single ESDRecordCustomerAccountEnquiryCredit record that has been retreived from the Customer Account Enquiry Credits data export. The credit record is then placed within a ESDocumentCustomerAccountEnquiry document which exported out in its final state to the Ecommerce system.
Customer Account Enquiry Credits Obtains a list of credit records associated to a given customer account (Customer Card). Each credit record is placed within a ESDRecordCustomerAccountEnquiryCredit record, which is then placed within ESDocumentCustomerAccountEnquiry document which exported out in its final state to the Ecommerce system. The data export is used to retreive an individual credit record, as well as search for a multiple credit records based on a number given number of search filters.
Customer Account Enquiry Invoice Lines Obtains a list of lines within a invoice record that is associated to a given customer account (Customer Card). The line data is placed within ESDRecordCustomerAccountEnquiryInvoiceLine records, which is placed within a single ESDRecordCustomerAccountEnquiryInvoice record that has been retreived from the Customer Account Enquiry Invoices data export. The invoice record is then placed within a ESDocumentCustomerAccountEnquiry document which exported out in its final state to the Ecommerce system.
Customer Account Enquiry Invoices Obtains a list of invoice records associated to a given customer account (Customer Card). Each invoice record is placed within a ESDRecordCustomerAccountEnquiryInvoice record, which is then placed within ESDocumentCustomerAccountEnquiry document which exported out in its final state to the Ecommerce system. The data export is used to retreive an individual invoice record, as well as search for a multiple invoice records based on a number given number of search filters.
Customer Account Enquiry Payment Lines Obtains a list of lines within a payment record that is associated to a given customer account (Customer Card). The line data is placed within ESDRecordCustomerAccountEnquiryPaymentLine records, which is placed within a single ESDRecordCustomerAccountPayment record that has been retreived from the Customer Account Enquiry Payments data export. The invoice record is then placed within a ESDocumentCustomerAccountEnquiry document which exported out in its final state to the Ecommerce system.
Customer Account Enquiry Payments Obtains a list of payment records associated to a given customer account (Customer Card). Each payment record is placed within a ESDRecordCustomerAccountEnquiryPayment record, which is then placed within ESDocumentCustomerAccountEnquiry document which exported out in its final state to the Ecommerce system. The data export is used to retreive an individual payment record, as well as search for a multiple payment records based on a number given number of search filters.
Customer Account Enquiry Sales Orders Obtains a list of sales order records associated to a given customer account (Customer Card). Each sales order record is placed within a ESDRecordCustomerAccountEnquiryOrderSale record, which is then placed within ESDocumentCustomerAccountEnquiry document which exported out in its final state to the Ecommerce system. The data export is used to retreive an individual sales order record, as well as search for a multiple sales order records based on a number given number of search filters.
Customer Account Enquiry Sales Order Lines

Obtains a list of lines within a sales order record that is associated to a given customer account (Customer Card). The line data is placed within ESDRecordCustomerAccountEnquiryOrderSaleLine records, which is placed within a single ESDRecordCustomerAccountEnquirryOrderSale record that has been retreived from the Customer Account Enquiry Sales Orders data export. The sales order record is then placed within a ESDocumentCustomerAccountEnquiry document which exported out in its final state to the Ecommerce system.

Customer Account Status Obtains the status of a single specific customer account. The data is placed within an ESDRecordCustomerAccount record when exported. The record data is placed into an ESDocumentCustomerAccount document which is exported out in its final state to the Ecommerce system.
Customer Accounts Obtains a list of customer accounts (Customer Cards). The data is placed within ESDRecordCustomerAccount records when exported.The record data is all placed into an ESDocumentCustomerAccount document which is exported out in its final state to the Ecommerce system.
Product Price Level Pricing Obtains a list of prices that is associated to the unit price-level prices associated with products (Items). The data is placed within ESDRecordPrice records when exported. The record data is all placed into an ESDocumentPrice document which is exported out in its final state to the Ecommerce system.
Product Price Level Quantity Pricing Obtains a list of prices that is associated to the quantity break based price-level prices associated with products (Items). The data is placed within ESDRecordPrice records when exported. The record data is all placed into an ESDocumentPrice document which is exported out in its final state to the Ecommerce system.
Product Stock Quantities Obtains a list of available stock quantities associated with products(Items). The data is placed within ESDRecordStockQuantity records when exported. The record data is all placed into an ESDocumentStockQuantity document which is exported out in its final state to the Ecommerce system.
Products Obtains a list of products(Items). The data is placed within ESDRecordProduct records when exported. The record data is all placed into an ESDocumentProduct document which is exported out in its final state to the Ecommerce system.
Sales Reps Obtains a list of sales representatives(Employees). The data is placed within ESDRecordSalesRep records when exported. The record data is all placed into an ESDocumentSalesRep document which is exported out in its final state to the Ecommerce system.
Supplier Account Addresses Obtain a list of addresses that are assigned to supplier accounts (Supplier Card). The data is placed within an ESDRecordSupplierAccountAddress record when exported. The record data is all placed into an ESDocumentSupplierAccountAddress document which is exported in its final state to the Ecommerce System.
Supplier Account Enquiry Purchase Order Lines Obtains a list of lines within a purchase order record that is associated to a given supplier account (Supplier Card). The line data is placed within ESDRecordSupplierAccountEnquiryOrderPurchaseLine records, which is placed within a single ESDRecordSupplierAccountEnquiryOrderPurchase record that has been retreived from the Supplier Account Enquiry Purchase Orders data export. The purchase order record is then placed within a ESDocumentSupplierAccountEnquiry document which exported out in its final state to the Ecommerce system.
Supplier Account Enquiry Purchase Orders Obtains a list of purchase order records associated to a given supplier account (Supplier Card). Each purchase order record is placed within a ESDRecordSupplierAccountEnquiryOrderPurchase record, which is then placed within ESDocumentSupplierAccountEnquiry document which exported out in its final state to the Ecommerce system. The data export is used to retreive an individual purchase order record, as well as search for a multiple purchase order records based on a number given number of search filters.
Supplier Accounts Obtains a list of supplier accounts (Supplier Cards). The data is placed within ESDRecordSupplierAccount records when exported.The record data is all placed into an ESDocumentSupplierAccount document which is exported out in its final state to the Ecommerce system.
Taxcodes Obtains a list of taxcodes. The data is placed within ESDRecordTaxcode records when exported. The record data is all placed into an ESDocumentTaxcode document which is exported out in its final state to the Ecommerce system.

Data Export URL Hooks

For a number of data exports within the adaptor there is the ability to embed hooks within the Data Export URL field. When done each hook will get replaced with URL parameters and values based on the type of request being made to obtain records. The hooks are used to filter the records that are returned from the MYOB Add-on Connector webservice endpoints, and further customise the record data retrieved.

Customer Account Enquiry Records Data Export URL Hooks

Within each of the customer account enquiry records data exports the following list of the hooks can be placed into the request URL.

Data Hook Description
{KeyCustomerAccountID} unique ID of the customer account to find records that are assigned to it.
{recordType} Type of record being requested. Can be either INVOICE, BACKORDER, ORDER_SALE, CREDIT, PAYMENT
{pageNumber} Number of the page to get records within. If set to 0 or less then return records from page 1, otherwise return records from an offset amount.
{numberOfRecords} Sets the number of records that have been requested to obtain. If set to 0 then return all records, otherwise return the given amount.
{orderByClause} Sets the the name of the field used to order the records by.
{limitClause} Controls both the page number, and number of records to return.
{whereClause} Sets the conditions used to filter and match records on. This includes date filtering, record ID filtering, search filtering.
{recordsPerPage} Contains the number of records that the export will allow to be returned.
{pageOffset} Sets the number of records from the top of the record list to start obtaining records from.

Customer Account Enquiry Record Data Export URL Hooks

Within each of the customer account enquiry record data exports the following list of the hooks can be placed into the request URL to obtain a single record.

Data Hook Description
{KeyCustomerAccountID} unique ID of the customer account to find records that are assigned to it.
{recordType} Type of record being requested. Can be either INVOICE, BACKORDER, ORDER_SALE, CREDIT, PAYMENT
{keyRecordID} ID of the record to obtain.

Supplier Account Enquiry Purchase Orders Data Export URL Hooks

For the Supplier Account Enquiry Purchase Orders data exports the following list of the hooks can be placed into the request URL.

Data Hook Description
{KeySupplierAccountID} unique ID of the supplier account (Supplier Card ID) to find records that are assigned to it.
{recordType} Type of record being requested. Can be either ORDER_PURCHASE
{pageNumber} Number of the page to get records within. If set to 0 or less then return records from page 1, otherwise return records from an offset amount.
{numberOfRecords} Sets the number of records that have been requested to obtain. If set to 0 then return all records, otherwise return the given amount.
{orderByClause} Sets the the name of the field used to order the records by.
{limitClause} Controls both the page number, and number of records to return.
{whereClause} Sets the conditions used to filter and match records on. This includes date filtering, record ID filtering, search filtering.
{recordsPerPage} Contains the number of records that the export will allow to be returned.
{pageOffset} Sets the number of records from the top of the record list to start obtaining records from.

Supplier Account Enquiry Purchase Order Lines Data Export URL Hooks

Within the Supplier Account Enquiry Purchase Order Lines data export the following list of the hooks can be placed into the request URL to obtain a single record.

Data Hook Description
{KeySupplierAccountID} unique ID of the supplier account (Supplier Card ID) to find records that are assigned to it.
{recordType} Type of record being requested. Can be either ORDER_PURCHASE
{keyRecordID} ID of the record to obtain.

Product Stock Quantities Data Export URL Hooks

For the Product Stock Quantities data export the following list of the hooks can be placed into the request URL to obtain either a single stock quantity record for a given product, or for all products.

Data Hook Description
{whereClause} Contains parameters that allow either a single matched product record to be obtained, or else any product record.
{recordsPerPage} Sets the maximum number of records that can be obtained in a single request.
{pageOffset} Sets the start position within the records list to start obtaining record data from.

Customer Account Status Data Export URL Hooks

For the Customer Account Status data export the following list of the hooks can be placed into the request URL to obtain a single customer account record.

Data Hook Description
{keyCustomerAccountID} Unique ID of the customer account (Customer Card ID).

Data Export JSON Record Traversal

For each of the data exports within the adaptor there is the ability to further filter the records after they have been retreived from MYOB Add-on Connector webservice. After the request is made to obtain data from the webservice, it will return a JSON document containing all the records embedded in a hierarchical JSON data structure. For each data export there is the "JSON Record Set Path" setting which allows JSON notation to be set. This JSON notation tells the adaptor how to traverse through the JSON document to find the array of records that need to be iterated through.

For example in the Customer Account Addresses data export when it retrieves data from the AccountRight API's /Contact/Customer endpoint, the data export's JSON Record Set path is configured to "Items[*].Addresses[*]". This means that the export will traverse through the "Items" top level JSON object and iterate through all of the records in its array, then for each of those records if it contains an "Addresses" object, then it will iterate through the array of records in the Addresses object. The end result is that the data export will iterate through all the address records across all customer accounts in the JSON data returned from the webservice. The JSON notation additionally provides context to the data fields configured in the data export. In this case data fields can be directly set for each of the properties within the address records.

The JSON notation in each data export needs to the conform to the JsonPath syntax, more information about it can be found here and here

Using JSONPath allows for highly customized traversal of JSON data structures and well as the ability to further filter on records after the JSON has been retreived from a webservice.

Data Export Field JSON Functions

The MYOB AccountRight adaptor obtains its data from the AccountRight API webservice which returns data in the JSON data structure. Built in to the adaptor are the following functions that allow you manipulate the JSON data mapped to each field before it is exported out of the Connector. The functions accept nesting other functions inside their arguments, however try to avoid too much nesting since each function incurs a processing cost which could add up to longer waiting times for a data export to complete.

CONCAT(arg1arg2arg..n)

Description: Allows one or more fields in the same record to be joined to another field or literal text, and outputs the joined text.
Arguments The function can take 1 or more arguments with each argument either the name of a JSON field in the record, or literal text enclosed with either single quote or double quote characters.
Output: STRING
Examples

CONCAT(Taxcode,'1234')
Taxcode = 'GST'
outputs: GST1234

CONCAT('ABC',REPLACE('DEF','E','1'),'GHI')
outputs: ABCD1FGHI

REPLACE(input_argmatching_argreplace_arg)

Description: Replaces any matching text within a string value with another string, then outputs the final text
Arguments

The function takes 3 arguments:
input_arg: the field name or literal text to read in
matching_arg: the text to match on
replace_arg: the text to replace the matched text with.

Output: STRING
Examples

REPLACE(Taxcode,'GST','Other Value')
Taxcode = 'GST'
outputs: 'Other Value'

REPLACE('GST',TaxCode,'NOTAX')
Taxcode = 'GST'

outputs: NOTAX

REPLACE('GST',CONCAT('G','S','T'),CONCAT(Taxcode,'-123'))
Taxcode = 'Tax Free'
outputs = 'Tax Free-133'

CALC(arg1arg2arg..n)

Description: Calculates out a numeric value after evaluating out all arguments into a string representation of a mathematical equation. 
Arguments

The function can take 1 or more arguments with each argument either the name of a JSON field in the record, or literal text enclosed with either single quote or double quote characters. The output of each argument is joined together to make one final mathematical equation which is evaluated out. The mathematical operators supported are + - / % ( )

Output: NUMBER
Examples

CALC('((10 + 4 - 2) / 2) * 6')
outputs: 36

CALC(TaxRate,' + 33')
TaxRate = 10
outputs: 43

CALC(CONCAT('10','00'),'/',Amount)
Amount = 50000
outputs = 0.02

IF(compare_arg1, operatorcomprare_arg2, then_arg, else_arg)

Description: Checks if one value matches another value, then if so outputs one value, otherwise it outputs the other value.
Arguments

The function takes 5 arguments:
compare_arg1: The first field name or literal text to read in and compare against the second
compare_arg2: The second field name or literal text to read in and compare against the first
then_arg: Name of the JSON field in the record or literal text to be outputted when the comparing arguments match
else_arg: Name of the JSON field in the record or literal text to be outputted when the comparing arguments fail to match
operator: Operator used to compare the two arguments. must be set to one of the following

  • ==S
    Checks if both values match each other, character for character in each value's string
  • ==N
    Checks if both values match each other numerically. Each value must evaluate out to a number first.
  • !=S
    Checks if both values do not match each other, character for character in each value's string
  • !=N
    Checks if both values do not match each other numerically after each value has been converted to a number.
  • >
    Checks if the first value is greater than the second value after both values have been converted to numbers.
  • >=
    Checks if the first value is greater than or equal to the second value after both values have been converted to numbers.
  • <
    Checks if the first value is less than the second value after both values have been converted to numbers.
  • <=
    Checks if the first value is less than or equal to the second value after both values have been converted to numbers.
  • .*
    Checks if the first value starts with the text given in the second value.
  • *.
    Checks if the first value ends with the text given in the second value.
  • *.*
    Checks if the first value contains the text given in the second value.
  • REGEX
    Checks if the first value matches a regular expression set within the second value.
Output: STRING
Examples

IF('1','==S','1','Y','N')
outputs: 'Y'

IF('1','==S','1.0','Y','N')
outputs: 'N'

IF('1','==N','1.0','Y','N')
outputs: 'Y'

IF(CONCAT(Taxcode,'123'),'.*','GS','Y','N')
Taxcode = GST

outputs: 'Y'

IF(CONCAT('11',TaxRate),'>=','110',REPLACE('Y','Y','YY'),'N')
TaxRate = 0

outputs: 'YY'

IF(Description,'REGEX','(tax)','Y','N')
Description = 'goods and services tax applies'
outputs = 'Y'

DATESTR_CONVERT(input_argdate_formatoutput_type)

Description: Converts a date time string into different date format.
Arguments

The function takes the following 3 arguments:
input_arg: the field name or literal text to read in
date_format: the field name or literal text that contains text on how the input text has its date format parsed. This date format should conform to the Dot.NET language's date format conventions.
output_type: Set to 'LONG'. Denotes that the datetime will be converted to a long integer number that represents the amount milliseconds past since the 1970-01-01 12am UTC date time epoch.

 

Output: NUMBER
Examples

DATESTR_CONVERT('14/07/2016 21:14:48','dd/MM/yyyy HH:mm:ss','LONG')
outputs: 1468530888000

PARENT_NODE(input_arg, parent_count)

Description: Obtains the value at any parent node of a JSON record. This allows for traversal up a JSON tree.to find a value.
Arguments

The function takes the following 2 arguments:
input_arg: the field name or literal text to read in that contains the name of the JSON property to read from the parent node.
parent_count: Set literal text containing a number to denote how many levels of parents to traverse up to obtain the value with the given name.


 

Output: STRING
Examples

Below is an example of JSON data obtained in entirety from a data source for a given data export.

{
    "customers"
    [
        {
            "keyCustomerAccountID":"4324324",
            "accountName":"Acme Industries",
            "addresses":
        
    [
       
        {
                    "description":"Primary Address",
                    "address1":"123 High Street",
                
    "address2":"Melbourne",
                    "region":"Victoria"
                }
            ]
        }

    ],
    "country":"Australia"

}

If a data export is configured to get all address records from within any customer accounts. then a rule such as customers.[*].addresses[*] would return an array of address records.

If for each address record you wanted to get associated customer data then you would use the PARENT_NODE function like so:

PARENT_NODE('keyCustomerAccountID','3')

For the first address record this would output the value: 'Acme Industries'.
The number 3 denotes that from the address record it took 3 steps up the JSON hierarchy to get to the customer record.
Step 1: The array of address records
Step 2: The array of address records including its "addresses" key
Step 3: The customer account record

If for a field in the address record you wanted to get the country at the top most level of the JSON structure, then you would use the following function:

PARENT_NODE('country','6')

This would output the value 'Australia' when being used within an address record field. The number 6 denotes that it took 6 steps to go from the address record up the JSON hierarchy to get the top JSON object containing the country property.
Step 1: The array of address records
Step 2: The array of address records including its "addresses" key
Step 3: The customer record
Step 4: The array of customer records
Step 5: The array of customer records including the "customers" key
Step 6: The top level JSON object

PARENT_NODE_NAME(parent_count)

Description: Obtains the key name of a parent node from a JSON record. This allows for traversal up a JSON tree.to find a key name associated to a parent.
Arguments

The function takes the 1 argument:
parent_count: Set literal text containing a number to denote how many levels of parents to traverse up to obtain the key name of the parent node.


 

Output: STRING
Examples

Below is an example of JSON data obtained in entirety from a data source for a given data export.

{
    "customers"
    [
        {
            "keyCustomerAccountID":"4324324",
            "accountName":"Acme Industries",
            "addresses":
        
    [
       
        {
                    "description":"Primary Address",
                    "address1":"123 High Street",
                
    "address2":"Melbourne",
                    "region":"Victoria"
                }
            ]
        }

    ],
    "country":"Australia"

}

If a data export is configured to get all address records from within any customer accounts. then a rule such as customers.[*].addresses[*] would return an array of address records.

If for each address record you wanted to get the name of parent key that holds the array of customer records you would use the PARENT_NODE_NAME function like so:

PARENT_NODE_NAME('4')

For each of the address records this would output the value: 'customers'.
The number 4 denotes that from the address record it took 4 steps up the JSON hierarchy to get to the object storing the customers array, from which it then obtains its parent node name.
Step 1: The array of address records
Step 2: The array of address records including its "addresses" key
Step 3: The customer account record
Step 4: The customer account records

 

Adaptor Routines

The adaptor contains no routine types.