Entity Set Sync allows you to transfer a structural portion of your system from one knowledgebase to another. It differs from External System SyncSynchronization, which is used to keep keep

Companyname

and external systems up-to-date with the same records and data, such as integration with Salesforce, Google, or other third-party systems. Entity Set Sync is used to transfer the structure of a KB, such as tables, fields, rules, and actions. A common use of Entity Set Sync is to transfer changes from a development or testing KB to your production system.

The Entity Set Sync wizard is a single screen accessed from the admin Setup menu at Setup > Sync > New > Entity Set. When adding a table to the entity set, 

Companyname

 automatically includes portions of other tables which relate to the construction and function of the initial selection. The system includes the specific fields, saved searches, rules, actions and views that are needed to reproduce the functionality of the initial table. This means that selecting one table for the entity set may pull in tables with linked fields from many other parts of the system.

Using a separate development or testing KB allows for complex or experimental builds without affecting day-to-day use of the system, or unintentionally changing connected Using a separate development or testing KB from your production system allows for complex or experimental builds without affecting day-to-day use of the system, or unintentionally changing connected but unrelated system behavior. Working with multiple environments might look like this:

...

Note
When transferring changes from a development to a production environment, the Source KB is the development KB, and the Target KB is the production KB.

Types of Sync

Sync is either direct or indirect. Direct sync is preferred, but to use it, the source KB and target KB must be on the same server. If the KBs are on different servers, they can still sync, but only through the indirect sync method that uses an intermediary carrier file to transfer the entity set. In indirect sync, t he the carrier file is exported from the source KB and then imported to the target KB.

Use direct or indirect sync to push changes between KBs

Carrier KBs are occasionally used  used to enable special features. If you have a carrier KB file to set up a special feature, skip to the Sync the Entity Set section to import it.

...

If the source KB and target KB for the entity set transfer reside on the same server, you can perform a direct sync. You can export an entity set directly from one KB to another by providing login credentials for the target KB in the Sync wizard. This is the simplest way to perform sync and only requires admin level login credentials for both KBs.

See Direct Sync for detailed instructions.

Indirect Sync

If the source KB and target KB are on different servers, you must perform an indirect sync, also known as "sync via carrier file." Note that Carrier KB files can only be imported into other knowledgebases running the same release version or higher. A carrier KB created on a higher release will not import successfully into an older KB.

In an indirect sync, the entity set is created in the source KB and exported to an XML file, known as the carrier KB file . Download the file and transfer it to the target server. Then, the carrier file is imported into the target KB on the other server.

See Indirect Sync  for  for detailed instructions.

Create an Entity Set

Direct and indirect sync both require an entity set. Start by creating an entity set that contains everything you need to sync.

1. Click the Setup gear in the top-right corner, go to Sync, and select New > Entity Set. 
   Image RemovedNew Entity Setclick Configure under Entity Set.
2. Click New and then click Entity Set or Lightweight Entity Set. Lightweight entity sets are used for sending simple build without including a lot of implicit dependencies, because lightweight sets send only a single level of implicit entities and curtail any beyond that. A standard entity set will populate all implicit dependencies, which makes the sync more complex, but also makes sure pieces of the build aren't missed. If you create a standard entity set, you can always choose to send only explicit entities later.
3. In the wizard, enter a Name for the entity set.
4. Select which entities are included in the set. Available entities include: tables, choice lists, color schemes, pictures/images, groups, teams, attached files, and global variables.
5. Customize the entity set as needed by marking entities as  Explicit  or  entities as Explicit or Implicit, or by or by adding or removing fields, rules, etc. See Customize the Entity Set.   

6. If applicable, select the Transfer Only Explicit Entities checkbox. See Explicit and Implicit Entities.

   Note
   If this option is selected, leave the Update Implicit Linked Fields option selected to prevent broken relationships after sync. This option is used only for advanced troubleshooting.

7. Click Finish to save the entity set.

...

You can choose to send only the explicit entities in your set. This is useful to minimize the size and duration of the sync, but for large changes, it can be difficult to make sure all the necessary entities are sent. If you do choose to send only explicit entities, carefully review any implicit entities that were added to the set and evaluate whether they need to be made explicit and sent as well.

You can also choose a middle ground using a lightweight entity set. These send a single level of implicit dependencies, but no additional levels beyond that. This make sure the bare essentials are included, but might miss some pieces when used to send complex build.

Anchor
CustomizeEntitySet CustomizeEntitySet

Customize the Entity Set

...

Add Tables to the Entity Set

There are three options for adding tables to an entity set:

• Add empty tables.
• Add tables and all fields.
• Add tables and all entities. This option adds all child entities of the table, including fields, saved searches, rules, email templates, inbound email accounts, and other settings. 

