There are two types of synchronization events for any Cartegraph and Esri integration: initial sync and background sync.
When a GIS feature class and Cartegraph recordset are integrated, the map engine works to maintain consistency between these data sets. Each GIS feature matches one Cartegraph record. Their geometry/location matches, along with all attributes/fields that were mapped in Cartegraph GIS Integration. For example, if a Cartegraph user adds a record with a location, the map engine adds a matching GIS feature with the same shape, Cartegraph ID, and integrated attributes. Deleting the record deletes the feature.
There are two integration types: One-Way and Two-Way. In a one-way integration, Cartegraph is the system of record. Any changes made to geo-integrated fields in the ArcGIS feature will be ignored and overwritten by the Cartegraph value during the next sync. The Tasks and Work Orders recordsets participate in one-way integrations; all other recordsets participate in two-way integrations. In two-way integrations, sync changes in Cartegraph and ArcGIS are reconciled as detailed below so that the result is two identical records in both systems (in regards to the geo-integrated fields and shape).
Two-way integrations may contain fields flagged as a "Cartegraph Locked Value". Cartegraph Locked Value fields are indicated by a lock icon in the Field Associations section. Locked fields in a two-way integration always have the Cartegraph value as the value of record. Any GIS modifications to these associated fields will be overwritten with the Cartegraph value. These fields do not change the overall functionality of a Two-Way sync, however there are some exceptions to how the individual field is handled as documented below.
The sync behaves the same for one-way and two-way integrations unless otherwise noted below.
- An initial sync is initiated any time an active GIS Association is saved. This happens whether the save is after editing an existing association or initially creating an association.
- The initial sync first performs a system Code Generation. This is the same as when the Publish option is run from Cartegraph Structure Manager. All users must be out of the system.
- Two-Way integration: For all ArcGIS features without a corresponding Cartegraph record, a new Cartegraph record is created and the spatial data and all integrated attributes are copied to the new record. One-way integration: ArcGIS features without a corresponding Cartegraph record are deleted.
- For all Cartegraph records without a corresponding feature in ArcGIS with coordinates, a new feature is added to the feature class and all mapped fields are populated by Cartegraph.
- Two-way integration: For records that exist in both Cartegraph and Esri, the sync overwrites any null data on either side if the opposite side has non-null data. If both data sources have data for a particular field/attribute, ArcGIS wins. One-way integration; All data from Cartegraph is copied to the ArcGIS feature class, regardless of null or non-null values.
- The system disregards any records stored in the Cartegraph database with a non-null value for the Retired Date field. This indicates the record is retired. Retired records never sync between Cartegraph and Esri.
- Two-way integration: For any feature class attributes associated to a Cartegraph library through an enforced lookup, the system auto-adds any missing library entries. One-way integration: The geo-attribute value will always be overwritten with the Cartegraph value, therefore there are no missing library values for enforced lookups.
- If a feature class attribute is from domain or subtype, ensure this is mapped to a Cartegraph library. The sync erases the library’s contents and populates it with the domain/subtype values. It is recommended not to use domains or subtypes with one-way integrations. Library contents and meta data are still manipulated in Cartegraph when implementing a one-way integration.
- Two-way integrations; Errors during the sync, or canceling the sync, cause the system to perform a roll back: All changes to the Cartegraph database and the feature class, and all changes made in the field associations grid. This applies only to the initial sync. One-way integration: If there are errors during the sync the system will not roll back any changes. The errors can be reviewed in the sync log and once corrected, a sync can be initiated again from the action menu.
- Exception: If new Cartegraph structure was added in the field associations grid like new fields or libraries, that structure exists after a failed or canceled sync.
- Complex geometries such as linear features with breaks, region polygons, and polygons with holes are supported in synchronization, but the geometry is not editable in Cartegraph.
Normally, when Cartegraph or ArcMap users edit integrated data, Cartegraph and the Cartegraph ArcMap Add-in automatically keep the Cartegraph database and geodatabase in sync.
There are circumstances when this not the case:
- If you edit data in Cartegraph and the ArcGIS server is down.
- If you edit GIS data in ArcMap without the Cartegraph Add-in installed or the Cartegraph server is down.
- If the credentials configured in the Cartegraph Add-in do not have the necessary permission to change the Cartegraph data.
- If you edit a geodatabase version other than the one that is integrated, then reconcile that with the Cartegraph integrated version.
To handle these situations, a regularly scheduled background synchronization checks for changes on both sides and reconciles any discrepancies. In a two-way integration, the discrepancies are reconciled. In a one-way integration, any records found to be out of sync will be brought back into sync by setting the Cartegraph data in the ArcGIS feature or deleting or adding ArcGIS features.
The background sync can be triggered three ways:
- Use Windows Task Scheduler to schedule the Cartegraph GIS Synchronizer. The sync runs in the background whenever it is scheduled to do so.
- In the Cartegraph GIS Integration page, select Synchronize from the Actions Menu from either the Association detail page or after selecting an association from the Associations grid on the GIS Integration index page.
- In Windows Task Scheduler, select Run on the Cartegraph GIS Synchronizer task to manually run the sync.
Initial sync logic is enforced with background syncs as well, unless otherwise noted as an exception.
- Background Syncs occur:
- When initiated by an established reoccurring schedule
- When an edit event occurs in Cartegraph
- When the Synchronize action is selected from the Actions menu in GIS Integration.
- When records exist in both Cartegraph and Esri, the system checks timestamp information to see if the feature class was edited since the last successful sync. If so, and in a Two-Way sync, all associated feature class fields are copied over the Cartegraph record. If not the Cartegraph record was edited most recently or this is a One-Way sync, the Cartegraph fields are copied to the feature. In the situation where the recordset is a Two-Way sync, but some of the fields are One-Way, the timestamp is still used to determine which values are copied from one to the other for the Two-Way fields, however the One-Way fields are also replaced in the ArcGIS feature with the values from Cartegraph.
- In a Two-Way sync, when an edited Cartegraph record is saved, if a matching feature exists and its timestamp shows it was edited in ArcGIS after the last sync with Cartegraph, the map engine copies the feature attributes to the Cartegraph record for any fields that are not dirty in Cartegraph. The map engine then copies the dirty Cartegraph fields to the feature. If there are any One-Way fields in the Two-Way sync, those values are also copied back to the ArcGIS feature. If the recordset is a One-Way sync, when edits are made in Cartegraph, those changes are sent to ArcGIS. If edits were made in ArcGIS, those changes are not sent to Cartegraph and the edits made in ArcGIS will be overwritten.
- The system checks for duplicate Cartegraph IDs in the feature class. If any are found, a split occurred in ArcGIS is implied. In a two-way sync, if the corresponding Cartegraph record exists, the system duplicates it for each feature class feature, auto-assigning a new unique Cartegraph ID in both data sources for the newly added records. If there is no matching Cartegraph record to duplicate, the map engine adds new records instead.
- If new Cartegraph records are created, they are created with the Duplicate method, which does not copy over child data.
- In a Two-Way sync, the system retires Cartegraph records with no corresponding feature in the respective feature class. This only occurs for records that were successfully synced in the past, implying their matching features in ArcGIS used to exist and most likely have been deleted. The system sets the retire date to the date of the sync event. In a One-Way sync, Cartegraph records with no corresponding feature in the respective feature class are added to the ArcGIS feature class, even if the records were deleted in ArcGIS.
- If the Cartegraph record was retired before an edit, and is still retired after, no sync takes place for this record.
- If the Cartegraph record has no geometry, the map engine deletes any matching feature. This only occurs after the initial synchronization.
- In a two-way sync, during an edit to a record in Cartegraph, and the matching feature in ArcGIS was deleted since the last sync, then the retire date is set during save, retiring the Cartegraph record and preventing future syncs for that record. In a one-way sync, the feature is added to ArcGIS.
- If the ID is edited in Cartegraph, on save any corresponding feature also has its associated field changed to match, even if the record is retired.
- When a Cartegraph record is added, if it has geometry, the map engine adds a matching feature. If it has no geometry, no feature is added.
- When adding or editing a Cartegraph record, if the user enters data in a mapped field that is incompatible with the matching GIS attribute, Cartegraph displays an error and disallows the save.
- In a two-way sync, if feature class records are encountered without Cartegraph IDs, the sync assumes the records were added in ArcGIS and automatically adds matching Cartegraph records. It auto-assigns Cartegraph IDs and saves them in both Cartegraph and ArcGIS. In a one-way sync, a feature calss record without a Cartegraph ID is deleted.
This requires that ArcGIS users must not edit or null out the Cartegraph ID field or synchronizations are undefined.
- When a Cartegraph record lacking geometry is edited in Cartegraph, the system does not add a record to ArcGIS. However if there is a corresponding ArcGIS record, the geometry can updated in ArcGIS and the system copies the geometry to Cartegraph at the next sync. For a One-Way sync, the geometry must be entered in Cartegraph. Any geometry data entered in ArcGIS will be ignored.
- Deleting a Cartegraph record warns the user the feature will be deleted in ArcGIS. Click Continue to delete the feature class record and Cartegraph record.
This dialog box displays an overview of information about the status of the synchronization. The dialog box displays after starting a synchronization. Information displayed includes the following:
Displays the GIS Feature Class Layer and Cartegraph Recordset being synced. In a One-Way sync there is a single arrow indicating that the sync is One-Way, from Cartegraph to ArcGIS. In a Two-Way sync, a double headed arrow is displayed indicating the sync of data is reconciled between Cartegraph and ArcGIS. For the Task synchronization, if full geometry is used (synchronizing not only the Tasks, but the geometry of the polygon and linear tasks), this message will also indicate which of the three feature classes are being synchronized.
Displays the current progress of the synchronization process. The possible run status values are: In Progress, Complete, Canceled, Failed. For the Task synchronization if full geometry is used (synchronizing not only the Tasks, but the geometry of the polygon and linear tasks), the status bar will fill three times, once for each of the three associated feature class.
Date and time the current synchronization process started for the last synced feature class.
Date and time the current synchronization process ended for the last synced feature class.
GIS Records to Process
Total number of GIS records to process, this indicator counts down as records are processed for each feature class.
Cartegraph Records to Process
Total number of Cartegraph records to process, this indicator counts down as records are processed for each feature class.
Records In Sync
Total number of records that are already in sync. During an initial sync this has a value of NA. For the Task synchronization if full geometry is used, this number represents the cumulative total of all three synced feature classes.
Total number of records that have been updated during the current sync process. For the Task synchronization if full geometry is used, this number represents the cumulative total of all three synced feature classes.
Total number of records that have been added during the current sync. This is aggregation of the records that have been added to either the Feature Class Layer or Cartegraph. For the Task synchronization if full geometry is used, this number represents the cumulative total of all three synced feature classes.
Total number of records that are not synced. For the Task synchronization if full geometry is used, this number represents the cumulative total of all three synced feature classes. Review the Log for more information.
Total number of records that could not be synced. More information about the failed records can be found in the Log File. For a Two-Way sync, if there is a failure during an initial sync, any data changes are rolled back. For a One-Way sync, changes are not rolled back if failures are encountered. For the Task synchronization, if full geometry is used, this number represents the cumulative total of all three synced feature classes.
The dialog also provides buttons to download the synchronization log file and cancel the sync.
The Log gives more information about the results of the sync, and it is suggested to review it each time, especially if there are any records skipped or any failures. For the Task synchronization, if full geometry is used, this log is cumulative for the synchronization process of all three feature classes.
Cancel a Sync
Canceling a sync should be done with caution. Here are some things to be aware of if a cancel is necessary:
- For a Two-Way sync, all data changes are rolled back (for a One-Way sync the changes are not rolled back.), but any structure created during the Publish will still exist in the system.
- The association is saved, so if any updates or edits are made to the Cartegraph Recordset or Feature Class Layer moving forward, they sync together.
- It is suggested to mark this association as Inactive if you are not ready for the association to work.
- For a Two-Way sync, if the AutoNumber property of the Cartegraph ID field is enabled, review this property in Structure Manager. This might have increased during the sync process, and reset it.