The Essentials API Announcement: Get prepared for new Essentials upgrade

We are currently undertaking a major upgrade of MYOB Essentials. The new Essentials will be powered by the AccountRight platform along with using the AccountRight API to integrate with apps such as yours. If you use the AccountRight API there will be no change – this will continue to work as it does today. If you use the Essentials API there is a change required for your current customers. From May 2020 we will progressively start to upgrade existing Essentials customers to the new Essentials. Once an old Essentials file has been upgraded users will no longer be able to use the old Essentials API and over time support for the Essentials API will cease.

This article provides you with information on:
 - The public Essentials API update to indicate the statuses during an end-user file upgrade.
 - Old to new Essentials upgrade flow.
 - An end-user experience during and post a file upgrade.

This upgrade will not only affect the end-users but also your application requires an update to inform and navigate users to switch the API connection from old to new Essentials(i.e. the AccountRIght API). An old Essentials file that is in the process of being upgraded or has been upgraded will contain specific codes that will tell you that the file is currently being upgraded or has been upgraded. You will be unable to use the old Essentials API if you receive either of these codes and will have to use the ARL API for this end-user.

UPGRADING

Any upgrade is planned to be commenced during overnight hours. During this file migration, file access will be blocked via the UI and the Essentials API. This will consequence in any GET/PUT/POST/DELETE request to /businesses/{business_uid} and /businesses/{business_uid}/* endpoints via the Essentials API result in 423 response code with a below payload format.

{
 'globalId' : '8fcxxxx1-b35d-xxxx-9256-7cexxxxx078', 
   //An unique new Essentials File identification i.e. cf_guid
 'businessId' : '1234xx', 
   //An unique old Essentials File identification i.e. BID 
 'status' : 'UPGRADING', 
}

If an end-user should encount this response code, we recommend your application to inform the user  below:
 - Selected Essentials file is currently being upgraded.
 - The file is locked and unable to use during the upgrade.
 
If anything should go wrong during the upgrade, the file gets unlocked. This means the file can be accessed via old Essentials and the API connections can be re-established via the Essentials API with retained refresh tokens. Upgrade of this file will be rescheduled in due course.

UPGRADED

When the file upgrade completes, the end-user will be directed to access new Essentials. Yet since your application should still be connected with the old Essentials file, any calls to the Essentials API post-upgrade completion are remain blocked but with a 418 response code. This will consequence in any GET/PUT/POST/DELETE request to  /businesses/{business_uid} and /businesses/{business_uid}/* endpoints via the Essentials API in a below payload format.

Note: All records will be reissued a new UID upon a new Essentials file upgrade completion.

{
 'globalId' : '8fcxxxx1-b35d-xxxx-9256-7cexxxxx078', 
 //An unique new Essentials File identification i.e. cf_guid
 'businessId' : '1234xx', 
 //An unique old Essentials File identification i.e. BID
 'status' : 'UPGRADED'
}

Scenario 1: Scope = CompanyFile la.global

If your application already obtains access and refresh tokens that cover both the AccountRight and the Essentials APIs (i.e. Scope = CompanyFile la.global), re-authentication is not required. This is a recommended approach to avoid doubled authentication for end-users who are new to establish connections with new Essentials files.

Since the stored tokens are ready to be integrated with the AccountRight API, navigate the end-user to the AccountRight file list or directly the file based on 'globalId' via the AccountRight API.

Scenario 2: Scope = la.global

If your application obtains tokens for the Essentials API (i.e. Scope = la.global) only, we would recommend you to consider updating your authentication process to obtain tokens to cover both the AccountRight and the Essentials APIs (i.e. Scope = CompanyFile la.global). Yet, as a workaround, redirect the end-user to the AccountRight API authentication:

https://secure.myob.com/oauth2/account/authorize?client_id={{api_key}}&redirect_uri={{redirect_url}}&response_type=code&scope=CompanyFile 

Allow the end-user to complete the AccountRight API authentication, and navigate the end-user to the AccountRIght file list or directly the file based on 'globalId' via the AccountRight API.
 

Note: Authentication is expected to happen per device basis.

Important: This new Essentials upgrade process will consequence in creation of a new file. If your application asks to select an MYOB product suite before establishing a connection, consider updating the Essentials product suite option to have another validation layer to catch UPGRADING(423) and UPGRADED(418) response codes in order to perform smooth switchover between the Essentials API and the AccountRight API.

If anything should go wrong, during establishing the connection to the new Essentials fie(i.e the AccountRight API), consider advising the end-user to revoke access to your application. Once the access is revoked, the end-user can re-authenticate via your application to obtain the tokens. For revoking access details, visit here.