Module xero.assets
ballerinax/xero.assets Ballerina library
Overview
Xero is a cloud-based accounting platform for small and medium-sized businesses. The Xero Assets API exposes the fixed asset features of Xero Accounting, such as registering assets, managing asset types and reading depreciation details.
The Xero Assets connector lets Ballerina applications list, create and look up fixed assets, manage the asset types that define how assets depreciate, and read an organisation's fixed asset settings. It supports version 1.0 of the Xero Assets API.
Key features
- Search fixed assets by status, with paging, ordering and text filtering
- Register new fixed assets and retrieve an asset with its depreciation details
- Create and list asset types with their depreciation settings
- Read the organisation's fixed asset settings, such as the asset number prefix and the last depreciation date
Setup guide
To use the Xero Assets connector you need a Xero account and an app registered with the Xero developer portal.
Step 1: Create a Xero app
- Sign in to the Xero developer portal and select New app.
- Enter an app name and choose the Web app integration type.
- Enter your company URL and add a redirect URI, for example
http://localhost:8080/callback. - Accept the terms and select Create app.
Step 2: Get the client credentials
Open the Configuration page of the app and generate a client secret. Note down the client ID and the client secret.
Step 3: Get a refresh token
-
Direct the user to the authorization URL, replacing
YOUR_CLIENT_IDandYOUR_REDIRECT_URI, and replaceYOUR_STATEwith a random, unguessable value generated for this request (for example, withopenssl rand -hex 16). Include theoffline_accessscope so that a refresh token is issued.https://login.xero.com/identity/connect/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=openid profile email assets offline_access&state=YOUR_STATE -
Check that the
statereturned to your redirect URI matches the value you sent, and stop if it does not. Then exchange the authorization code for tokens. curl prompts for the client secret, so it is not echoed or kept in your shell history.curl -X POST https://identity.xero.com/connect/token \ -u CLIENT_ID \ -d "grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI"The response contains an
access_tokenand arefresh_token. Use theassets.readscope instead ofassetsif the app only needs read access.
Step 4: Find the tenant ID
Every request must carry the ID of the Xero organisation it acts on. List the organisations the user connected to your app:
curl -X GET https://api.xero.com/connections \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Use the tenantId of the organisation you want to work with.
Quickstart
To use the xero.assets connector in your Ballerina application, update the .bal file as follows:
Step 1: Import the module
import ballerinax/xero.assets;
Step 2: Instantiate a new connector
Create a Config.toml file with your credentials:
clientId = "<client-id>" clientSecret = "<client-secret>" refreshToken = "<refresh-token>" tenantId = "<xero-tenant-id>"
Then create a client in your .bal file:
configurable string clientId = ?; configurable string clientSecret = ?; configurable string refreshToken = ?; configurable string tenantId = ?; assets:Client xeroAssets = check new ({ auth: { clientId, clientSecret, refreshToken } });
Step 3: Invoke the connector operation
List the registered fixed assets of the organisation:
public function main() returns error? { assets:Assets _ = check xeroAssets->listAssets({xeroTenantId: tenantId}, {status: "REGISTERED"}); }
Step 4: Run the Ballerina application
bal run
Examples
The Xero Assets connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:
-
Asset register review - Page through every registered fixed asset, total the purchase price and book value, and inspect the latest purchase.
-
Asset type onboarding - Create a fixed asset type if it is missing, record a new asset against it and confirm the numbering settings.