We have created a new Application within Aptify, as well as several entities to standardize integration processes. The Framework includes multiple entities to be able to cover all possible integration scenarios and needs. These are intended for Administrator/Developer use only. Each integration does not necessarily have to use each part of the framework.
This framework was designed to be extensible to virtually any type of integration, without being an onerous overhead. It has numerous pieces to improve integration performance, as well as greatly simplify troubleshooting.
This framework was developed to standardize integration connections between Aptify and third party systems on a single, flexible framework. Integrations do not necessarily need to use all of the framework, but the core ones are identified in the document.
The framework eliminates duplicative integration points and provides significant error handling and troubleshooting capabilities. New integrations should be built with the new Integration Management framework, and existing integrations can also be adapted to use this as well.
Contents
- New Application
- New Entities
New Application
A new application, Integration Management, contains all the entities and subtypes for this framework. You may need to add each service to your application upon deployment.
Note: you may need to add User/Group security to this Application based on your organizational needs.
New Entities
The framework contains a series of 6 new entities (and 2 subtypes) designed to support a variety of integrations. Identified below is an ERD diagram of how each of these entities relate to each other:
The core two entities are Integration System, which tracks information about each integration, and Integration Logs, which stores data for each integration action.
A brief description of each entity and usage is listed below, including whether usage is required for integrations or just recommended. More information on each entity is included further below in the document.
Static Setup Data (setup once per integration)
| Entity | Description | Required Usage? |
| Integration System | Entity identifying integration system, as well as integration attributes, encrypted handshake keys, etc. | Yes |
| Integration System Attributes | Subtype of Integration System entity containing Name/Value fields to store various attributes specific to each Integration. | Yes |
| Integration Category | Entity listing out the different categories of integration, e,g, LMS, CMS, Event Registration, Third Party Order system. | Yes |
| Integration Field Mapping | Lookup table to map Aptify entity field records to integration field names | No |
| Integration Log Type | Entity defining the type of the Integration action captured in the Integration Log. For example, PersonCreate. | Yes |
| Integration Log Type Attribute | Subtype of Integration Log Type entity containing Name/Value fields to store various attributes specific to each Log Type. E,g, PersonCreate uses spIntegratationCreatePerson. | No |
Dynamic Integration Data (transactional records generated by the integration)
| Entity | Description | Required Usage? |
| Integration Logs | Entity that stores the transactional record of each integration action, classified by the Integration System and Log Type. Stores data to assist in troubleshooting. | Yes |
| Integration Record Mapping | Simple lookup table that ties external record IDs to Aptify IDs. For example, linking the Aptify Person ID to the FMS VendorID record. These records would be generated by the integration process. | Yes |
Note: you may need to add User/Group security to these entities based on your organizational needs.
Integration System
Overview:
This is the primary entity that stores information about your integration. It also contains a subtype called Integration System Attributes that can contain a number of values or attributes specific to each integration.
The Integration System record also has ELVs linking to any Record Mappings, Field Mappings, Integration Logs or Log Types related to this system.
Example:
Setup/Usage:
This record should be setup during your initial implementation or deployment of an integration. The field usage breaks down as such:
| Field | Description |
| Name | The name of the system or company you are integrating with. |
| Integration Category | The classification of the integration, e,g, LMS, FMS, etc. |
| Description | (Optional) Field to add notes about the integration. |
| Status | Field that denotes whether the integration is Active or Inactive. |
| Generates Logs | Bitfield to indicate whether this integration has been setup to generate Integration Logs records. (Strongly encouraged) |
| Date Deployed | The date the integration was setup. |
| Integration Password | The encrypted password to use during the integration process, typically the password the vendor provides you. |
| Integration Password Security Key | The encryption key to use for the Integration Password. |
| Callback Password | (Optional) The encrypted password to use during for integration callbacks. |
| Callback Password Security Key | The encryption key to use for the Callback Password. |
| Object | (Optional) Field to identify the Object Repository Object used by this integration. |
| Assembly Name | (Optional) Field to identify the Assembly name of the Integration object. |
| Class | (Optional) Field to identify the Class name of the Integration object. |
Integration System Attributes
A subtype record that can store general Integration-level attributes. Contains a Name, Value and (Optional) Description field. Can be used as shown below.
Integration Categories
Overview:
This is a simple entity that just stores different categories of Integration. For example, you can setup records for Learning Management Systems (LMS), Third Party Order systems, Third Party Event Registration systems, different Content Management Systems (CMS).
Example:
Setup/Usage:
Simply create a new record for each Category you need to integrate with. You’ll tag your Integration System with the appropriate category.
Integration Logs
Overview:
This is the primary entity that will store transactional records for each time your integration performs an action. It is recommended to build your integration in a way that generates these records as an automated process does not currently exist. This entity can greatly help out with troubleshooting problems with the integration, both during development as well as Production usage.
Typically, an Integration Log is generated for each individual process, for example, pushing a Person records update to the LMS, however, this can also be used for batch processing or integration actions not specific to an individual record.
Example:
Setup/Usage:
These records should be automatically generated by your Integration process. The integration should generate a new record for each “action” with the third party.
These records can be purged on a routine basis to avoid cluttering the database, for example, records more than 60 days old. Alternatively, the JSON/XML in the Request field (and possibly the Response/Exception fields) is likely to take up the most space so it could be scrubbed on a regular basis to avoid database bloat.
The fields break down as such:
| Field | Description |
| Integration System ID | The Integration system that is linked with this process |
| Log Type ID | (Optional) Type of Action or Process that is happening, e,g, CreatePerson, UpdatePerson, CreateOrder, etc. This field only displays Log Types related to the integration system of the Log record. |
| Linked Entity ID | (Optional) If Integration Action/Type is specific to an individual record, the Entity ID of that record. For example, if we are doing a CreatePerson, we would link to the Persons entity. |
| Linked Entity Record ID | (Optional) If Integration Action/Type is specific to an individual record, the Record ID of that record. This can be used to tie Integration Log records (optionally) to different form templates, such as Persons or Products. |
| Status |
Status field containing “New, Pending, Sent, Success, Errored.” Your integration should use this field per the above steps, however, new Status values can be added to the Entity Field. Newly generated Integration Logs can be created as New, with a backend process moving it to Pending on a scheduled basis, or your integration can be setup to automatically set it to Pending. Upon sending the transaction to the third party, it should be updated to Sent, and depending on the results, Success/Failed on the callback. For many integrations where you want the ability to reprocess errors, you can setup your integration process to fire automatically or on a scheduled basis when records have been set to Pending. If you’ve had several actions that errored outed, upon resolving the issue you can then change their status from Error to Pending to reprocess. |
| Record Mapping ID |
(Optional) Field to link the Integration Log to a Record Mapping record, if generating or updating record linkages between systems. |
| Date Generated |
Datetime field to mark when the record was created. |
| Date Sent |
Datetime field to mark when the record was processed and sent to the third party. If reprocessing Errors, should be updated when the Integration re-sends the job. |
| Date Response |
Received Datetime field to mark when the response came back from the third party. If reprocessing Errors, should be updated on subsequent calls. |
| Callback Password Security Key |
The encryption key to use for the Callback Password. |
| Request |
Nvarchar(max) field to store the XML or JSON request that is sent to the vendor. Recording this data is helpful, in case the integration is not working, you can provide the exact request that was sent to see if the data is malformed or in the method the vendor is expecting. Your integration must not record any encrypted sensitive data (e.g. Social Security Number) within this field, instead either omitting the field data or putting a dummy value in its place. |
| Response |
Nvarchar(max) field to store the response from the Integration system. For example, it can store data like “200 OK” for successful calls, or “Bad Gateway/404” if the endpoint cannot be reached, or any vendor-specific response data. |
| Exception |
Nvarchar(max) field to store any Aptify exception logs that result in either sending the data to the Integration System, or in processing the response. |
Integration Log Data
A subtype record that can store individual request data. Can be used differently for each integration, with an example below.
Note: we probably wouldn’t store payload here since it would be saved on Integration Logs under request, but other JSON could be saved here.
Integration Log Types
Overview:
Each Integration Log or action record can be tied to a Log Type. This describes the type of action that is occurring and the Integration System that is doing it. You can setup your integration to leverage this to take functions and attributes out of code and put them in a more easily accessible/modifiable metadata record.
There is an optional subtype with a Name, Value, and Description field similar to the Integration System Attributes subtype.
Example:
Setup/Usage:
This record should be setup during your initial implementation or deployment of an integration. If new functionality is added to the integration, these records can be added later. The field usage breaks down as such:
| Field | Description |
| Name | The name of the Log Type or Action being performed, e,g, PersonCreate, PersonUpdate, SyncOrders, etc |
| Integration System |
The Integration System that this action applies to. Note: the Log Type field on Integration Logs filters to only display/save Integration Log Types that match the Integration System of the Log record. |
Integration Log Type Attribute
There is an optional subtype with a Name, Value, and Description field similar to the Integration System Attributes subtype. This can be used to define specific attributes to the Log Type, for example, PersonUpdate should use a specific StoredProcedure, or should interact in some way different from the PersonCreate Type. These subtypes can be extended or defined however works best for your Integration.
Integration-level attributes should be stored on the Integration System subtype record.
Integration Field Mappings
Overview:
This is an optional entity that can be used by your Integration to define field mapping linkages between Aptify and your Integration System. You can setup your integration to leverage this to take these mappings out of code and put them in a more easily accessible/modifiable metadata record.
Example:
Setup/Usage:
This record should be setup during your initial implementation or deployment of an integration. If your integration is setup accordingly, it can be updated here if any changes are made, thus not requiring changes at the code level. The field usage breaks down as such:
| Field | Description |
| Integration System ID | The Integration system that is linked with this process |
| Entity Name | The name of the Aptify entity that your field is using. For example, if you select a “Name” field and MemberTypes shows up here instead of your intended Product entity, you selected the wrong entity field. |
| Aptify Field ID |
A linked value to Entity Fields. You can select the Aptify entity field for this mapping. Note, on the EntityFields entity, you may want to mark the EntityID field “default in view” so when searching for the Field, you can see which entity it applies to. Stock will display this which makes it hard to identify the right Field ID. |
| Integration Field ID |
(Optional) The Field ID of the mapped field in the Integration System. This field is nvarchar to support systems that may have a mix of letters and numbers in the ID field. |
| Integration Field Name |
The name of the Aptify field in the Integration System. |
| Log Type |
(Optional) The Log Type of Action that this field mapping relates to, for example, you can tie 10 field mappings to the process of updating a Person. |
| Description |
(Optional) A field to put in any notes about the mapping that may help. |
Integration Record Mappings
Overview:
This is an entity that can be used by your Integration to define record mapping linkages between Aptify and your Integration System. For example, what is the ID of Aptify Person ID 247 in the LMS? This can be used for any entity, like mapping Person, Company, Product, Order, or Meeting records.
Use of this entity avoids the need to add integration-specific ID fields to the base table. (e,g, adding FreestoneID to Persons)
Using this flat, simple table as a lookup for your Integration should also assist in performance. It will be quicker to look up the Aptify Person ID using this table as opposed to doing a query that hits either vwPersons or the Persons base table.
Example:
Setup/Usage:
Your integration should be setup to generate these records whenever necessary and use this view/table for lookups.
You can optionally tie specific Integration Log records to a mapping, for example, if a Person record mapping has been created and updated multiple times, each Integration Log would show up on the tab. The field usage breaks down as such:
| Field | Description |
| Integration System ID | The Integration system that is linked with this process |
| Linked Entity ID | The entity that relates to the record being sent over. E,g, product record mappings would display Product. |
| Aptify Record ID | The ID of the Aptify record. For example, if sending over Product ID 257 to create, LinkedEntityID would be the ID of the Products entity, and Aptify Record ID would be 257. |
| Integration Record ID | The ID of the Integration system’s corresponding record, whether generated through a lookup, or if a new one was created. |
| Date Created | The date the record pairing was created. |
| Date Updated | (Optional) The date the record pairing was updated, if applicable. |
| Details | (Optional) Field to outline anything specific about this mapping, or any errors or duplicate records identified. |
Comments
Please sign in to leave a comment.