Block Properties Include Tab — Hierarchical Entities
Use the Include tab in a Query or Fetch block to gather source hierarchical data where parent and child information is stored in a single record instead of related records, such as in an XML file.
Use the Include tab in a CreateWith Block, UpdateWith Block, or UpsertWith Block. to write parent and child data to a hierarchical datastore or use in a subsequent operation.
If the source datastore is not hierarchical, but does have relationships, see Block Properties Include Tab — Relational Data.
Source Parent/Child Relationships
On a Query Block or a Fetch Block, the Include tab shows you the shape of the Source data hierarchically and lets you select the data to be gathered. Any related entity selected on the Include tab is available on the Source side of the Fields tab for operation blocks or in the entity drop-down in the For Each Child block.
- Select Apps from the menu.
- Select an app to open it.
- Select the Flows tab and select a flow to open it.
- Select a Query or Fetch block.
- Select the General link in the Properties panel to open the Block Properties dialog.
- Select the Include tab.
- Select the Browse link next to an entity to display the next level down in the hierarchy.
- Scroll through the list of Related Entities and select the check box in the Select column to include the related entity in the data returned. Note:
You cannot select a child without also selecting its parent. For example if the hierarchy is Country, State, City, you cannot select City without selecting State.
- For each related entity, the following information displays:
- Root Entity.Relationship (Entity)— Name of the object where the Relationship between the primary entity and the related entity is stored. In hierarchical data, this name contains the path from the parent down to the children and grandchildren. For example, if the Root entity is Country, the child is State, and the grandchild is City, then the name of the object is Country.State.City (cityType).
- Type — Type of relationship.
- One to One — For each parent record, there is only one child record for this entity. For example, if the parent entity is Country and the child entity is Government, there is only one Government per Country. Fields from One to One relationships display on the source side of operation blocks within this Query or Fetch block.
- Zero or More — For each parent record, there can be from zero to any number of child records. For example, if the parent record is Country and the child is State, there can be from zero to any number of States within a Country. Fields from Zero or More relationships show up as mappable source fields only for blocks that are within a corresponding For Each Child block.
- Required— Select which records to return from the drop-down:
- Return records with or without relationship — Returns all records for the higher-level entity whether or not there are any records for the related entity. For example, if contact is the higher-level entity and account is the related entity, all contact records are returned whether there is a related account record or not.
- Return only records with relationship — Returns records for the higher-level entity only if there are records for the related entity. For example, if contact is the higher-level entity and account is the related entity, only contact records with at least one related account record are returned.
In the case of multiple levels of nested entities, if a record has no related records, this affects records below it but not above it in the hierarchy. For example, assume a Country has Zero or More States, and a State has Zero or More Cities, and you have selected Return only records with relationship between the state and the city. If a particular state has no cities, the state is excluded from the source data, but this does not move up the hierarchy and cause the whole country to be excluded.
To exclude a Related Entity, make sure the Select check box for that entity is empty. Limit your selections to the data required for your app to improve performance.
Target Parent/Child Relationships
On a target operation block, such as the CreateWith Block, the Include tab shows you the shape of the data as it will be written to the target. If the target datastore and associated Connector do not support hierarchical data, the blocks listed below cannot be used. Instead you must use the traditional Create blocks. Target operation blocks used with hierarchical data include:
There may be some Connector specific blocks that can be used with hierarchical data. Refer to the Help for the Connector for additional information.
Related entities selected on the Include tab of a target operation behave as follows:
- If the Include tab for an operation Block, such as CreateWith, is blank or only one -to-one relationships are selected, the Path drop-down for an Add Block nested within the operation Block is empty.
- If the entity selected on the target operation Include tab has a zero-to-many relationship with the entity selected on the General tab, it is available in the Path drop-down and on the target side of the Add Block Fields tab where source data can be mapped into those entities.
Selecting Target Related Entities
- Select Apps from the menu.
- Select an app to open it.
- Select the Flows tab and select a flow to open it.
- Select an operation block, such as CreateWith, and add it to the flow.
- Select the General link in the Properties panel to open the Block Properties dialog.
- Select the Include tab.
- Select the Browse link next to a parent or child to display the next level down in the hierarchy.
- Scroll through the list of Related Entities and select the check box in the Select column to include the related entity in the data written to the target. Note: You cannot select a child without also selecting its parent. For example if the hierarchy is Country, State, City, you cannot select City without selecting State.
- For each related entity, the following information displays:
- Root Entity.Relationship (Entity)— Name of the object where the Relationship between the primary entity and the related entity is stored. In hierarchical data, this name contains the path from the parent down to the children and grandchildren. For example, if the Root entity is Country, the child is State, and the grandchild is City, then the name of the object is Country.State.City (cityType).
- Type — Type of relationship.
- One to One — For each parent record, there is only one child record for this entity. For example, if the parent entity is Country and the child entity is Government, there is only one Government per Country. Fields from One to One relationships display on the target side of the Fields tab of CreateWith or UpdateWith blocks.
- Zero or More — For each parent record, there can be from zero to any number of child records. For example, if the parent record is Country and the child is State, there can be from zero to any number of States within a Country. Fields from Zero or More relationships display on the target side of Add Blocks within the CreateWith or UpdateWith block.