diff --git a/docs/8.0/ayanova/docs/api-integrated-applications.md b/docs/8.0/ayanova/docs/api-integrated-applications.md index 88831617..c6ec7ebc 100644 --- a/docs/8.0/ayanova/docs/api-integrated-applications.md +++ b/docs/8.0/ayanova/docs/api-integrated-applications.md @@ -7,7 +7,7 @@ Often when working with AyaNova, external applications will have common needs: - Logging troubleshooting information - A master on/off "switch" to control the Integrating application from within AyaNova itself -There are two interfaces for this feature: +AyaNova provides the Integrated applications feature to support all of the above with a User facing and Developer facing side: ## User interface @@ -51,16 +51,53 @@ An integration is first created by posting to the `/integration` route. ``` - `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 GUID 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 Guid 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. +- `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](adm-integrations.md) 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](https://www.postgresql.org/docs/current/datatype-character.html) 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](https://www.postgresql.org/docs/current/datatype-character.html) 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 + - `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](https://www.postgresql.org/docs/current/datatype-character.html) 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: + +```json +{ + "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.