Sync Filter

Tip	This article introduces the concepts and basic functions of the Sync Filter. To jump into action, check out also the Sync Filter examples in FetchXML format.

Synchronization filters define what data from the server is replicated in the Resco Mobile CRM application after a synchronization. Filters are defined in Woodford; each entity for each app project can have custom settings.

Editing the sync filter

1. Edit an app project.
2. Select an entity from the Project menu > Entities.
3. Click Show Fields to display the list of entity fields.
4. Click Sync Filter. The conditions are defined using the generic Filter editor user interface.

Editing the sync filter as XML

Internally, the sync filters for all entities are saved into a single file, SyncFilter.xml. If you prefer to edit the sync filter directly as XML, you have two options.

Per-entity editing

1. Edit the sync filter for an entity as described in the previous section.
2. Click Export XML to download the sync filter for the entity as an XML file.
3. Edit the file in your favorite editor, perform any changes as needed.
4. Return to Woodford and upload the modified XML file using the Import XML button.
5. Save all changes.

Editing the entire SyncFilter.xml

1. On the list of all your app projects in Woodford, select a project and click Export to download the entire project.
2. Change the extension of the downloaded file from "woodford" to "zip".
3. Extract the file SyncFilter.xml from the Configuration folder and modify it as needed.
4. Add the modified file back to the archive.
5. Change the extension back to "woodford" and import the file to Woodford.

Warning

If you want to upload a modified version of the app project back into Woodford, always keep a backup copy of the original file.

Why use XML

Some Woodford administrators prefer editing the filter in XML format because they are familiar with the used FetchXML format. See Analyzing SyncFilter.xml below for more information.

Additionally, there's also a rare scenario where the Woodford filter editor user interface does not allow you to be as exact in your sync filter as you need: some SQL server optimization options for Dynamics can only be edited in XML format.

Introduction

There are two types of synchronization: initial (full) synchronization, and incremental synchronization.

• Full synchronization is performed for example when the mobile app is used for the first time. In these cases, apps download data from the CRM server depending on the sync filter, so the sync filter is used to define what data is being downloaded to the Mobile CRM app's local database.

• In case of an incremental synchronization, the app downloads all records (that the user has permission for) that were created or updated since the last synchronization. Subsequently, the sync filters are used to only keep the records that follow the sync filters in the local database.

When setting up a Sync Filter, a condition can be defined for the CRM database entities (rows) which will be synced to your mobile device. Please keep in mind the capacity of mobile devices.

Example

In this example, we set up a Sync Filter for opportunities that were created within the last 120 days.

1. Edit an app project in Woodford.
2. Select the entity Opportunity from the Project menu.
3. Click Sync Filter.
4. Define the filter:
   • Click Add condition. A default condition is created for Actual Close Date, which is the first field of the entity, with the default operator Contains Data.
   • Click the field and select Created On from the dropdown menu.
   • Click the operator and select Last X Days from the dropdown menu.
   • Enter the number: 120.
     
5. Click Save & Close.

Incremental linked sync filters

Incremental linked sync filter ensures that linked filters on entities are checked during incremental synchronization. Without enabling it, the only initial filter for downloading records from server is the one checking whether the entity records were changed since last synchronization.

This feature can be enabled per entity; see Managing entities for instructions.

The use case for this filter is best shown on an example:

• The owner of an existing account is changed to the current user of the application, while the sync filters are set to only allow user-owned account to be stored in the offline database.
• As a result, the changed account record is downloaded (based on the incremental synchronization definition from previous section).
• But what if the account has associated records, which are not downloaded as they were not changed on the CRM?

Incremental linked sync filter in practice:

For a more detailed discussion, see Linked sync filters.

Example with linked sync filter disabled

Use case: Owner of an existing account is changed to the current user of the application.

Account: the initial filter checks, whether there were some accounts changed since last synchronization. One account record was changed. This account record is downloaded to local database. After this step, the sync filter on account entity (checking whether account owner is the current user) applies to the currently downloaded record. It matches the filter and is kept in local database.

Contact: the initial filter checks, whether there were some contacts changed since last synchronization. No contact records were changed on CRM side. No contact records are downloaded to local database. But what if the account, now belonging to the current user, has contacts which may not be part of local database? It could happen, that some contacts were not downloaded, because they weren’t changed on server side since last synchronization and linked sync filter on contact entity isn’t checked during default Incremental Synchronization.

Example with linked sync filter enabled

Use case: Owner of an existing account is changed to the current user of the application.

Account: The initial filter checks, whether there were some accounts changed since last synchronization. One account record was changed. This account record is downloaded to local database. After this step, the sync filter on account entity (checking whether account owner is the current user) applies to the currently downloaded record. It fits the filter and is kept in local database.

Contact: The initial filter checks, whether there were some contacts changed since last synchronization. No contact records were changed on CRM side; however, we have incremental linked sync filter enabled for contact entity which results in checking linked filters as well.

Based on this linked filter, all contacts that have our downloaded account record set as parent record are downloaded into local database as well. In this moment, only those are kept, which have their parent account owner set to current user – linked filter’s conditions are completely fulfilled. It is certain that all related contacts are part of local database as well, even they were not changed since last synchronization.

Which entities should use linked sync filter?

Incremental linked sync filter should be enabled for the child entity – the entity, which has linked filter conditions stated in its Sync Filter.

If you use CRM server version 2013 SP1 or later, you can use the advantage of the linked filters, that will work not only on initial/full synchronization, but also on incremental synchronization. If not, from the incremental synchronization definition, only records, that are changed will be included.

Use sync filter in online mode

If you want to ensure the same data in the application in online and offline mode, you can force using the sync filter also in online mode. This can be configured for each mobile view; edit the properties of your view and enable Sync Filter - Use Sync Filter in Online Mode.

Mark as Parent Pointer

You can enable the parameter Mark as Parent Pointer in the properties of a lookup field to ensure that both parent and child records are available. However, this setting is only effective if the lookup has only a single lookup target (also displayed on the properties pane for entity fields). When you use this option, the sync filter of the parent entity is also used for synchronization (application uses this flag and runs the parent sync filter in the code, parent sync filter will not be copied to the child entity sync filter). See Sync Filter examples with child entities for a more detailed explanation.

Analyzing SyncFilter.xml

When you synchronize your device with an app project, the sync filters for all entities are saved in one file, SyncFilter.xml. In the case of Windows apps, you can easily find this file on your file system; see finding physical files. If you're in charge of troubleshooting sync filter issues, it may make your life easier if you can read and understand the file SyncFilter.xml directly, instead of relying on the Woodford representation.

For example, your sync filter file may start with the Account entity:

<fetchcollection>
  <fetch version="1.0">
    <entity name="account">
      <filter type="and">
        <condition attribute="statuscode" operator="ne" value="2"/>
        <condition attribute="ownerid" operator="eq-userid"/>
      </filter>
    </entity>
  </fetch>
  ...
</fetchcollection>

This corresponds to the following sync filter:

The filter criteria are saved using the FetchXML query language.

If you are already familiar with FetchXML, you can explore additional examples for inspiration.

See also

• Third-party Sync Filter guide