Check data integrity

Prerequisite: You must be familiar with the Syntax used in Tutorials and have already created an extension.

In the below examples we will use a method to detect an incoherence and prevent such object to be saved in database.

• This method in the Console or Portal, reports errors after submission.
• And prevents creation and update of incoherent objects done by DataSynchro, REST/JSON and CSV import.

We will overwrite the method DoCheckToWrite() of the object class:

• This method is invoked just before writing to database - See details of call stack.
• The method should provide error message(s) if it encounters data incoherence.
• Errors messages are recorded in an array $this->m_aCheckIssues[],
• Warnings messages are recorded in an array $this->m_aCheckWarnings[],
• When returning from this method, if there is at least one error the object is not written to database (creation or update)
• Error and warning messages are
  • displayed to the user in interactive mode only: Console, Portal, CSV import
  • logged in itop/log/error.log depending on level of tracking for DataSynchro, REST/JSON, CLI FIXME -to be checked !-

Migration: No visible effect on setup, but objects not compliant can no more be modified, until they are made compliant. So it could prevent a datasynchro or a REST/JSON script to update other fields for eg.
To identify faulty objects, create an audit rule to retrieve objects not compliant to this new constrain and fix them one by one in the UI or by CSV import.

In this use case we will prevent a Change to be recorded with an End date which would be before the Start date.

class:Change

   public function DoCheckToWrite()
   {
      // Always ask the parent class to perform its own check
      parent::DoCheckToWrite();
 
      // Defensive programming, ensuring that 'end_date' and 'start_date' has not been removed 
      // from the Change class by some extensions which I am not yet aware of.
      // Get the value in seconds before comparing them is safer
      if (MetaModel::IsValidAttCode(get_class($this), 'start_date') 
       && MetaModel::IsValidAttCode(get_class($this), 'end_date')
       && (AttributeDateTime::GetAsUnixSeconds($this->Get('start_date')) 
         > AttributeDateTime::GetAsUnixSeconds($this->Get('end_date'))))
      {
         $this->m_aCheckIssues[] = Dict::Format('Class:Error:EndDateMustBeGreaterThanStartDate');
      }
   }

In this use case we want to prevent a Server to be put in 'production' status without a Location to be provided.

class:Server

public function DoCheckToWrite()
{
   // Always ask the parent class to perform their own check
   parent::DoCheckToWrite();
   // Defensive programming, ensuring that 'status' is an existing field on the current class
   // then checking the condition: an enum value returns code, not label, so we test the code,
   if (MetaModel::IsValidAttCode(get_class($this), 'status')
   && ($this->Get('status') == 'production'))
   {
      // AttributeExternalKey are never NULL, O is the value used when empty
      if (MetaModel::IsValidAttCode(get_class($this), 'location_id')
      && ($this->Get('location_id') == 0))
      {
         // 'Server:Error:LocationMandatoryInProduction' must be declared as a dictionary entry
         $this->m_aCheckIssues[] = Dict::Format('Server:Error:LocationMandatoryInProduction');
      }
   }
}

         // You may also provide a simple error message in plain text
         $this->m_aCheckIssues[] = 'Location is mandatory for all Servers in production';

Here the way to define a dictionary entry in XML:

itop_design / dictionaries / dictionary@EN US / entries

    <entry id="Server:Error:LocationMandatoryInProduction" _delta="define">
      <![CDATA['Location is mandatory for all Servers in production']]>
    </entry>

In this use case we want to prevent two FunctionalCIs to have the same name. Except if the FunctionalCI is in fact a SoftwareInstance, a MiddlewareInstance, a DatabaseSchema or an ApplicationSolution, in which case, we don't care.

class:FunctionalCI

public function DoCheckToWrite()
{
    // Call the function on the parent class as it may need to check stuff as well
    parent::DoCheckToWrite();
    // Check that the name of the FunctionalCI must be unique
    $aChanges = $this->ListChanges();
    // Check if the name field was set or changed
    if (array_key_exists('name', $aChanges))
    {
      $sNewName = $aChanges['name'];
      // Retrieve all FunctionalCI having that new name, ignoring CIs from some sub-classes
      $oSearch = DBObjectSearch::FromOQL_AllData("
         SELECT FunctionalCI WHERE name = :newFCI 
         AND finalclass NOT IN ('DBServer','Middleware','OtherSoftware','WebServer',
            'PCSoftware','MiddlewareInstance','DatabaseSchema','ApplicationSolution')
      ");
      $oSet = new DBObjectSet($oSearch, array(), array('newFCI' => $sNewName));
      // If there is at least one FunctionalCI matching the required name
      if ($oSet->Count() > 0)
      {
         // Block the FunctionalCI writing the Database
         $this->m_aCheckIssues[] = Dict::Format('Class:FunctionalCI:FCINameMustBeUnique', $sNewName);
      }
   }
}

Ensure that a Change has an associated CI attached at creation.

• It's a good example to force a n:n relationship to have at least one entry.

class:Change

public function DoCheckToWrite()
{
    parent::DoCheckToWrite();
 
    // Check if the current Change is expected to have a CI linked 
    // under creation, with a particular type, service, status, whatever logic you need...
    if ($this->IsNew())
    {
        $oSet = $this->Get('functionalcis_list');
        if ($oSet->Count() == 0)
        {
             $this->m_aCheckIssues[] = Dict::S('Class:User/Error:AtLeastOneCiIsNeeded');
        }
    }
}

This is how iTop out of the box ensures that a user has always at least one profile attached.

• Note that this is not enough to prevent the deletion of a Profile which would be the only one of a given User
• Not a big deal in this particular example as iTop UI does not offer any mean to delete a Profile

class:User

public function DoCheckToWrite()
{
    // Call the function on the parent class as it may need to check stuff as well
    parent::DoCheckToWrite();
    // Check if the profile list was changed to avoid loading it for nothing
    $aChanges = $this->ListChanges();   
    if (array_key_exists('profile_list', $aChanges))
    {
        $oSet = $this->Get('profile_list');
        if ($oSet->Count() == 0)
        {
             $this->m_aCheckIssues[] = Dict::S('Class:User/Error:AtLeastOneProfileIsNeeded');
        }
    }
}

This method is not really user friendly, but it allows to let some users modify any FunctionalCI, but limit the creation of a new FonctionalCI only to users having the profile “Configuration Manager”

class:FunctionalCI

public function DoCheckToWrite()
{
    if ($this->IsNew() // Are we trying to create a new object
    && !(UserRights::HasProfile('Configuration Manager')) // The user does not have the profile "Configuration Manager"
    {
 
        $this->m_aCheckIssues[] = Dict::S('Class:FunctionalCI/Error:CreationDenied');    
    }
}

The dictionary entry in this example, does not exist, you must create it.