MYOB Exo Business Serviceshelp.myob.com.au/exo/onthego/releasenotes/15/MYOB EXO...using the MYOB Exo...

MYOB Exo Business Services Release Notes 1.5

Contents Introduction 1

........................................................................... 1

Installation 2

Pre-Install Requirements ................................................................................. 2

Installing the Exo Business Services ............................................................ 2

Setting up the Services 6

Setting up Exo Business Services ................................................................. 6

Setting up Exo Business ................................................................................... 8

Adding the Exo API and Exo OnTheGo Modules ................................................. 8

Updating the Exo Business Database ........................................................................ 8

Generating User Tokens ................................................................................................. 8

Adding Exo OnTheGo Access and Devices ............................................................. 9

Bulk Loading Locations ................................................................................................... 11

Testing the API Service ................................................................................... 12

Troubleshooting ................................................................................................ 12

New Features 13

New Stock Adjustment Endpoints .............................................................. 13

Transaction Lines .............................................................................................................. 14

New Stock Transaction Endpoint ............................................................... 14

Transaction Lines .............................................................................................................. 15

General Ledger Endpoint ............................................................................... 16

Period Status Endpoint ................................................................................................... 16

General Ledger Endpoint .............................................................................................. 17

Chart of Accounts Endpoint ......................................................................................... 18

Display Names in Report Parameter Labels ........................................... 18

Known Issues 19

Exo Business Services 1.5 Release Notes Page 1 of 19 Copyright 2018 MYOB Technology Pty Ltd.

Introduction

The 1.5 release T of the Exo Business Services coincides with the release of Exo Business 2018.4 and supports more advanced encryption of passwords. API 1.5 and associated Services are required for businesses using 2018.4 and above; however, it is also backward compatible to versions 2017.2 and above. It also includes enhancements to the licence expiry and token management and support for some more recent Exo Business features in Extra Fields and Clarity report parameters.

The purpose of this document is to provide essential information on the installation and use of this release:

• The Installation section provides an overview of the installation process, including pre-installation requirements.

• The Setting up Exo API section provides information on configuring the Exo API after installation.

• The New Features section describes all new features introduced in this release.

• The Resolved Issues section describes all issues that have been addressed by this release.

For information on how to use the Exo API, including documentation on all API endpoints, see the Exo API Online Help at http://apidocs.myob.com/api/exo/.

http://apidocs.myob.com/api/exo/


Installation

Pre-Install Requirements

Full details of requirements and supported operating systems for PCs running MYOB Exo Business components are available on the Minimum System Requirements page on the MYOB website.

The Exo API requires Exo Business 8.4 or later. If you are using Exo Business 8.7 or later, you can set up the Exo API using the Exo Business Configurator application; for Exo Business versions 8.4 8.6, you must use the separate ExoMobileConfig.exe

Setting up Exo Business Services 8).

Installing the Exo Business Services

The Exo Business Services Setup Wizard, Exo Business Services Installer.msi, installs the local components needed to access the Exo API from an Exo Business server. This wizard is supplied with the main Exo Business installer in Exo Business 8.7 and later.

The Exo Business Services Setup Wizard must be run on a server that already has Exo Business installed on it. It must be run from an account with administrative permissions.

To perform the installation: 1. Double-click on the Exo Business Services Installer.msi installer. The welcome

screen appears:

http://myob.com.au/products/medium-business/enterprise-solutions/exo-business-1258090694421?productArea=Minimum+System+Requirements&category=1257828903138

http://myob.com.au/products/medium-business/enterprise-solutions/exo-business-1258090694421?productArea=Minimum+System+Requirements&category=1257828903138

Installation


2. Click Next. The MYOB Exo End User Licence Agreement is displayed:

3. Tick I accept the terms in the Licence Agreement and click Next to continue.

4. Select which components to install. Choose from:

• The Exo API Service

• The Exo Messaging Service

Note: Setting up the Services 6).

5. The install location is displayed at the bottom of the window. Click Browse to choose a different location if necessary.

Installation


6. Click Next. You are now ready to install the Exo API components.

7. Click Install to being the installation. The progress of the installation is

displayed:

Installation


8. Once the installation is complete, click Finish to close the wizard. You can choose to open the Exo Business Service Configuration utility to set up details of the Exo API services (see page 6).

Note: The Exo Business Service Configuration utility is installed in the same location as the Exo API services. You can run the utility (MYOB.ED.Exo.Cloud.ServiceConfig.exe) from this location at any time.


Setting up the Services Once the Exo Business services have been installed, they must be set up and the Exo Business system must be configured to interact with them. These steps are detailed below.

Note: All setup must be performed on the server that the services are installed on, using an account with administrative permissions.

