Embedded Files
When DMM migrates data between two environments it has to keep the records connected to each other. The MapperWorker entity is where it records how each source record maps to the record that was created in the destination.
When DMM uses it
DMM only stores this data when it actually needs it. There are two cases:
Data Append mode. The entities mapper is saved, so that the correspondence between the source and the destination identifiers is available for the records that were appended.
Migrate BPT. The BPT mapper is saved, so that the process and activity records keep pointing at the right data.
If a migration runs without Data Append mode and without Migrate BPT, DMM has no need to keep the mapping and does not store it. There will be nothing in the MapperWorker to consult afterwards.
This matters if you intend to use the mapping yourself: it has to be decided before the migration runs, by the configuration you choose, not afterwards.
Why it exists
Most OutSystems entities use an autonumber primary key. The value of that key is generated by the database at the moment the record is inserted, which means DMM cannot force the destination to reuse the identifier the record had in the source. The destination assigns its own.
That by itself would break every relationship in the data, so for each record it inserts DMM stores the pair of identifiers: the one in the source and the one the destination assigned. Whenever it later inserts a record with a foreign key pointing at that entity, it looks the pair up and writes the destination identifier instead of the source one. The records end up connected exactly as they were in the source, even though the identifiers themselves are different.
This is invisible during normal use. You only need to know about the MapperWorker in three situations: when you want to translate identifiers yourself after a migration, when you are planning database space for a large migration, and when you are deciding how long DMM should keep this data.
What it contains
Each row is one source identifier and the destination identifier that corresponds to it, for one entity. Three columns matter if you are reading the data yourself:
ENTITYID — identifies the entity the pair belongs to.
SOURCEVALUE — the identifier the record had in the source.
DESTINATIONVALUE — the identifier the record was given in the destination.
The entity has further columns that DMM uses internally. They are implementation detail, they may change between DMM versions, and you should not build anything that depends on them.
How long the data is kept
The MapperWorker is not meant to be a permanent record of an ordinary migration. A background timer, ClearMapperWorker, removes old rows.
It keeps rows for the number of days set in the site property DaysToClearMapper, which is 2 by default. If you set the property to -1 the timer deletes the rows without looking at the date at all.
There is one important exception. Rows created by a delta migration are not removed by the timer. They are the baseline the next delta run compares against, so DMM keeps them for as long as the delta configuration exists, regardless of DaysToClearMapper.
So the retention rule only applies to the mapping produced by ordinary migrations. If you intend to use that mapping data yourself, raise DaysToClearMapper before you run the migration, not after. Once the timer has run the correspondence is gone, and the only way to rebuild it is to run the migration again.
Size and growth
During a migration the MapperWorker receives a row for every record DMM inserts into an entity whose identifier has to be translated. On a large migration this is normally the largest table DMM creates, and it grows in proportion to the volume you are moving rather than to the number of entities.
Plan for it when you size the database that hosts DMM. Two things are worth checking before a large run:
that the tablespace or data file holding the DMM tables has room to grow, and is not capped at a size the migration will reach;
that DaysToClearMapper is not set to a value that keeps several large migrations' worth of rows alive at the same time.
A migration that fills the available space will fail partway through. For ordinary migrations, lowering DaysToClearMapper or letting the timer run between runs is the normal way to keep the table under control.
For delta migrations it is not, because the timer does not remove those rows. A delta configuration's mapping grows with the data it tracks and stays there for the life of the configuration. Size for that: it is retained data, not a temporary working set.
Using the mapping to update identifiers stored in text
DMM translates identifiers only in attributes that OutSystems declares as foreign keys. If your application stores identifiers inside a Text attribute, inside JSON, inside a URL, or in any other free-form content, DMM has no way to know they are identifiers and leaves them untouched.
You can fix those yourself using the mapping:
Make sure the migration will actually produce the mapping, as described in When DMM uses it above.
Before the migration, set DaysToClearMapper high enough that the data will still be there when you get to it.
Run the migration.
Export the MapperWorker entity. Every row carries the entity it belongs to, so keep only the rows for the entity whose identifiers you need to translate.
Use the SOURCEVALUE and DESTINATIONVALUE pairs to run your own find and replace over the affected fields in the destination.
Do this as soon as the migration finishes. The timer will eventually clear the rows, and nothing warns you that it is about to.
One limitation to be aware of. DMM keeps the mapping for an entity only where it is needed. If no other entity has a foreign key to it, there is nothing for DMM to translate, so no mapping is stored for that entity and it will not appear in the export. This can affect exactly the case described here: an entity whose identifiers are only ever referenced from inside text has no declared foreign key pointing at it, and is therefore one of the entities DMM has no reason to map. If you depend on this workaround, check that the entity is genuinely referenced before planning around it.
What not to do
Do not insert, edit or delete rows in the MapperWorker by hand, and do not clear it manually to recover disk space while a migration or a delta migration is in use. DMM treats what it finds there as the record of what has already been migrated. Removing rows does not produce an error; it causes the next delta migration to behave as though those records had never been migrated, which can result in duplicated data in the destination.
If you need the table smaller, use DaysToClearMapper and let the timer do it.
Delta migration
Delta migration uses the MapperWorker to decide what has changed since the last run. It compares each source record against what it recorded there, using the primary key, or the selected attributes if you are using the User Mapped Table feature, to tell whether a record is new, has changed, or has been removed.
Because that comparison has to work no matter how long ago the previous run was, the rows a delta migration creates are kept. ClearMapperWorker does not remove them and DaysToClearMapper does not apply to them, so you do not need to tune the property around your delta schedule.
What this does mean is that the mapping for a delta configuration is long-lived data. Do not clear it manually to reclaim space, and see What not to do below for what happens if you do.
That last pointer matters more now than when I first drafted it: with the timer out of the picture, manual deletion becomes the only realistic way those rows disappear — which makes it the only realistic way to silently break a delta migration.
Report abuse