Connecting Other Systems
Assets can be read and written by software as well as by people — a procurement system that registers new equipment, a handheld scanner used on an audit floor, an accounting package that pulls a posted depreciation period, and the staff mobile app. This page is for the person who has to decide what to grant, not for the person writing the code.
Two separate interfaces, for two different callers
They are not two versions of the same thing. They differ in who is asking, and that decides everything else about them.
| The integration interface | The employee interface | |
|---|---|---|
| Who calls it | Another system — procurement, accounting, an audit scanner, a reporting tool. | A person, through the staff mobile app, signed in as themselves. |
| How access is granted | An administrator issues credentials and grants one or more scopes (below). | Nothing to grant. Anybody who can sign in already has it. |
| What it can see | Whatever the granted scopes allow, across the whole company. | Only the caller's own equipment — and equipment they are the caretaker of. Anything else answers “not found”. |
| Typical use | Registering purchased equipment automatically; pulling a closed depreciation period into the ledger. | “Confirm you received this laptop”; “report that the screen is cracked”. |
The four scopes — and why they are not one
A scope is what an integration is allowed to do. They are deliberately narrow, because the alternative is handing an accounting system the ability to rewrite your entire equipment register in order to let it read one month's figures.
| Scope | Allows | Grant it to |
|---|---|---|
| Assets (Read) | Listing and reading equipment records, and reading an asset's fault history. | Reporting tools, dashboards, anything that only needs to look. |
| Assets (Write) | Creating and updating equipment records, accepting a return, and filing a fault report. | A procurement or provisioning system that registers equipment as it arrives. |
| Assets (Audit) | Opening an audit campaign and recording counts against it. Nothing else. | A handheld scanner or a stock-take app. It can record what it finds and cannot touch the register. |
| Assets (Finance) | Reading depreciation periods and their lines, and filing a disposal. | An accounting system. It can pull a closed period and retire an asset, and it cannot edit equipment or start an audit. |
The four scopes appear in the platform's API access screens only while the Assets module is installed, so a company that does not use Assets is never offered them.
What the integration interface can do
Twelve operations, grouped by the job they belong to.
| Group | What a caller can do | Scope needed |
|---|---|---|
| Equipment | List equipment (filtered by category, status, holder, or a search); read one record in full; register a new one; update an existing one; record that something has been returned. | Read for the first two, Write for the rest |
| Faults | Read an asset's fault history; file a new fault report against it. | Read to look, Write to file |
| Audits | Open an audit campaign; record a count against one. | Audit |
| Accounting | List depreciation periods; read one period with a page of its lines; file a disposal. | Accounting |
Three behaviours worth knowing before you plan an integration
- Retries are safe on the scanner and on disposals. Sending the same count twice is recognised as a repeat rather than recorded as a second observation, and asking to dispose of an asset that already has an open disposal returns the existing one instead of starting a second. A dropped connection is not a data problem.
- A refused disposal says why. When the disposal rules block a request, the answer names what is standing in the way — equipment still held, a fault still open — rather than simply failing. The caller is told what to clear.
- Long lists are paged, always. A monthly close over a real estate carries thousands of depreciation lines, and a period is returned a page at a time. Your administrator can set the largest page a caller may ask for on the Settings page (100 by default).
What the employee interface can do
This is the surface behind the staff mobile app. Thirteen operations, all of them about the caller's own equipment, and none of them needing an administrator to grant anything.
| The employee can | Which means |
|---|---|
| See their own equipment | The list of what is currently endorsed to them, and the full detail of any one item. |
| Confirm receipt | Acknowledge that they have physically received something handed to them — the step that closes the gap in the chain of custody. |
| Ask to return something | Signal that they are finished with an item, so somebody can arrange to take it back. |
| Report a fault | Raise a fault against something they hold, and read its history. |
| Confirm a repair actually worked | After a repair is marked done, say whether the problem is genuinely fixed. A closed ticket is the technician's opinion; this is the holder's. |
| Read and answer their endorsement paperwork | See the handover documents addressed to them, and accept or reject one. A document can cover several items at once, which is why it is separate from the equipment list. |
| See what they look after | Equipment they are the caretaker of on behalf of a branch, department, project or room. It is not issued to them personally, so it can never appear in the list above. |
| Read the equipment categories | Reference data, so the app can label and group what it shows. |
Granting access, in the right order
-
Ask what the integration actually needs to do
“Read equipment”, “register new purchases”, “record counts”, “pull the closed period”. Each of those maps to exactly one scope in the table above.
-
Grant only those scopes
Grants are issued from the platform's API access screens by an administrator, not from within Assets. Adding a scope later is easy; discovering that a token has been able to rewrite the register for a year is not.
-
Check that the module is enabled and stays enabled
Both interfaces stop when the module is off. If Assets is ever switched off for a maintenance window, expect the integration to report failures.
-
Agree a page size and let them page
Set the maximum page on the Settings page if the default of 100 does not suit, and expect the caller to follow the pages rather than asking for everything at once.
-
Watch the activity log for a week
Everything an integration changes is written to the affected asset's own history, exactly as if a person had done it. The first week of that log will tell you whether the integration is doing what you agreed.
What the interfaces deliberately do not do
Naming the gaps is the point of this section — a plan built on an assumption that turns out to be wrong is more expensive than a plan that started with the truth.
- No accounting entries are posted anywhere. The finance scope lets a caller read a posted depreciation period. Turning that into journal entries in your ledger is the calling system's job; Assets does not write to a general ledger. See Finance & Depreciation.
- No custody paperwork is created through the integration interface. Endorsing equipment to somebody is a decision with a signature attached, and it is done in the application.
- No bulk import. Loading a spreadsheet of equipment is a separate, supervised job with its own screen — see Import, Export & Labels.
- No webhooks or push notifications. Nothing calls out to another system when something changes; an integration reads when it wants to know.
Related
The API tab, where the maximum page size is set and the grantable scopes are listed.
How access works for people, which is a separate system from scopes for machines.
What happens to a fault an integration or a phone reports.
What a depreciation period is, and what “posted” means before anything can pull it.