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 |
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:
- Connector Adaptors.
- Connector Routines.
- MYOB AccountRight software
- https://www.myob.com/au/accounting-software/accountright
- MYOB AccountRight Addon Connector http://help.myob.com/wiki/display/ar/Add-ons#expand-HowdoIinstallorreinstalltheMYOBAddOnConnector
- MYOB AccountRight synchronisation between data in the cloud and offline http://help.myob.com/wiki/display/ar/Automatic+synchronisation#expand-Toenableautomaticsynchronisation
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.
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.
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:
- Open the Connector application by clicking on its icon in the desktop or within the Windows start menu.
- 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.
- In the Key field give the adaptor a unique value that no other adaptors have set.
- 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.
- Create a non-inventoried item with the product code: c that is used by the adaptor to add text lines to orders and invoices.
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. |
| Payment Deposit GL Account Type |
Set type of general ledger account that sales order and customer account payments will be applied against. Can be set to the options:
|
| 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 a 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 a 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 a 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 a 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 a 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 into the adaptor are the JSON/XML/CSV field 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.
To find out all the details on the JSON/XML/CSV field functions, go to the JSON/XML/CSV field functions page.
Adaptor Routines
The adaptor contains no routine types.
Adaptor Issues
Below are are list of issues that you may encounter whilst to setup or use the adaptor.
| Issue: Adapter Showing error: Unable to Connect to MYOB AccountRight Premier/Enterprise datasource or close its connections. | |
Summary: When attempting to run a data export, the following two errors appear in the log:
This issue may be caused by having a network path to the MYOB datafile in the ODBC Data Source given by the DSN (ODBC Data Source Name) and the Connector service does not have user priviledges to this path. For instance, if your path is \serverMYOB, then you need to ensure that the service is logged in with a user account that has permission to access this network path or the ODBC System DSN cannot access the MYOB data file. Mitigation Steps:
If you are still having trouble, search the forum or post an issue to the Service Centre. | |
| Issue: Adaptor showing error : Unable to open the lock file: access privileges may be incorrect or disk may be full | |
Summary: When attempting to run a data export, the following error appear in the log:
A common cause for this message is the presence of 'lock files' in the location where the company file is stored for MYOB AccountRight Premier/Enterprise. These files are created to manage multi-user access to Premier/Enterprise. Ordinarily these files are automatically deleted when the user closes or logs out of the accounting system, but an abrupt termination of a session can result in one or more of these files remaining in the system, or sometimes for no apparent reason at all. To rectify this, the lock files must be deleted. The Connector contains a tool to allow you to remove the lock files. Please follow the mitigation steps to remove the lock files from the MYOB AccountRight Premier/Enterprise directory. Mitigation Steps
| |
| Issue: Adaptor showing error : An initialisation error with the MYOB application has occurred | |
Summary: When attempting to run a data export, the following error appear in the log:
This issue can occur if the same MYOB user configured in the ODBC Data Source Name (DSN) has the MYOB AccountRight Premier application open, and when the Connector tries to use the DSN this error occurs. To rectify this the MYOB AccountRight Premier application needs to be closed for the logged in user who is set in the DSN. Mitigation Steps
| |
| Issue: Adaptor showing error : Cannot launch MYOB | |
Summary: When attempting to test the MYOB AccountRight Premier/Enterprise read/write connect within the adaptor settings window the following error appears in the dialog.
This issue could occur on some Windows server machines that have User Access Control (UAC) enabled. It appears that the issue could be because UAC is blocking the Connector application from being able to run MYOB's driver (and associated executable). There only solution is to run the Connector application as an administrator user. Mitigation Steps
The connection should hopefully now be sucecssfully made to the MYOB. | |
| Issue: Connector Host Service crashes when an attempt is made to obtain supplier account enquiry purchase order record data from MYOB AccountRight Premier | |
Summary: When a request comes into the Connector to obtain supplier account purchase order data from the MYOB AccountRight Premier adaptor, the ODBC connection made by the adaptor causes the Connector Host Service crash.
C:Premier19MYOBp.exe.manifest <requestedExecutionLevel level="asInvoker"
|