Integrated applications¶

Often when working with AyaNova, external applications will have common needs:

Persisting configuration data
Persisting maps and links between AyaNova objects and external objects in other applications
Logging troubleshooting information
A master on/off "switch" to control the Integrating application from within AyaNova itself

AyaNova provides the Integrated applications feature to support all of the above with a User facing and Developer facing side:

User interface¶

One side of this feature is the Integrated applications User interface available to the Business Administration role allowing them to view the log, control the Active status of the application and when necessary delete the stored integration data from AyaNova.

Developers interface¶

Using standard AyaNova API routes, developers can leverage this feature to provide configuration and mapping data persistance, logging for troubleshooting and a master on/off "switch" to control the active status of the integrating application.

API Routes¶

As with all API routes in AyaNova, these API routes can be viewed in the API explorer console.

POST - Create an Integration record¶

An integration is first created by posting to the /integration route.

{
  "id": 0,
  "concurrency": 0,
  "integrationAppId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "active": true,
  "integrationData": "string",
  "items": [
    {
      "id": 0,
      "concurrency": 0,
      "integrationId": 0,
      "objectId": 0,
      "aType": 0,
      "integrationItemId": "string",
      "integrationItemName": "string",
      "lastSync": "2022-07-15T22:25:53.029Z",
      "integrationItemData": "string",
      "integration": "string"
    }
  ]
}

id and concurrency should always be 0 when first posting as this number is assigned by AyaNova after it has created the posted object in the database.
integrationAppId: this field is critical, it should be the unique and unchanging UUID representing your unique application and any version compatible with the integration data stored. It should uniquely identify your application and be the same for all instances of your application no matter where it's installed. This ensures that a User can uninstall and re-install your application without losing the configuration data. In cases where your configuration schema changes you should not simply use a new UUID value but rather handle that scenario by supporting reading in the older format config data, modifying the configuration data to the new format and saving it back in the new format.
name: this field is the name of your application as it's know to the User and will display in the Integrated applications User interface of AyaNova.
active: this field is intended to allow the end user to control your application and to temporarily disable or enable it. We strongly recommend making use of this feature and on start up of your application (or more often if practical) checking this value and preventing your application from running if it's set to false.
integrationData: this field is provided to store any value your application requires for operation. A common use would be to store a JSON or XML formatted object as a string. This field is backed by a Postgres 'text' character type which is theoretically unlimited but in practice you should not store more than a few kb here.
items: this optional collection is often used to map or link AyaNova objects to external application objects for synchronization purposes however you can use it in any way that makes sense or not at all:
- id, concurrency, integrationId always set these to zero when initially creating / posting, AyaNova will fill these in automatically from the database records created
- objectId: required the AyaNova Id of the AyaNova object in this map/link record, required but there is no requirement that it be an actual ID if you want to use this for other purposes
- aType: the mapped AyaNova object's Type integer enumeration value. See the /enum-list/list/AyaType api route to view all AyaNova defined types and their id's.
- integrationItemId: the id value of the object as known to the integrating application. Stored as a string here.
- integrationItemName: optional place to store the name of the object as it's know to the integrating application. Useful for UI purposes when showing what integrating object is linked to what in AyaNova
- lastSync: optional place to record the last time the two objects were synchronized in cases where your application needs to update one side or the other on a timely basis
- integrationItemData: optional place to store any extra data you wish to go with this particular item. A common use would be to store a JSON or XML formatted object as a string. This field is backed by a Postgres 'text' character type which is theoretically unlimited but in practice you should not store more than a few kb here.
- integration: in internal pseudo field to link the integration item to the integration object, not actually used by the rest route and will be ignored if set

PUT - Save an Integration record¶

Update your integration object by PUTting it to the \integration route. Concurrency and ID values must be set and you should handle a scenario where the concurrency token has changed because a User has changed the Active status of your integration within AyaNova.

Essentially you PUT the entire object you fetched in a GET or POST earlier with modifications.

GET - Fetch an integration record¶

Fetch your integration data by your integration application UUID from the /integration/{integrationAppId} route.

Note that you can check if the integration object already exists first by using the /integration/exists/{integrationAppId} route which will return a true or false value depending on what it finds in the database.

DELETE - Remove an integration record¶

Remove your integration with the /integration/{integrationAppId} route.

LOGGING - create a log entry¶

The Integration log is used by AyaNova Users and your technical support staff to troubleshoot issues with your integrating application.

AyaNova will daily trim the log keeping only entries younger than 90 days and make them available for viewing in the AyaNova user interface to the Business administration role user.

Log entries are made by posting to the following route /integration/log the following object:

{
  "id": 0,
  "name": "string"
}

id: this is the internal id of the integration object not your integration application UUID. In other words this is the value in the Id field returned when you fetch or post the Integration object.
name: this field is the log line item you wish to post. It's better to break up large items rather than posting a huge chunk of text in one go for readability purposes.

Date and time (in UTC) are automatically added to the log entry by the server when posting and displayed to the User in their local time zone.