Tip
To send a small change with minimal build, add the empty table first and then use Customize to select the relevant table items.

Add Other Entities to a Set

1. Locate the type of entity to be added, such as choice lists, groups, teams, images, etc. When sending groups, add the group explicitly if the intention is to sync the group's permissions. For more information, see the Group Permissions section.
2. Click Add Entities to expand the list of available items. 
3. Select the entities you want, then click Add Entities or Make Explicit to finish adding them to the set. The screen refreshes and additional entities may be added implicitly. 
   Groups list showing the Make Explicit button
   
4. Change the status of previously added entities by clicking Make Explicit or Make Implicit. 

Remove Entities

When an entity is added to the set, the system automatically adds implicit entities that are necessary to reproduce the table structure and functionality. You can review and, if necessary, override these implicit entities by clicking Remove next to an item, or Customize next to a table to add or remove fields, searches, the table layout, and so on.

Be cautious when removing items that were added by the system. It is usually best to keep all items which are automatically added to an entity set. Removing these items may cause an incorrect sync transfer. The system warns the user of any dependencies broken by removing an item. For example:

Image Modified

You can use this warning or the Entity Set Dependency Report to investigate why the unwanted item was originally added, and then potentially remove the causal relationship. To successfully remove an entity from the set and prevent the system from adding it back, you must identify how your selected set relies on the unwanted entity and make changes to resolve that relationship. For example, you might need to remove an action you don't want to send from a rule you do want to send, to prevent the system from sending both.

...

1. Dependent items are automatically added to an entity set.

   Info
   title Example
   If a linked field is added added to an entity set, the system transfers the associated saved search and action, which  which are part of the linked field settings. If an empty table is added to an entity set, the system may add additional tables. Even without custom fields, some tables have a relationship to other tables such as Email, Email Marketing, Team, and People, which the system identifies and adds to the set.

2. Changes to items included in an entity set are refreshed the next time an entity set is opened for edit.

   Info
   title Example
   An entity set includes a linked field based on a saved search. The saved search is later modified or replaced. When the entity set is reopened, the new or modified saved search is included in the set.

This feature is designed is designed to make working with sync easy: just add the key components needed, and the system identifies and includes related and dependent entities.

Anchor
DependencyReport DependencyReport

Entity Set Dependency Report

This feature is used to examine why additional entities have been added automatically or implicitly to an entity set. Once you understand which relationship is causing the system to add the entities, you can determine whether to keep the entity or change or remove the relationship.

To run a dependency report:

1. Go to Setup to Setup > Sync.
2. Select the entity set and click Report entity set dependencies. 

Reports are divided into five tabs:

• Subtypes, or tables
• Columns, or fields
• Teams
• Groups
• Records

The report shows

...

the logical chain between items added to the entity set by users and those that the system adds implicitly due to dependencies. For example:

Sample report of entity set dependencies

...

Use Verify KB to check the overall integrity of both the target KB and the source KB before performing sync. The system reviews linked field schema, actions, tables, and teams, and generates an on-screen report of any issues.

1. Go to Setup > Sync > Verify KB.
2. Allow some time for the report to run.
3. When the report is finished, review it and resolve any issues.
4. Repeat these steps until the KB is verified to have no issues.

From the admin console, you can also perform Linked Field and Schema Repair, which identifies inconsistencies and broken linked fields that may lead to a sync failure.

...

 Hosted customers may contact 

Companyname

 Support to perform LF and Schema repair. 

1. In the admin console, go to Setup > Repair.
2. Select a KB for repair.
3. Click LF and Schema Repair.

Make sure to perform these steps for both the target KB and the source KB.

Anchor
lfauto lfauto

Disable Linked Field Auto-propagation During Sync

Sync has a higher risk of failure with large KBs and entity sets where tables in the target KB contain a lot of records and massive propagation on linked field columns. In this situation, it can be useful to disable linked field auto-propagation during the sync. This can save time and prevent sync failures. If you do disable this feature, make sure to run linked field repairs after sync.

To do this, open the Using the Setup Assistant

...

and navigate to the Application Server section. Enter the

...

following text into the

...

options field:

-Dew.sync.populateAddedColumns.disabled=true

...

Note that this property will survive server upgrades. If you wish to disable the property after sync, just add the following property into the same Jboss options field:

-Dew.sync.populateAddedColumns.disabled=false

Test Sync on a Copy KB

The best way to see what to expect from a sync is to create a copy of the target KB and sync to the copy. This offers you a complete picture of what to expect.

1. Create a copy of the target KB. Note that if the target KB is on a different server, it can be useful to perform these steps twice: once with a copy KB on the same server as the source KB, and once with a copy KB on the same server as the target KB. The more thorough your tests can be, the more likely you are to efficiently resolve any issues in the final sync.

   Tip
   Perform all preparation steps in this section on the copy KB if possible.

