UpsertWith Block

Use the UpsertWith Block to update existing or create new hierarchical records where one or more child records are contained within the parent record. You can, for example, use an UpsertWith Block to process a Sales Order and use the Add Block to add new Items. See Hierarchical Data.

The behavior when child data is omitted from an UpsertWith operation may vary by Connector. For example, if you use an UpsertWith Block to modify a country, but do not add any of that country's states, the existing states may all be deleted or they may be left alone. Consult the documentation for the specific Connector to determine how such scenarios are handled.

When configuring an UpsertWith Block you need to:

Select the parent entity that you want to update.
Add supported related entities. See Block Properties Include Tab — Hierarchical Entities.
Map the fields to update or insert.
Configure Error Handling.

Note: Change Block Operation Type and Batch Processing are not supported for target blocks associated with hierarchical data.

Block Properties — General Tab

From the Block Properties General Tab, you can change the Block Label, add a description, and select the parent or top level entity to use for this operation.

Block Properties — Include 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 to modify that data for each Country. To include the related child information, use one or more Add Blocks 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.
Use the SmartMapper service to help you link selected source and target fields. You may need to clear some fields linked by SmartMapper, such as any modifiedon or createdon datetime fields. See SmartMapper.
Create simple or complex formulas to transform source data. See Formula Editor Overview.
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 UI Filters.
Select any column head to sort all fields in the pane by that column.

For detailed information about using the Fields tab, see Block Properties Fields Tab and Mapping Hierarchical Data Fields.

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 Flow 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 UpsertWith 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 flow 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 Flow Errors And Warnings.