updateHierarchy
- Description
- This transaction updates a hierarchy. A hierarchy is a structure formed by two or more nodes that represent entities; nodes may be linked by parent/child relationships, and one of the nodes may be designated as the ultimate parent of the hierarchy. In addition, this transaction can be used as a coarse-grained transaction to update a hierarchy, add one or more nodes, update one or more nodes, add one or more parent-child relationships between nodes, update one or more parent-child relationships between nodes, add an ultimate parent, and update an ultimate parent.
- Web Services
- Operation name: updateHierarchy
- Web Services
- Operation name: UpdateHierarchy
Service name: HierarchyService
- Example
- Update a hierarchy, add one or more nodes, update one or more nodes, add one or more parent-child relationships, update one or more parent/child relationships, add an ultimate parent, update an ultimate parent.
- Usage information
The following entity types are currently supported: CDPRODTP, CONTACT, CONTRACT, GROUPING, PERSON, ORG.
When using this transaction as a coarse-grained transaction, the following simple transactions may also apply:
- addHierarchyNode
- updateHierarchyNode
- addHierarchyRelationship
- updateHierarchyRelationship
- addHierarchyUltimateParent
- updateHierarchyUltimateParent
Hierarchy types (cdhierarchytp) and categories (cdhierarchycattp) are user definable through a code table. A hierarchy type can be categorized by the hierarchy category type.
- Preconditions
- Hierarchy must exist
- Mandatory input
- HierarchyName
- Inquiry levels
- Not applicable
- Filter values
- Not applicable
- Transaction behavior
- All nodes, relationships, and ultimate parent designations must
be ended before the hierarchy itself can be ended.
A hierarchy must not have more than one ultimate parent at any given time in its time line. In other words, one ultimate parent can be ended and new one added for a for a time slice, which is not overlapping with the first one.
Cyclical relationships are not permitted in a hierarchy, meaning that the child of a node cannot also be the node's parent.
The hierarchy category type and value will be returned when the associated hierarchy type is provided.
When an updateHiearchy or updateHierarchyNode transaction contains nodes/ultimate parent/node relationships, validation checks for nodes, ultimate parent, and relationships may fail incorrectly.
There are four scenarios in which validation checks may fail incorrectly when the updateHierarchy or the updateHierarchyNode transaction runs:- The node validation check on time frame (start and end date) for
the ultimate parent and node relationship may fail. It does not consider
any changes to the ultimate parent or node relationship in the request
message. Note: This scenario applies to both updateHierarchy and updateHierarchyNode.
- The ultimate parent validation check for uniqueness may fail when
there are multiple ultimate parent changes in the input. The duplication
check does not consider these multiple ultimate parent input changes.Note: This scenario only applies to updateHierarchy.
- The ultimate parent is a child validation check may fail when
there are multiple node relationship changes in the input related
to this node. The validation check fails to consider these input changes. Note: This scenario only applies to updateHierarchy.
- The node relationship cyclic validation check may fail when there
are multiple node relationship changes in the input. The validation
check fails to consider these input changes.Note: This scenario applies to both updateHierarchy and updateHierarchyNode.
If the updateHierarchy or the updateHierarchyNode transaction fails, the workaround is to divide the one composite updateHierarchy transaction into the following fine grained transactions:- add/updateHierarchyNode
- add/updateHierarchyRelationship
- add/updateHierarchyUltimateParent
Dividing and running these transactions in the proper sequence will ensure that the data required to pass validation already exists in the database.
- The node validation check on time frame (start and end date) for
the ultimate parent and node relationship may fail. It does not consider
any changes to the ultimate parent or node relationship in the request
message.
- Request message
- <TCRMTxType> updateHierarchy
<TCRMTxObject> DWLHierarchyBObj
<TCRMObject> DWLHierarchyBObj
with optional business objects:
- Response objects
- DWLHierarchyBObj
with optional business objects:
- Special note
- Not applicable