Skip to main content
Version: 3.5.2

Process

Summary#

agosense.symphony one supports a standard synchronization flow. In that flow we assume, that exactly two systems are involved in the synchronization. The first system is considered to be the Source system and the second system is considered to be the Target system.

In the first phase, the process executes a query on the Source system to identify all Source Objects that needs to be synchronized.

In the second phase all details of the Source Object are retrieved from the Source system, including:

  • Attributes
  • Attachments
  • Comments

For any Source Object that is new to the synchronization, the flow will create a new Target Object in the Target system. The Mapping is used to translate the Source Object attributes into the Target Object attributes used for the creation.

For any Target Object that is new to the synchronization, the flow will create a new Source Object in the Source system in case the Create Target option is selected for the sync.

A subset of the Mapping is used to translate the Target Object attributes into the Source Object attributes. All mapping rules with direction Both or direction To source are applied for the Source Object creation.

When identifying a known Source Object, the flow loads all details about the the corresponding Target Object. Through its internal checksum mechanism, the synchronization then identifies each attribute on the Source and on the Target side that has changed compared to the last synchronization. The Mapping is applied for changed Source Objectattributes to calculate the Target Object update and the other way round.

The third phase synchronizes the attachments from the Source Object to the Target Object and the other way round. Any attachment that is new to the synchronization triggers the creation of a new attachment on the other side. The internal checksum mechanism will also identify attachment modifications and trigger corresponding attachment updates. Problems during the attachment synchronization will be recorded as Warnings, the synchronization of the object will not be aborted. Disable the Transfer Attachments option for the sync to prevent any attachment synchronization.

note

Not all systems do support attachment updates. In case an attachment update is triggered but not supported, a Warning is recorded including all attachment details, so that a manual procedure can be applied in such case. This will not abort the synchronization.

Phase number four synchronizes the comments in both directions. Currently, the flow checks for new comments and and synchronizes them to the corresponding object on the opposite side. The content of the comment is normalized to plain text during the synchronization. Disable the Transfer Comments option for the sync to prevent any comment synchronization.

This standard synchronization flow can be customized using Extensions.

Options#

OptionDescription
Create TargetEnable this so that the sync creates corresponding source objects for newly detected target objects
Transfer AttachmentsDisable this to prevent any attachment synchronization
Transfer CommentsDisable this to prevent any comment synchronization

Mapping#

The mapping is a set of attribute mapping rules. Each attribute mapping rule defines a Source Attribute and a Target Attribute. This attribute name translation rule is bi-directional.

For each attribute mapping rule a Direction needs to be defined, valid Directions are:

  • To Source
  • To Target
  • Both

The To Source directions defines, that the attribute is only synchronized from Target Object to Source Object, the To Target direction defines the reverse behavior. In case the Both direction is applied, the synchronization of the attribute will be executed in both direction.

Using the Both direction implies the risk of a conflict, in case the synchronization detects an attribute change in the Source Object and the Target Object at the same time. This is why the rule has a Conflict behavior configuration.

Valid Conflict behaviors are:

  • Source Wins
  • Target Wins
  • Error

If selecting Source Wins, the flow will overwrite the Target Object with the Source Object value in case a conflict is detected. The reverse behavior is applied in the Target Wins case. If you select Error, the synchronization of the object is aborted in case of a conflict. A Conflict failure record is made available in the process panel then.

The flow categorizes the attributes into the following types:

  • Boolean
  • Date
  • Date/Time
  • Double
  • Identity
  • Integer
  • List
  • Markup
  • String

When defining attribute mapping rules, you can always use Source Attribute and Target Attribute of the same type. Underlying values are normalized and thus do not require any specific translation.

If you define an attribute mapping for List type attributes, you can also define a list of value mapping rules. This will allow you to translate the choices between Source and Target, you can simply select from the possible choices on each side.

If you choose To Source direction, you can also define a String and Markup type Source Attribute independent of the Target Attribute type. The mapping will automatically convert the value into a text. The same applies in the reverse direction. This automatic conversion is of course NOT applicable for the Both direction.

For each attribute mapping rule, you can also select None as the Source Attribute OR the Target Attribute. In that case, you will have to define a default value for the opposite side. This is intended for mandatory attributes where the opposite system does not have a corresponding meaningful attribute. This behavior is currently not available for Boolean, Date and Date/Time type attributes.

Scheduler#

The scheduler can be used in order to plan the automatic execution of the synchronization. Make sure to configure the rules and activate the scheduler.

Once the Active column shows a checkmark, the synchronization will be executed according to the configured rules.

Failures#

If the synchronization experiences a problem it will record a failure and present it in the process panel.

Depending on the problem itself, the failure record will expose the complete context including:

  • Name of the synchronization
  • Name of the Source adapter
  • URL of the Source system
  • Identifier of the Source Object
  • Name of the Target adapter
  • URL of the Target system
  • Identifier of the Target Object

Error#

Errors are problems of unexpected nature, such as errors reported by the Source or the Target system.

The Error records will contain the complete list of all error messages from all components involved into the problem as well as a complete stacktrace.

The records will also contain indivdual context information depending on the phase in which they occur:

  • Comment
  • Create
  • Get
  • Query
  • Update

Trigger a Full Sync after the underlying issue is resolved or to check if the error still persists.

Warning#

There are currently two types of warnings:

  • Attachment
  • Extension

An attachment warning is recorded any time an attachment synchronization fails due to:

  • Network issues
  • Extremely large size attachments
  • Unsupported attachment updates

For some of this cases, like the network issues, the problem very often resolves itself on the next synchronization.

Other cases require a manual resolution. Trigger a Full Sync after you have resolved the issue.

Conflict#

A Conflict is recorded any time, that an object cannot be synchronized due to conflicting changes on the Source and the Target object based on the Mapping. The record will expose the exact names of the attribute(s) that where causing the conflict.

In that case, it is expected, that the conflict is manually resolved in the Source and the Target system, based on the details provided.

Trigger a Full Sync after to conflict resolution to include the object again into the synchronization.

Full Sync#

You can trigger a full synchronization from the process panel by hiting the Run button. This will reset the failure records for the corresponding synchronization and bypass the usual timestamp and failure based query optimizations.

Once the full synchronization has finalized, you will have a clear status in terms of remaining failures that require resolution.