Sync Configurations
The Sync Configuration wizard enables you to setup and manage synchronizations. Select Setup > Sync > External Sync to view a list of existing Sync Configurations in your knowledgebase. You may create a new configuration, or edit or delete existing ones.
Note that Entity Set sync is also called synchronization. This page focuses on syncing with external systems, whereas entity sets are used to sync between Agiloft KBs.
To create a new configuration, click New. To delete a configuration, select it in the list and click Delete. To edit an existing configuration, click the Edit icon next to the configuration.
The Sync Configuration Wizard creates a record in Agiloft holding:
- The external system to sync with
- The tables to be synchronized and their corresponding structures
- The fields to be synchronized within a Table-Structure pair
- The relations to be synchronized
- The direction for the update to happen between Agiloft and the external system
- The command that launches the ESA
- The identifier fields sync will use to identify matching records
If a Sync Configuration is modified after it has been run, all previous peering of Agiloft records with external system records is lost, and the next run will be an entirely new synchronization.
General Tab
Refer to the table below for each option.
| Configuration Name | Identifies the Sync Configuration name. |
|---|---|
| External System Type | Contains the options to define the type of external system for the current synchronization. The selection determines what other options open in the wizard. In addition, you can select whether to use an HTTPS or Command Line (CL) ESA type, when the ESA type is Third-party Adapter, and to download the esa.jar Remote Proxy. For more information, see HTTPS and Command Line ESA Types. |
| Status | Determines whether the current sync configuration is enabled or disabled. |
| Allow Multi to Multi Table Mapping | Determines whether multiple tables can be synced to one external entity, and vice versa. This feature is only compatible with one-way sync, and selecting it disables the Two-way option under Directions. |
| Sync only explicit records | Determines whether implicit entities are included in the set. If you select this option, only the records you explicitly selected will be synced. If you don't select this option, when you select a record to include, the system will also include some implicit entities that are related to that record, to better ensure the complete record is synced. This might include linked records, choice lists, or various other dependencies. |
| Post Sync Config | If you select a sync configuration here, then when the current sync runs and successfully completes, the selected sync configuration runs automatically. This is useful when using two one-way sync configurations to work around the multi-to-multi table mapping requirements. |
| Directions | Specifies whether the synchronization data updates happen in both directions, or on the side of Agiloft or the external system. The direction chosen here determines which sync operations are available for field mapping. For instance, the Allowed Operations and Update in Agiloft/Update in External options will be disabled if the sync direction does not support them.
|
| Queue Number | If necessary, use this option to set a specific queue priority for the sync configuration. |
| Related tables on explicit records | If you select this option, when the synchronization process starts on a record that was explicitly selected, the system will also sync all related tables that are mapped in Relation Mapping. Note that this does not sync the deletion of linked records. |
| Conflicts | Specifies how the system should handle conflicts during a two-way synchronization when records are edited on both systems. See Conflict Resolution for more information.
|
| Remoting | If the ESA is located on a remote server, this section enables you to download the Remote Proxy and configure the following items:
|
| Personal Synchronization | Enables you to store synchronization data on a per-user basis, which can allow your users to synchronize with their own PIM installations. |
| Secure API Calls | An authorizationkey header is required when setting up or running the sync with an API call. The key given here is the value for that header. |
| External System ID | An ID which uniquely identifies the Sync Configuration being produced is generated by the Sync system and placed in this field. At this point, before the configuration is created, you can edit it to make it more easily memorable - ensuring that it remains unique. A remote HTTPs ESA needs this ID as a parameter, and its developer must ensure that this parameter is received by the ESA. |
| Reset Records Pairing | Once the synchronization has been established, it is possible to reset the record pairing by clicking this button. This will make the next synchronization operate on every field as a first sync. |
ESA Settings Tab
Once the connection has been established with the ESA, the ESA Settings tab opens and allows you to set the directory path and other relevant ESA configuration options. The parameter set is specific to the ESA type, but usually this tab includes the necessary fields to set up a connection to the external system.
After you press Next, the system usually has enough information to connect to the external system. In cases when it does connect to the external system, it might open database connections, make some queries, verify, or provide additional parameters to manage, depending on what it finds. For example, a basic set of parameters might have a host URL and a login and password pair, while an advanced set might include selected tables to synchronize. If the wizard needs to show information extracted from the remote system, the system needs to connect to it first.
Clicking Next opens the Table Mapping tab.
Table Mapping Tab
The Table Mapping tab contains a list of the tables in the current knowledgebase, which can be mapped to structures such as tables or databases in the external system. Select a structure from the drop-down and click the Map button. This establishes the mapping relationship and open the Field Mapping wizard where you can map the individual fields between the tables for synchronization.
Some ESAs may ask for additional parameters after connecting to the external system. To set them, press Back to return to the ESA Settings tab.
Field Mapping Wizard
In the Field Mapping wizard you can define the relations between fields in the Agiloft table and the external structure to which it was mapped. Whenever synchronization happens, these fields are synchronized in the direction specified in the General tab and in this wizard. For more information, see Matching Records with Synchronization.
| Modification Time Field | Usually an Agiloft table has a Date Updated Datetime field. It might have several Datetime fields, and the user can select one of them to hold the modification timestamp. |
|---|---|
| System Update Type | Fields can be synchronized or simply replaced in either system depending on this setting.
|
| Allowed Operations | Any of the sync operations can be prevented or enabled by selecting the check box in this section. |
| ID Generation | Sets whether the ID is set by the external system or Agiloft, and how the ID should be stored. |
| Post Action | Applies the selected action to changed records after a successful sync. |
| Required Field Behavior | Determines whether the sync fails or continues when a mapped required field is empty. |
| Search for related records | Includes records in related tables in sync for this table. |
| Field Mapping | Sets whether fields should be strictly matched during sync and provides a list of all table fields with the related mapping options. Field names in the external structure, provided by the ESA, should be matched with their corresponding field names in the
Agiloft table. |
Filters Tab
The Filters tab enables you to use saved searches to filter the Agiloft or external system records when matching fields, as well as selecting the filtering method to apply. An Agiloft filter prevents filtered records in Agiloft from being synced to the external system, and an External filter prevents filtered records in the external system from being synced to Agiloft.
Relation Mapping Tab
The Relation Mapping tab enables you to set linked field relations with mapped fields.
Fields from the linked sets in the Relation Mapping tab cannot also be used in the Mapping tab, as these define primary relationships between the key tables. For example, Phone Number or Email fields in the Company mapping are part of the linked set between Company and Contact, and they make it impossible to set up a relationships between Company and Contact in the Relation Mapping tab.
It is also possible to use linked fields as normal mapped fields in the Field Mapping Wizard. However, this is less strict, and simply updates the values of the field from the linked field set directly. The Relation Mapping tab takes the entire set of fields as a unit, with both sides of the link being set as relations in the ESA. In this case, if the linked set is required, and a child field cannot be found in one of the systems, the record isn't updated and an error is logged.
Example
Take a Salesforce ESA sync with the following required linked field relations between Salesforce and Agiloft:
- Accounts in Salesforce mapped to Company with the linked set Account ID > ID, Account Name > Company Name, Account Number > Company Number, Website URL > Website URL.
- Opportunity in Salesforce mapped to Opportunity with the linked set Amount > Sale Value, Closed Date > Estimated Close Date Created Date > Date Created, Name > Opportunity Name, Probability(%) > Probability of sale, Stage > Status.
In the Relation Mapping tab, you can set the Account ID mapped to the Company linked field set: Company(Company, Currency, Fax, Company ID, Industry, Main Location ID, Parent Company, Region, Telephone, Website URL). In Salesforce, if you create an Opportunity record without linking it to any Account name, that record is not updated during sync and ends with an error, due to the required linked field between Agiloft and Salesforce.
Running Tab
The Running tab defines how the synchronization process can be initiated:
- Manually, through the Sync option in a Table view.
- As actions, including running sync on a set schedule or when a record is updated.
- At the request of the ESA.
By default, all three triggers are allowed.