Helper class to handle issues around the Rank field of the Person row
public sealed class PersonRankHelper
Persons that belong to one contact should have a monotonically increasing set of rank values, starting with 1. In order to move a person to a lower (earlier) rank, it is swapped with its neighbour; or if the move takes it further, all intervening persons also get their ranks changed.
This class contains methods to shift a person one step up or down; set a given rank value; and normalize (clean up) the ranks for a given contact, in case they have become inconsistent.
The person with rank 1 (and there should only be one!) has a special function and is used in many cases, such as when 'add first person' in selection is used.
Move one person up or down in the ranking in the Person Archive, if possible.
The person record that has rank = 1 is the primary contact for a company, and is the one used in situations where no person has been explicitly chosen (such as in selections).
This method corresponds to the move up/move down functions in the person archive in the contact panel.
This method always affects two records.
public int ChangePersonRank(int personId, bool moveUp)
Primary key of person record to move up or down. You must have write access both to this record AND to whatever record is adjacent in the direction you want to move.
If true, the given person is moved to an earlier rank (lower numeric rank value, down to a limit of 1; up in the GUI if sorted by ascending rank). If false, movement is to later priority (higher numeric rank value).
If movement occurred, the return value will be the ID of the OTHER person that got moved. A GUI should switch the positions of the original person ID and this return value.
If no movement occurred, for any reason, 0 is returned.
Nomralize the ranks for all persons that belong to a contact. This means that the persons will be sorted according to their current rank values, and the ranks will be made monotonically increasing from 1.
public bool NormalizeRanks(int contactId)
Id of contact whose persons are to be rank normalized
The reutrn value is true if the operation suceeded, either because all persons were already normalized, or because normalization was done. It is false if Sentry blocks any required changes.
Directly set the rank field of a person record, adjusting all other person records under the same contact as needed.
This call may affect multiple records, potentially all person records belonging to one contact.
You must have write access for to affected records for this method to succeed.
public bool SetPersonRank(int personId, short desiredRank)
Id of person to change
Desired rank to set, legal values are from 1 to the number of person records on this contact. Out of range values will be moved to the closest valid value and processed.
If movement occurred, or the person already had exactly the desired rank value, then the return value will be true. If movement did not occur, for any other reason, the return value is false.