Background

The Org Structure screen allows the user to build a hierarchy of Org Units that represents the physical or logical structure of the organisation. 

The top four levels of the hierarchy are known as Org Unit 1, Org Unit 2, Org Unit 3 and Org Unit 4, and these Org Unit names are shown in the following types of record:

• Audit
• Entity
• Incident
• Key Issue
• Problem

The hierarchy may change in a couple of ways:

• Org Unit names may change
• An Org Unit may move to a different parent Org Unit (though in this case it is important to consider whether it is more appropriate to mark the existing Org Unit as Inactive and create a new one to replace it)

In both cases, making an update to the hierarchy means that Pentana must make changes to each individual record that has the original value in one of its Org Unit fields.

This could be a huge amount of records to update, so instead of keeping the user waiting the following happens:

• The user makes the change in the Org Structure screen
• The Pentana service submits a new UpdateHierarchyProperties job to the message queue
• The next time the matching Robot task runs, it will begin updating all of the affected records 
  
  

The Problem

As you can see from the description above, updating the Org Structure is in two parts:

• The update by the user, to change the hierarchy in some way
• The follow-on update by the robot, to align all of the affected records

Therefore it is possible to end up in a situation where the initial edit is made successfully but the 'child' records don't get updated, and remain with stale data stored in their Org Unit fields.  This can happen in various ways, for example:

• If the UpdateHierarchyProperties job is not running
• If the message queue is purged after the edit is made and before the job runs
• If the database moves from one environment to another before the robot job is completed

The solution is straightforward - to update the hierarchy and force another update - but executing that can put a heavy load on the system. 

The solution - for a small database

If the database is small then the fix is simply: 

• Ensure that the Robot is running
• Ensure that the UpdateHierarchyProperties job is active, and is set to run at an appropriate time (by default this is every 30 seconds - CRON value is 20/50 * * * * ?)
• In Pentana, go to Org Structure and highlight the root node 'All Org Units':
  
  
  
  
• In the Properties panel, change the Name to something else (e.g. add a '1' to the end, so that it is 'All Org Units 1') and then save
• Do the same again - change the name back again, and then save

This will change the name twice, but is the easiest method.

The solution - for a large database

If the database is large, this will not only cause a lot of work to be done but it will be twice as much as is strictly necessary to update with the desired values.  To minimise the load on the system, do the following: 

• Do this at a quiet time, when there are no users on the system and there will be no activity (e.g. overnight)
• Ensure that the Robot service is running without error
• Ensure that the UpdateHierarchyProperties job is active, and is set to run at an appropriate time (by default this is every 30 seconds - CRON value is 20/50 * * * * ?)
• Ensure that the message queue has no pending messages
• Stop the Robot service
• In Pentana, go to Org Structure and highlight the root node 'All Org Units'
• In the Properties panel, change the Name to something else (e.g. add a '1' to the end) and then save
• Look at the message queue (refresh if necessary).  There will be a new message for the UpdateHierarchyProperties job. 
• Either Move this job to a spare queue, or Purge the queue
• Start the Robot service
• In Pentana, go to Org Structure and highlight the root node
• In the Properties panel, change the Name back to its original value, and then save

This will result in a new message on the queue.  After the Robot has begun to process the message the records will begin to update, in batches of 100.  The time taken to complete the job will depend on the volume of data and the server performance.