Setting up Exo Business Services

The Exo Business services must be set up for each Exo Business database connection, using the MYOB Exo Business Service Configuration utility. This utility, MYOB.ED.Exo.Cloud.ServiceConfig.exe, can be run immediately after installation, or you can open it from the Exo API install directory at any time.

The utility displays configuration settings for the following services:

• Exo API Configuration

o API Services use this service if you want to use the Exo API on a local network.

o Live Relay Services use this service if you want to communicate with the Exo API remotely using the online MYOB LiveRelay. (You can use both the API Service and the Live Relay Service at the same time.)

• Exo Business Message Service Configuration

o Message Services this is the Exo Business messaging service.

To configure an API service, select an Exo Business database connection, then click the relevant Add Service button.

Setting up the Services


Note: The Exo Business database connection must have been created using an account with administrative permissions. It should specify a valid server name (not blank, local, localhost, etc). This same account should be used to run the MYOB Exo Business Service Configuration utility.

For the API Service, you must also enter a Base URL, which is the location and port the API is accessible on (the default should be suitable in most cases, unless you want to use a different directory and/or port).

Note: For local API access, ensure that your firewall is configured to allow the relevant ports, services and/or applications.

To validate that the Exo API has been successfully installed and set up, navigate to the Base URL in a web browser or REST client to see a list of available endpoints.

Note: type. If the API Service attempts to starts before the MSSQL service has started, it will fail. Setting the API Service to a delayed start, and having SQL Server as automatic (not delayed) should overcome this problem during bootup.

The configuration process for the messaging service is slightly different; where the API services create a separate instance for each Exo Business database connection, the messaging service has a single instance, which can have multiple connections to it.

To install the messaging service instance, select a database connection and click Add Connection. This adds the service and sets up a connection to the selected database. To add new connections, select them from the Exo Connection dropdown and click Add Connection.



Setting up Exo Business

The Exo Business system must be set up to use the Exo Business services. Setup can be performed in two ways:

• If you are using Exo Business 8.7 or later, you can use the Exo Configurator or the Exo OnTheGo Configurator to set up the Exo API.

• If you are using Exo Business 8.3 8.6, you must use the Exo OnTheGo Configurator, which is installed with the Exo API. This application contains only the Exo Configurator screens that are relevant to Exo API.

Adding the Exo API and Exo OnTheGo Modules Exo Exo

Configurator/Exo OnTheGo Configurator. To do this:

1. Click the Add toolbar button. 2. Exo Module dropdown. 3. Enter your licence details. 4. Click Save. 5. Click Launch Update to update the Exo Business system.

If you are licensed to use the Exo Exo OnTheGo Repeat steps 1 Exo

Updating the Exo Business Database If you are upgrading to a new version of the Exo API, you must update the database to add support for any new features used by the API. Open the Exo OnTheGo configurator and click the Launch Update button on the Company section.

Generating User Tokens Once the Exo API module is added and licensed, an API/OnTheGo Access tab becomes available when editing staff members in the Staff section of the Exo Configurator:



A similar tab is available in the Exo OnTheGo Configurator:

Tick the Allow API Access box for each staff member who will need to use the Exo API. This generates an API token for the staff member, to be used in API requests. You can right-click on the token to copy it to the clipboard.

For more information on working with the API and required token, see the Exo API Online Help at http://developer.myob.com/api/exo/exo-api-overview/getting-started/.

Adding Exo OnTheGo Access and Devices Once the Exo OnTheGo module is added and licensed, an OnTheGo sub-tab becomes available when editing staff members in the Exo Configurator and Exo OnTheGo Configurator:

Tick the Allow OnTheGo Access box to enable access to the Exo OnTheGo app for that staff member. The Exo OnTheGo license specifies a maximum number of usersonce this limit has been reached, the Allow OnTheGo Access box is disabled on all other staff members.

Note: If you reduce the number of Exo OnTheGo users you are licensed for, you must untick the Allow Mobile Access boxes of enough staff members to bring you down to the new limit before you can save the new licence.

http://developer.myob.com/api/exo/exo-api-overview/getting-started/

http://developer.myob.com/api/exo/exo-api-overview/getting-started/



The Exo OnTheGo app can be licensed for up to two devices per staff member. Click the Add Device button on the OnTheGo sub-devices.

Device Name Enter a descriptive name for the device.

Device ID . You can find this number using the

Exo OnTheGo app:

1. Open the app. 2. On the login screen that appears, tap the > arrow next to the connection name.

