Add template support for Imports
When importing with Civi-Import it should be possible to use an existing job as a Template - the UserJob table has a is_template
field for this purpose. Without this using SavedMappings is painful as some fields may not load and map. For example the contact field 'Gender' is only available if the contact option is update or create (not the default 'match') so this won't load when the screen is loaded if we are not also loading the relevant options that go with it. Template UserJobs would also be useful outside of Civi-Import for the purposes of loading basic repetitive configuration such as Contact Type, dedupe rule & date format
I do see template UserJobs as eventually replacing saved mappings for imports entirely. There is a 'clone action' aspect to this but I no longer see it being important to resolve that right now.
The way I imagine it working is that
-
if
template_id
is in the url then the code loads the values for that UserJob assumingis_template
is TRUE on theDataSource
form. This would usecheckPermissions
= FALSE because otherwise only the creator can access aUserJob
. (if the template_id is passed in the field to select a mapping would be frozen on the DataSource form) -
a user job template would be updated in sync with the civicrm_mapping record. There is already code for Update & save in a fairly tricksie way on the MapField screen and I propose to soft-link them by virtue of them having the same
name
- so if aMapping
is created or updated a templateUserJob
with the samename
would be too. This makes for a fairly low level of intervention and works with the existing UI, happening when theMapField
is submitted without any change of fields.
The above is moderately simple the question is how to keep the 2 in sync. On one level it is easy as there are NO template UserJobs
in use as yet and existing records have empty name fields - so we have Mapping
records without UserJobs
but not the reverse. As long as we ensure a UserJob
of the same name (perhaps with a prefix) is created at the right point of time & deleting it if the Mapping gets created we can reasonably keep them in sync. The job would be updated from the form when the mapping is (I think we can ignore the possibility people would update the mapping in any other way)
A question remains as to how we would originally create the UserJobs. There are 3 options as I see them
-
on upgrade create a
UserJob
for all existingcivicrm_mapping
records that relate to registered import types. This is probably the cleanest from a code point of view. Themetadata
would basically be an empty array -
when a mapping is selected on the
DataSource
form then inpostProcess
ensure theTemplate UserJob
exists -
when a mapping is selected on the
DataSource
form then ifpostProcess
ensure theTemplate UserJob
exists IF Civi-Import is enabled and / or IF the import in use is the Contribution Import.
A couple of notes
-
Template UserJobs
are more flexible thatcivicrm_mapping
and I expect they will become the way to go - While I see the addition of
template_id
in the url as being sufficient to load a template I expect the path to do that will be a SearchDisplay inCivi-Import
- so it would be a hidden feature with that disabled - The Template is still useful (if added manually to the url) even without CiviImport for loading details on
DataSource
- I suspect a one-off create of the templates on upgrade is likely most maintainable but
- Option 3 does lower our surface area if there are are any problems