Object mapping

The Object Mapping form is accessed from the properties of a Create Record task to specify how values are copied to new records to initialize them.

The form is also accessed from the properties of a Modify Records task to specify how values will be copied to existing records to modify them.

In this explanation of the Object Mapping form, the record that values will be copied from is referred to as the source record.

The first section of an Object Mapping form is labeled with the name of the business object that is expected to have been used to create the record being modified or created. In the middle of the first section' is the name of the business object used to create the source record.

In the first section is a dropdown field labeled Association Type. If an association is selected in this field, the selected type of association will be created between the record being initialized or modified and the source record. The dropdown list of Association Types is defined by the object-level associations defined for the object record being created in the Association Manager or Data Modeler.

The Association Type setting in the Object Mapping form is used to create a record-level association from the record being created to the record listed in the Initialize From section of the Create Record task.

If the Object Mapping form is being used to specify how to initialize new records, two check boxes appear under Association Type. These check boxes are not in the Object Mapping form when it is used to specify how to modify an existing record.

Use Source Project: If this is checked, records created by this task will be part of the same project as the source record.
If this is not checked, records created by this task will be part of whatever project is the current project. For a top-level record, its project will be that of the user's project context. For a new child record, its project will be that of its parent record. For an existing record that is made to be the child of another record, its project will be that of its parent record.
Include Child Records: If the source record is part of a hierarchy module, copies of all of the source record's children will be made. The copies will be children of the newly created record.
The copy of child records includes all children in the hierarchy, the values of their fields, any embedded records, and any associations. Note that even though the associations are copied, the associated records are not copied.

The Object Mapping form always has a section labeled General. The section labeled General is different from the other sections because it contains a list of fields that are not in any smart section.

The rest of the sections in the Object Mapping form are labeled with the names of smart sections in the record to be initialized or modified. In each of these sections is a list of the fields in the named smart section.

Each field name and section name has text that describes what the mapping operation does to the field. When there is no text, the mapping operation does nothing to the field.

The field name may contain accompanying text like:

General::PeopleFillName

This names the section and field in the source record. If a string appears, the new value for the field is copied from the specified field. You do not type in this text yourself. Instead, the text is put there as a result of a selection you made elsewhere.

If the text is in a text field, it means that the text is constant text that will be used as-is. This means that the mapping operation will always set the field to that value. To enter constant text into a text box, select the check box. When the check box is selected, a box appears and you can type text into it.

Workflow constant mapping for a locator field is case sensitive.

Text mapping should not be used to populate locator fields. Instead, use a mechanism to identify the record to be mapped into a locator via the task's Map From or Initialize From section and use the Source mapping option. It may require an additional Retrieve Records task or Query task to identify the record, but doing so ensures that the current record is being mapped into the locator.

A circumstance where text mapping can be used safely is when the value being mapped is either the full publish name for non-hierarchical objects, or the full hierarchy path for hierarchical objects. Only do so if the locator field has those respective fields set in the locator field's business object.

There is a special constant you can specify that means to copy the current time into a field. If you map a field to the constant $$CURRENTTIME$$, the mapping operation will copy the current time and date to the field. If mapping $$CURRENTTIME$$ to a text field, it maps a formatted date time value. If mapping to a number field, it maps a millisecond value.

To set a duration to a constant value, express the duration as a number of milliseconds. A duration of one hour is 3600000 milliseconds. A duration of one week is 604800000 milliseconds. A duration of one day is 86400000 milliseconds. Because a duration of one day is relatively common, there is a special way to represent a duration of one day that is easier to remember and easier to read. Instead of entering 86400000, you can enter $$DAY$$.

If you click the search icon, a small window pops up. This window contains radio buttons for the fields and sections of the source record.

This small window is called an attribute picker. If you want the mapping operation to copy data from a field in the source record, click the attribute picker icon for the field you want the data copied to and select the radio button for the source field. The procedure is similar if you want to copy from a smart section in the source.

There are two radio buttons in an attribute picker that do not correspond to a field or a section. These radio buttons are labeled None and Source.

If you select the radio button labeled None, it means that the mapping operation will not do anything to the affected field. In the Object Mapping form, the field will be blank.

If you select the radio button labeled Source, it means that you want to use the entire source record. This is useful, for example, if you want to point a smart section or locator field at a particular record. When populating a locator field or smart section via the workflow Object Mapping form, always choose the Source option from the attribute picker. This ensures that a valid reference gets created to the record being placed in the locator field or smart section.

If you use the Source radio button to put a record in a smart section, what actually happens depends on the kind of record that is the source for the task.

If the source is a stand alone record, then a reference is created from the smart section to the source record.
If the source is an embedded or link record, then a copy is made of the source record and a reference is created from the smart section to the copy.

There is another source of data for a mapping operation to copy. Some tasks perform computations. The results of these computations are associated with the task that performed them rather than with a record.

If you want a mapping operation to copy the results of one of these computations to a field, click the task data picker icon (it looks like binoculars). The task data picker shows each of the tasks that precede the current task.

Sometimes you want a mapping operation to use a formula to compute a value. You can use an extended formula as the source of data for a field. Extended formulas are described in Application building: Calculations.

To specify an extended formula as the source of data for a field, click the formula picker icon. Clicking the formula picker icon causes an Extended Formula window to pop up.

This Extended Formula window differs in three ways from the one discussed in Application building: Calculations.

First, extended formulas are available for fields of any data type in the Workflow Builder; they are not limited to numbers and dates.
Second, the extended formula does not have an Outputs section. An extended formula used in object mapping always has exactly one output, which is the field it is being used to provide data for.
Third, extended formulas can access fields in the source record of the object map only; fields from associated objects cannot be accessed.

With these exceptions, specifying an extended formula for use in an object mapping operation is exactly the same as using an extended formula anywhere else.

Note that when the name of a field is the same in the source record and the destination record and the destination field has formula mapping, the target field value is not mapped. Instead, it is calculated from its Data Modeler formula mapping. If a formula field is grayed out, it means that the formula map defined in the Data Modeler is used as the source value for this field.

The Object Mapping form also allows makes it possible for you to map associations from the source object to the target object. The Association Mapping section of the object map displays a list of the associations defined for the target business object. When you click the search icon for one of the associations, the association picker contains radio buttons for the association definitions of the source record.

You will notice that the association definition of the target is used to filter which associations you see from the source to those of the same business object. If you want the mapping operation to copy associations from the source record, click the search icon for the association definition you want copied to and select the radio button for the source association definition.

At runtime if an association is found from the source to the selected business object with the selected string, a new association will be made from the target using the definition selected. If the target association is flagged as dependent, a copy of the record associated to the source will be made and associated to the target.

To clear the mapping for a field, section, or association click the clear data icon.