(If this is the first time you are using the app, the connection name will be

3. On the Connections window, tap Add connection to open the Create connection window. The UDID appears at the bottom of this window.

4. Tap the icon to create an email containing the UDID. Send this email to an address that can be accessed from the Exo Business server.

5. On the Exo Business server, open the email and copy the UDID. 6. Paste the UDID into Exo Configurator or Exo OnTheGo Configurator.

Click OK. A key is generated for the device; this key is to be used in API requests from the device, and must be entered when setting up a connection to the device in the Exo OnTheGo app. You can right-click on the key to copy it to the clipboard.



Bulk Loading Locations The Exo API can retrieve the geolocation details (latitude and longitude) stored for Debtors, Creditors, Non Accounts and Contacts to search for accounts based on their physical location the Exo OnTheGo app makes use of this functionality, for example. These details can be entered in the Exo Business system in version 8.7 SP2 and later; in previous versions, the details must be entered and updated in bulk using the Exo OnTheGo Configurator.

To enter location details, click the Geo Locations button on the main toolbar:

To bulk update location details:

1. Use the Update locations for: dropdown to select the kind of account to update (Debtors, Creditors, Non Accounts or Contacts).

2. Use the Update where status is in: dropdown to filter the list of accounts by status. Only accounts that appear on the list will be updated. By default,

3. Click Bulk Update.

The system attempts to retrieve details for each account in the list, and updates each

Note: For versions prior to Exo Business 8.7 SP2, the Exo OnTheGo Configurator inserts database triggers to ensure that geolocation details are updated

upon upgrading to Exo Business 8.7 SP2 or later.



Testing the API Service

Once the API service is installed and set up, you can test it using the Advanced Rest Client in Google Chrome:

1. Download and run the Advanced Rest Client. 2. Enter the URL: http://localhost:8888/contact 3. Add a 4. Right-click on this header and click the Edit value box that appears. 5. On the Basic tab of the popup that appears, enter the login details of a user for

the Exo OK.

6. Add a header ca x-myobapi-exotoken 7. Enter the API access token for the user whose login details you entered in step

5. (You can copy the token from Exo Business Config > Staff > Staff > API/OnTheGo Access tab > API sub-tab.)

8. Click Send.

The response should be 200 OK and a list of the contacts from the system should be returned.

Troubleshooting

If you encounter any problems when using the Exo API, the Exo API & OnTheGo Troubleshooting Guide may help you to diagnose and solve these problems. This document is available on the Exo Business Education Centre at http://help.myob.com.au/exo/onthego.

https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo

https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo

http://help.myob.com.au/exo/onthego


New Features

New Stock Adjustment Endpoints

This release adds new endpoints for creating new stock adjustment transactions:

• stock/sale create a stock sales adjustment. • stock/receipt create a stock receipt adjustment. • stock/transfer create a stock transfer adjustment. • stock/adjustin create a stock adjust in adjustment. • stock/adjustout create a stock adjust out adjustment.

These endpoints can only be used to create adjustment transactions, i.e. they support the POST operation only (to retrieve details of stock transactions, use the new stock/transaction endpoint see page 14).

The stock adjustment endpoints are all structured the same way; each has the following attributes:

Attribute Type Can be null Description

createdate string no The date and time when the transaction was created.

periodid integer no The ID number of the ledger period that the transaction will be created in.

reference string yes A reference code for the transaction.

narrative string yes Narrative text for the transaction.

lines array yes An array of transaction lines Transaction Linesbelow for the attributes of each line object.

rel string yes Relative path to the endpoint.

title string yes

id string no

href string yes Hyperlink for the report request.

New Features


Transaction Lines The lines attribute of each of the new stock adjustment endpoints is an array of line objects. Each line has the following attributes:


tolocation integer no This attribute is used for the stock/transfer endpoint only; the other stock adjustment endpoints do not use this attribute. It specifies the location that stock was transferred to.

stockcode string yes The ID code for the stock item on the line.

reference1 string yes A source transaction reference on the line. Usually contains the Debtor/Creditor s invoice number, Purchase Order number, Sales Order number, job number, etc.

reference2 string yes A secondary reference code.

quantity number no The quantity on the line.

unitprice number no The unit price of the stock item on the line.

location integer no The ID number of the Location involved in the stock movement.

glaccount string yes The General Ledger account that is affected when the transaction is posted to GL.

New Stock Transaction Endpoint

The new stock/transaction endpoint is used to retrieve details of existing stock transactions (it supports the GET operation only). This endpoint is called in the following format:

stock/transaction/{ledger}/{id}

Where {id} {ledger} is the ledger type; currently only stock is supported.

The endpoint supports the following attributes:



transactiontype integer yes The type of the transaction. Will be one of:

• 0 = Sales

• 1 = Receipt

• 2 = Transfer

• 3 = Adjust Out

• 4 = Adjust In

• 5 = Average Cost Adjustment

New Features



reference string yes Reference text on the transaction header.

staffid integer no The ID number of the staff member who created the transaction.

periodid integer no The ID number of the ledger period that the transaction is in.

narrative string yes Narrative text for the transaction.

lines array no An array of transaction lines


title string yes

id string no


Transaction Lines The lines attribute of each of the new stock adjustment endpoints is an array of line objects. Each line has the following attributes:


id integer no

stockcode string yes The ID code for the stock item on the line.

transactiontype integer yes The type of the transaction. Will be one of:

• 0 = Sales

• 1 = Receipt

• 2 = Transfer

• 3 = Adjust Out

• 4 = Adjust In

• 5 = Average Cost Adjustment


reference1 string yes A source transaction reference on the line. Usually contains the Debtor/Creditor s invoice number, Purchase Order number, Sales Order number, job number, etc.

reference2 string yes A secondary reference code.

quantity number yes The quantity on the line.

unitprice number yes The unit price of the stock item on the line.

location integer yes ID number of the location involved in the stock movement.

New Features



tolocation integer yes ID of the destination location (only applies to stock transfers).

fromledger string yes The ledger that the transaction comes from:

• d = Debtor

• c = Creditor

• s = Stock

• j = Job Costing

• i = Inwards Goods Receipt

• o = Sales Orders

• p = Purchase Orders

glposted boolean yes Whether or not the transaction has been posted to the General Ledger.

glaccount integer yes The General Ledger Account that is affected when the transaction is posted to GL.

unitcost number yes The unit cost price of the stock item.

expirydate string yes The Expiry Date for a batch tracked item.

plu string yes The Price Lookup Unit (applies to lookup items).

posttogl boolean yes Whether or not the stock line is posted to GL.

sessionid integer yes Sessions ID number.

batchcode string yes The batch number, if applicable.

General Ledger Endpoint

This release adds new endpoints that give access to the General Ledger (which is required for the stock movement endpoints detailed in the previous section).

Period Status Endpoint A GET call to the periodstatus endpoint returns attributes of a specified ledger period. The endpoint supports the following attributes:


age integer no The age of the period. The current period has an age of 0.

ledger string yes The ledger for the age. Will be one of:

• C Creditors

• D Debtors

• S Stock

• G General

New Features



locked boolean no If true, the period is locked, implying that this age in a specific ledger is closed and no more transactions should take place

periodid integer no The period's sequence number within the fiscal year.

name string yes The name/description for the period, e.g. October 2016.

shortname string yes A short name for the period, e.g. Oct16.

reportcode string yes A code used for reporting purposes.

yearage integer no The ageing of the year that the period falls in. The current year has an age of 0.

startdate string no The start date for the period.

enddate string no The end date for the period.

finqtr integer no The financial quarter that the period belongs to.


title string yes

id string no


General Ledger Endpoint A GET call to the ledger endpoint returns the details of all General Ledger accounts. You can return the details of a single account with a call to ledger/{id}. The endpoint supports the following attributes:


name string yes display name.

active boolean no Whether or not the account is currently active.

subaccounts array yes An array of all subaccounts beneath the account. Each subaccount is returned with its name and ID.


title string yes

id string no


New Features


Chart of Accounts Endpoint A GET call to the ledger/chart endpoint returns the chart of accounts for your system. The endpoint supports the following attributes:


name

subaccount

subaccountname

branch

active

code

formattedid

formattedaccount

formattedsubaccount

formattedbranch

id string no


Display Names in Report Parameter Labels

Exo Business 2016.3.1 added the ability to insert a defined Display Name into the label of a report parameter. This functionality is now supported for report parameters that are returned by the Exo API.

Note: Display Names are set up on the Display Names screen in Exo Business Config. For more information on adding Display Names to report parameter labels, see the Release Notes document for Exo Business 2016.3.1 (available on the Exo Business Education Centre).

Known Issues


Known Issues The following issues have been identified as requiring end-user attention in this release.

Timeout Issues The API communicates using HTTP; any request that takes more time to complete than the standard HTTP timeout period will fail. This may include search operations that would return a large set of results or operations on transactions like Sales Orders that have a large number of lines. How large an operation has to be before it times out will depend in part on the speed of the Exo Business database server, network connectivity, etc.

MYOB Exo Business Serviceshelp.myob.com.au/exo/onthego/releasenotes/15/MYOB EXO...using the MYOB Exo...

Documents

Transcript of MYOB Exo Business Serviceshelp.myob.com.au/exo/onthego/releasenotes/15/MYOB EXO...using the MYOB Exo...