devdocs/todo.txt

@@ -3,6 +3,8 @@
 
 
 - DOCS for QBI
+- DOCS FOR AYANOVA (integrations and dev stuff)
+- there aer changes to everything so rebuild all before next deploy
 - Post as qbi rc.1
 - build AyaNova server package fresh, update test copy, test from here with downloaded qbi rc.1 build 
 - If all is well then post about it on the forum

docs/8.0/ayanova/docs/adm-integrations.md

@@ -0,0 +1,67 @@
+# Integrated applications
+
+Integrated applications are external programs that use the AyaNova [developers api](api-intro.md) to perform actions on AyaNova data.
+
+For example our optional [QBI application](https://ayanova.com/qbi/docs/) that integrates the QuickBooks accounting program with AyaNova uses the Integrated applications feature to store it's configuration and links between AyaNova and QuickBooks objects and log information for troubleshooting purposes.
+
+Integrated application objects are not used by or created within AyaNova but rather by 3rd party or optional add-on products to integrate with AyaNova.
+
+(Integrated application objects can be deleted here though see the [delete](#delete) menu option documentation below for details)
+
+These objects store logs, configuration settings and often links and maps between AyaNova objects and objects in other software.
+
+Note that only programs that wish to store data inside AyaNova will be listed here.
+
+A program can connect to AyaNova without making use of the Integrated applications feature, it's a convenience not a requirement.
+
+(AyaNova will still enforce security no matter how it is being accessed so a program still needs to login as an AyaNova User and can only access data which that User's [Roles](ay-biz-admin-roles.md) permit.)
+
+## Authorization Roles required
+
+Accessing the Integrated applications section of the AyaNova user interface is only available to Users with the following [roles](ay-biz-admin-roles.md):
+
+- Business administration
+
+## How to access Integrated applications
+
+From the `Administration` [navigation drawer](ay-start-form-overview.md#navigation-drawer) select `Integrated applications` navigation item.
+
+## Integrated applications data table
+
+![Integrated applications data tabl](img/adm-integrations.png)
+
+This [data table](ay-start-form-data-tables.md) lists all the Integrated applications that chose to store configuration and mapping data within AyaNova.
+
+## Integrated applications edit form
+
+![Integrated applications edit form](img/adm-integrations-edit-form.png)
+
+The Integrated application edit form provides some of the [standard edit form](ay-start-edit-forms.md) functionality and the following fields:
+
+#### Name
+
+This is the Name set by the integrating application. This field is not editable.
+
+#### Active
+
+This field controls the Active status of the integrating application. If set to false, integrating applications _should_ respect this setting and be disabled until it's set to true again, however this is at the discretion of the developers of those applications and may not be honoured by them.
+
+This is the only editable field on this form.
+
+#### Log area
+
+If the integrating application chooses to log to AyaNova it's log can be viewed here. Logs are automatically trimmed by AyaNova and any entries older than 90 days are removed as these logs are intended for short term troubleshooting purposes, not auditing.
+
+### Menu options
+
+In addition to some of the [common edit form menu options](ay-start-edit-forms.md#common-edit-form-menu-options), this form also has these unique menu options:
+
+#### Delete
+
+An Integrating application's data can be deleted here which will completely remove all it's data from AyaNova.
+
+Typically this is used when an integrating application has been uninstalled and is no longer used or as a way to completely reset any configuration previously made in the integrating application and start over. Be sure to close the integrating application before deleting it's integration data here to be safe.
+
+#### Copy
+
+This option will copy the entire log displayed to the Clipboard (if your device / browser supports this).

docs/8.0/ayanova/docs/api-integrated-applications.md

@@ -0,0 +1,66 @@
+# 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
+
+There are two interfaces for this feature:
+
+## User interface
+
+One side of this feature is the [Integrated applications User interface](adm-integrations.md) 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](api-console.md).
+
+#### POST - Create an Integration record
+
+An integration is first created by posting to the `/integration` route.
+
+```json
+{
+  "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 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.
+- `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

docs/8.0/ayanova/mkdocs.yml

@@ -112,6 +112,7 @@ nav:
       - 'Import Units': 'adm-import-unit.md'   
       - 'Import Vendors': 'adm-import-vendor.md'   
       - 'Import Warehouses': 'adm-import-warehouse.md' 
+      - 'Integrated applications': 'adm-integrations.md'
     - 'Vendors': 'vendors.md'  
     - Extensions:
       - 'Extensions': 'ay-extensions.md' 
@@ -192,6 +193,7 @@ nav:
   - 'API response format': 'api-response-format.md'
   - 'API error codes': 'api-error-codes.md'
   - 'API upload routes': 'api-upload-routes.md'
+  - 'API Integrated applications': 'api-integrated-applications.md'
   - 'API Data types': 'ay-start-data-types.md'  
 - Appendix:
   - 'Data types': 'ay-start-data-types.md'