Use the CreateWith Block to write entity records to a target datastore that stores related data hierarchically. You can, for example, use a CreateWith Block to process a Sales Order and use the Add Block to include the Sales Item entity or children contained in the Sales Order record or parent. See Hierarchical Data.
Note: This Block is only available for Connections that support hierarchical data.
The CreateWith Block adds a new record for a specified entity, and can contain Add Blocks to specify data for its children to add records to a datastore. As part of configuring a CreateWith Block, you:
- Select the parent entity to use for this CreateWith operation.
- Add supported related entities. See Block Properties Include Tab — Hierarchical Entities.
- Map the fields you want to add to the new target records.
- Configure Error Handling.
Note: Change Block Operation Type and Batch Processing are not supported for target Blocks associated with hierarchical data.
The CreateWith Block builds an entire hierarchical record and then writes that to the target datastore. When using a CreateWith Block and any Add Blocks it may contain, no data is written to the target until the end of the CreateWith operation. If you use a standard Create, Update, Delete operation within a CreateWith Block, those operations write to the target immediately.
When using a CreateWith Block, operation results are only available outside the CreateWith and only for the first level of the hierarchy selected. For example, if in the CreateWith Block you selected an entity named Country, only the results for Country are available, not the results for any related children or grandchildren.
Depending on your requirements, you can nest CreateWith Blocks. If for any reason there is a conflict where an Add Block might be paired with more than one CreateWith Block, the innermost CreateWith Block takes precedence.
Note: To improve the readability of a Map, select the collapse () or expand () icons on the Block to display or hide all of the Blocks included within the selected Block.
Block Properties — General Tab
For target Blocks that support hierarchical data, use the Include tab to select related entities that you wish to write to the target datastore. For example, if your hierarchy is Country, State, City, Business, and the entity selected for this Block is Country, select State, City, and Business to indicate that you also want that data for each Country. To include the related child information, use a combination of the For Each Child Block and Add Block inside this Block. See Block Properties Include Tab — Hierarchical Entities.
Block Properties — Fields Tab
From the Block Properties Fields Tab, you can:
- Create links between source and target data fields, including fields from the relationships that you specified in the Query Block or Fetch Block:
- Source fields from parent entities are available in all Blocks.
- Source fields from child entities are only available within a For Each Child Block for that child relationship. See Mapping Hierarchical Data Fields.
- Target fields for entities with one to one relationships with the entity selected on the General tab display only if the related entities are selected on the Include tab for the target operation Block, such as CreateWith or UpdateWith.
- Autolink one or more source and target fields that have the same name, compatible data types, and are not read-only. Fields for child entities do not Autolink. You may need to clear some fields linked by Autolink, such as any modifiedon or createdon datetime fields. See Autolinking.
- Create simple or complex formulas to transform source data. See Formula Editor.
- View detailed information about any field in your source or target using the Info icon .
When using the Fields tab, you can:
- Use column filters to find specific data in the source or target pane as described in Using The Filter Dialog.
- Select any column head to sort all fields in the pane by that column.
Note: When you first open the Fields tab, the icon displays and the Errors/ Warnings tab indicates that there are Errors and Warnings. This is expected behavior. Errors and Warnings display for the General and Fields tabs until all required data has been entered and the Validate button has been selected. See Block And Map Errors And Warnings.
Block Properties — Error Handling Tab
Use the Error Handling options to enable or disable processing this record when a Block operation encounters a problem. For the CreateWith Block, errors can be logged when an operation fails. See Block Properties Error Handling Tab for additional information.
If this setting is checked, an error from any part of the data, parent or child, generates a record error and no more Blocks execute for that record. If the setting is unchecked, no error is written to the log and the Map continues running with the text of the error available in the Result Fields.
Note: For most runtime errors, the error handling setting on the CreateWith, UpdateWith, or UpsertWith Block supersedes the error handling set on any Add Blocks within it, even if the problem is generated by one of the fields in the Add Block.
Block Properties — Errors And Warnings Tab
If there are any errors or warnings for this Block, the Errors and Warnings tab displays the number of errors or warnings in the tab name. See Block And Map Errors And Warnings.
Once you have corrected the errors, select the Validate button to update the Errors and Warnings tab.