Filtering By Inclusion Using a Previous Migration Set

In some situations in may be desirable to filter the records by associating them with another set of records, either from a previous form migration in the same project or by using an Ad-Hoc Query.  For example, when migrating the work-logs for an Incident, you may only want to migrate those work-log records for which the corresponding parent Incident records are migrated. Think of this as a requirement to 'migrate child records', or 'migrate related records' for the set of parents previously migrated.

To filter in this way, navigate to the Filter By Inclusion section on the Source Filtering Tab and select ‘From Previous Migration Set’ for the Value Set Definition Method.  Using the above example, if the current (child) form mapping is for Work-logs, then you must have defined a form mapping for Incident (parent) with a lower execution order.

The fields in this section are defined as follows:

Field Name	Meaning
Include Skipped Records	If unchecked, only records associated with a 'parent' record that was actually migrated (i.e. reported with migration status of Success or Warning) will be migrated. If checked, records associated with a 'parent' record that was reported with a migration status of Success , Warning or Skipped will be included (Note that records associated with parents reported as 'Error' will not be migrated. 'Unchecked' is appropriate in most situations, see below for cases where including skipped parents might be useful.
Source Field	The name of the source field on the current form mapping that is used to match a value in the Value Set (parent) mapping.
NULL Value Action	If set to Include, will ALWAYS include child records for which the source field is NULL (even if there are no NULL values in the value set) If set to Exclude will ALWAYS exclude child records with a NULL source field value.
Value Set Migration Mapping	The name of the previous form mapping which represents the Value Set (parent).
Value Set Source Field	The field on the Value Set to be matched with the source field on the current mapping

In the above example, the Source Field on the Work Log (child) form is the Incident Number (this is what relates the Work Log to the Incident), the Value Set Migration Mapping is the HPD: Help Desk and the Value Set Source Field is the Incident Number (on the parent Incident).

When the project is executed, only those work-logs which belong to Incidents that have been migrated are themselves migrated.

If both an Inclusion Filter and a Source Filter Query are used, then only those records that satisfy BOTH queries will be returned.  Note that the Source Count button only applies to the Source Filter Query and not to the Inclusion Filter.

When to Use the Skipped Records option

Usually, the requirement is to 'migrate child records related to a parent'. In this case, you do not generally want to include skipped records, since the parent may not have been created resulting in either an error when migrating the child or an 'orphan'

However, the skip option can come in handy when the relationship between the parent and child is multi level (i.e. there is not a foreign key to the parent on the child record that we can use). This use case is described in this article: Handling Complex Parent-Child Relationships in Source Filtering