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
Service name: DWLBusinessServices
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:

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.

Request message
<TCRMTxType> updateHierarchy

<TCRMTxObject> DWLHierarchyBObj

<TCRMObject> DWLHierarchyBObj

with optional business objects:

Response objects
DWLHierarchyBObj

with optional business objects:

Special note
Not applicable