2. Test the sync operation using the steps in the sections below. Syncing to a copy KB helps to discover inconsistencies between KBs that must be fixed before syncing to a production KB.
 
3. The KB might contain obsolete actions that should be deleted, such as unused conversion actions with no conversion selected, or broken actions resulting from the removal of a team, group, or saved search. It's important to clean up these objects before performing sync.
4. Check for problems and unique attributes.
 Run
5.  Run the test sync and carefully read error messages to resolve any issues. For example, if
 the Company
6. the Company Name field
 is
7. is designated ‘unique’ in the source KB but not the copy, sync will fail if it finds duplicate entries in records in the copy KB.
8. Resolve issues and take
notes as
9. notes as you go. In the copy KB, investigate and resolve the conflicts, taking careful, detailed notes of each step you take. These notes are the plan for the final sync, and they are critical to making sure everything will work as expected. For more information about conflicts between entities, see UUID Recognition and Sync Conflicts.
10. Repeat these
steps to
11. steps to test your plan in a new copy of the target KB. After sync, follow the plan exactly, and then review and test the result to make sure the KB works as expected and data appears appropriately. If anything is found in the KB that does not meet expectations, investigate, plan, and test a solution. Add that solution to the plan for the final sync.

Many test syncs may be needed before everything is ready for the final sync. Thorough preparation is essential to making sure the target KB is in good condition after the final sync.

Schedule the Final Sync

Treat a sync, especially a large sync, like a server upgrade. Secure a generous time window outside business hours, so you have time to complete the sync, resolve conflicts, and run basic checks. Make sure to back up the target KB shortly before the final sync.

If possible, it is helpful to:

• Stop background services and emails from the KB, which can cause sync failure
• Log users out to prevent anyone from modifying a record being synced
• Disable linked field propagation for sync with very large KBs
• Perform the sync with a user account that won't be needed for anything else during the scheduled window
• Perform the sync on a computer with consistent network connectivity

Anchor
SyncEntitySet SyncEntitySet

Sync the Entity Set

...

You do not need to complete both sets of steps below. There  There is no functional difference between the two. You can perform direct sync from either KB. Choose one set of steps to follow. 

To run a direct sync from the source KB:

1. Log into the source KB as an admin.
2. Go to Setup > Sync.
3. Select the entity set.
4. Click Export to open the Sync Export wizard.
5. On the Source tab, select Transfer to existing KB.
6. The drop-down list shows all knowledgebases on the same server. Select the name of the target KB.
7. Enter admin-level login credentials for the selected target KB.

8. Click Export Now to begin exporting changes. It may take several minutes to transfer changes depending on the size and number of entities in the set. You may not log out of the KB while sync is working.

Anchor
IndirectSync IndirectSync

Indirect Sync

Indirect sync is used between KBs on different servers. Given a choice, direct sync is preferred. Indirect sync is more complex because it involves creating, transferring, and importing a separate carrier KB file.

Anchor
Creatingexportingcarrierkbfile Creatingexportingcarrierkbfile

Create and Export a Carrier KB File (Indirect Sync)

If the source KB and target KB are on different servers, a carrier KB file is used to transfer the entity set. Follow these instructions to create a carrier KB file using the sync export wizard.

1. Log in to the source KB as an admin.
2. Go to Setup > Sync.
3. Select the relevant entity set, then click Export to open the Sync Export wizard.
4. In the wizard, select select Create export file.
5. Click Export Now.
6. Leave the progress the progress window open; it may take a few minutes to create the file. Once completed, a confirmation message with an option to  option to download the export file  and and to view a transfer report appears. 
   Image Modified
7. Save the file locally and note its location.

Anchor
Importingstructuresfromcarrierkb Importingstructuresfromcarrierkb

Import from a Carrier KB File (Indirect Sync)

...

Info
title Example
For example, the following file contains the entities for the 2017 default Look and Feel:   2017_default_look_and_feel_for_power_and_end_user.xml.ew  After the file has been imported, Setup > Look and Feel > Manage Power Schemes shows an L&F named "2017 Calibri Default" and Setup > Look and Feel > Manage End User Schemes shows an L&F named "2017 Calibri Default EUI."

Monitor Sync Progress

 Check Check the status of the sync process from the Sync Status page. Go to Setup > Sync and click Sync Status to see all active sync processes. When a process is complete, it disappears from the list.

...

In case of sync failure, see Troubleshooting with Error Logs.

Compare KBs

The Compare  feature The Compare feature generates a report of differences between two selected KBs based on a selected entity set.   Compare  Compare is only available for two KBs hosted on the same server.   The Compare feature is available from both the power user interface and the admin console. 

Users typically compare KBs in the following cases:

