Page tree

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 NameIdentifies 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.

StatusDetermines whether the current sync configuration is enabled or disabled.
Allow Multi to Multi Table MappingDetermines 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 ConfigIf 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.

  • Two-way sync: Allows mapping between objects in both directions - from  Agiloft to the external system, and the other way around. Records of the mapped tables synchronize in both systems. This option is disabled if you select Allow Multi to Multi Table Mapping.
  • Update Agiloft only: This one-way option allows records to be updated in Agiloft with values from the external system.
  • Update External System only: This one-way option allows records to be updated in the external system with values from Agiloft.
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.

  • This system should take precedence: If both records have been changed to different values, the Agiloft record is updated.
  • This system should take precedence: If both records have been changed to different values, the Agiloft record is updated.
  • Take the most recent record: If both records have been changed since the last sync to different values, the most recently modified record is updated.
  • Duplicate records: The system creates a duplicate of each record with both external system and Agiloft values.
Remoting

If the ESA is located on a remote server, this section enables you to download the Remote Proxy and configure the following items:

  • Polling Period - When an ESA is run remotely, it is presumed that it is behind the firewall. So, ESA should eventually come to  Agiloft and ask whether there are synchronizations pending. The Polling period setting determines how long the ESA will wait between such requests, in seconds.
  • IP Filter (optional) - If an IP Address is entered here, ESA or Remote Proxy connections will be accepted by the Sync Configuration concerned only from that IP. In the case of NAT, this must be the outermost IP of the ESA machine, as seen by  Agiloft.
Personal SynchronizationEnables you to store synchronization data on a per-user basis, which can allow your users to synchronize with their own PIM installations.
Secure API CallsAn 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 PairingOnce 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.

  • Synchronize: Synchronize the fields in both systems.
  • Export: Update the fields in the external system.
  • Import: Update the fields in  Agiloft.
Allowed OperationsAny 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 ActionApplies the selected action to changed records after a successful sync.
Required Field BehaviorDetermines whether the sync fails or continues when a mapped required field is empty.
Search for related recordsIncludes 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.

Relation Mapping screen

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.