Unique Business Keys

Introduction

Unique Business Keys (UBKs) enable direct access to a specific entity. There are two types of UBK on some entities:

Primary UBK (PUBK) - the key is the "natural" key for the entity (e.g. Document Reference or Customer Code)
Secondary UBK (SUBK) - the key is some other attribute which happens to be unique - n.b. consultancy required to implement.

Primary Unique Business Keys (PUBKs)

Entities can be accessed by specifying a full access path and a PUBK thus (by example):

https://www.aqilla.net/InstanceName/wsapi/2.5/Documents/Purchase Invoice/Purchase Invoice - Details/PI_C000012

One PUBK is supported for each entity type. Example PUBKs include:

Document Reference
Customer Code

The PUBK for an entity is unlikely to change after creation (and will never change in some circumstances - e.g. if Document Reference is used as a PUBK) but integrators must not assume that PUBKs never change. For example it would be possible to change Customer Code (a typical PUBK) after creation.

Secondary Unique Business Keys (SUBKs)

Where supported entities can be accessed by specifying a full access path and an SUBK thus:

https://www.aqilla.net/ InstanceName/wsapi/2.5/Documents/Purchase Invoice/Purchase Invoice - Details/{SUBK}

Please contact your Aqilla consultant or account manager if you want to use SUBK's

Errors

If a UBK is used which - for any reason - is not unique the Aqilla API will return an error message:

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataentry>
  <error>
    <message>More than one entity was found with given key</message>
  </error>
  <subordinates/>
</dataentry>

Managing UBKs

UBKs are managed at Configuration > Entity Types > {Entity} > {Attribute} > More. For example:

The attribute in question is UBK Type which has the options No, Primary or Secondary.

Configuration > Entity Types is only accessible to Aqilla consultants.

GUID

When an entity (e.g. a reference record or document) is created through the Aqilla API a GUID is returned in response. The entity can be subsequently accessed using that GUID thus:

https://www.aqilla.net/ InstanceName/wsapi/2.5/3yrv7wO6oHxfVAN8ekZd

Note that it is not necessary to specify a full access path to the entity in question.