1. Transferring changes from a development to a production environment. Use  Compare  in this case  Use Compare in this case to discover any changes in the KB, what these changes are, and whether sync is necessary. For more information about environment management, see Managing Multiple Environments.
2. Checking the results of a just-performed sync. After  After a full development-to-production sync, use  Compare  to check use Compare to check that the comparison report is empty and verify that all items were transferred correctly. 
3. Comparing two completely different KBs to reveal how many differences they have. For example, you can see how far two systems are from each other, and get a sense of how much cleanup would be needed to perform a successful sync operation between them. 

Comparing whole KBs from the admin console

1. Log in to the Admin Console and go to Setup to Setup > Debugging > Compare KBs.
2. Select the source and target KBs you want to compare.
3. The system will generate a report in .xls format xls format listing the differences and sorting by item type. 

Comparing partial KBs (entity sets) from the admin interface

1. Log in to the Power User Interface as an admin user. 
2. Go to Setup > Sync, select an entity set, and click Compare.
3. You will be prompted to select a second KB for comparison. 
4. Here you can compare only the items of interest in the entity set. 
5. You can download or open the system-generated report in .xls formatxls format. 

Anchor
fixLF fixLF

Repair Linked Fields

If you disabled linked field auto-propagation before performing sync, use the LF Propagation Check utility to repair any linked field issues caused by the sync.

1. Log in to the Admin Console and go to Setup > Repair. 
2. Select a KB.
3. Click LF Propagation Check.
4. In the report, review the flagged fields in each table. You can click the red hyperlink to see a list of the affected records.
5. Repair individual linked fields with Repair LF, or use Repair All LFs to repair all the linked fields in a given table. Using a repair option generates a report with details on what was changed.

If you disabled linked field auto-propagation, you  you might also need to enable it before the next sync. For details, see here.

Entity Sync Limitations

The following sections describe the known limitations of sync.

Deletion

In general, sync does not support deleting objects in a target KB.

Info
title Example
An object is included in an entity set and synced to a target KB. The item is later deleted in the source KB and entity set. When you run sync again, the object will not be deleted in the target KB. Instead, its status will be marked 'Free' in the transfer report. Thus, 'Free' items are objects not found in the source KB due to deletion.

...

Even when group permissions are transferred, only a direct sync of explicitly listed groups syncs all the permissions in the group. Indirect sync only transfers permissions for entities that are included in the entity set. For example, let's say group A in the source KB has access to tables B, C, and D, and group A is added explicitly to your entity set. Table B is also added explicitly, and table C is added implicitly, but table D is not included at all. If a direct sync is performed with this entity set, group A is synced to the target KB with access to tables B, C, and D, even though table D is not included in the set. However, an indirect sync is performed with this entity set, group A is synced to the target KB with access to tables B and C, but the permission to access table D is not synced. This applies to permissions at all levels.

Groups can automatically be added to an entity set depending on the table and field dependencies.   If the number of user groups is large, we recommend performing an entity set sync with all components (tables, fields, related items)   except  except groups. Permissions can be transferred afterwards in a separate direct sync action.

If an entity set contains some (or all) groups selected for sync, all permissions for previously synchronized tables are correctly transferred for each group.

Indirect sync can update permissions only for the entities included in the set, even if all groups are selected for sync. In contrast, if you use direct sync to update all groups, the sync updates permissions for all entities, even if they aren't included in the set. 

Layout Transfer

Sync does not support renaming layout tabs because layout tabs have no universally unique identifiers (UUIDs). If a tab is renamed in the source KB and then synced, the corresponding table in the target KB has two tabs: an empty tab with the previous name, and a tab with the new name holding the corresponding fields.

...

The entity set sync logs, primarily sync.log, is found at <Installation_directory>/jbosswildfly/serverstandalone/sw/log/sync.log.

In some cases sync issues can be found by other

Companyname

activities, so it could be helpful to use the server.log files at <Installation_directory>/jbosswildfly/server/swstandalone/log/server.log.

Note
Sync is sensitive to concurrent database level operations. Please avoid running a KB import/export/deletion or concurrent syncs on the same server while attempting to import an entity set.

...

• If the log entries do not have any specific information on what caused the issue, check the server.log entries at the same time for any other critical errors not related directly to the sync process.

• If the server log entries have information about an entity, check the sync log entries for occurrences of errors by the UUID or name of the entity. It is possible that some other error occurred earlier which is the real cause of the issue. For more information, see UUID Recognition and Sync Conflicts.

  Note
  Server logs contain entries with different levels of priority (debug, info, warn, or errors). In most cases, you should look at the log entries with WARN/ERROR priority levels.

If you need further technical assistance, is needed, contact the

Companyname

support team by submitting a ticket with the attached sync.log and server.log files: Get Support.

...