Goal

  1. Prepare and test rules on a test environnement. Export and then import them on the production environement once correct
  2. Provide a set of rules ready to use (for example for dictionnaries)

Saving and restoring rules

The goal is to implement a mechanism to store export and import rules.

Import & export

Usages

We can export rules by :
  • globally, through a dedicated page
  • selection, with the massives actions

Importing can be done with the same page as the global export

Database changes

  • Add an uuid field as a unique rule number (filled on rule add)
    • MoYo : manual field or auto generated ? I think I have answer after.
    • Walid : an auto generated one
  • During migration, put an uuid for all rules that are available in the empty databse
  • All the basic rules of glpi should have a predefined uuid

Having an uuid make possible to update a rule which is provided by default in GLPI.

ALTER TABLE `glpi_rules` ADD COLUM `uuid` VARCHAR(255) COLLATE utf8_unicode_ci DEFAULT NULL;

Format

uuid allows to update rules between two instances of glpi (for example : between a qualifying platform and a production platform) and avoid duplication of the same rule.

It will be generated by uniqid php function with more_entropy=true parameter (23char):

$uuid = uniqid('', true);

MoYo : need to check that this uuid does not exists in the DB.

Orthagh : The number generated by uniqid function with more entropy parameter is almost unique.
The php doc on this function tell us : Gets a prefixed unique identifier based on the current time in microseconds. So, i think the collision between two uuid doesn't exist.

MoYo : thinking is not a certainty. Prefer to check twice to be sure. Using 2 GLPI, uuid collision may be possible (not really probable but possible...), so how to include in uuid an uuid of the GLPI system. How to make this uuid of GLPI system unique ?

Orthagh : The uuid of base rules (rules named "root" for example) should not differ between two instances of glpi. On rules created by user, prefix with the uuid of glpi may be a good idea

For this, we can use

uniqid(php_uname('n'), true);
// Output: darkstar4dfa8c27aea106.40781203
> MoYo : in case of 2 GLPI on the same server uuid server is not unique

Orthagh : this ?

$serverSubSha1 = substr(sha1(php_uname('a')), 0, 8); //encode uname -a, ex Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
$dirSubSha1 = substr(sha1(__FILE__), 0, 8); // encode script current dir, ex : /var/www/glpi_X
$uuid = uniqid("$serverSubSha1-$dirSubSha1-", true);

//output : 22101fb0-c9496318-4f61ecf873fbf7.66114182

The uuid will be in 3 parts to insure its unicity :
- 1st part (char8), encoded serveur name
- 2nd part (char8), encoded directory of glpi
- and uuid for the rule, encoded with microtime creation.
These 3 parts provide the unicity even if :

  • they're more than one GLPI instance on the same server
  • they're several GLPI instances on several servers in the same path

MoYo : is this uuid manually updatable after generation ?

Orthagh, no auto-generated only

The rule export format can be a XML file:

<RULES>
  <NAME>myname</NAME>
  <UUID>4b340550242239.64159797</UUID>
  <DESCRIPTION>My description</DESCRIPTION>
  <COMMENT>My comment</COMMENT>
  <IS_ACTIVE>1</IS_ACTIVE>
  <MATCH>OR</MATCH>
  <SUB_TYPE>RuleOCS</SUB_TYPE>
  <ENTITIES_ID>0</ENTITIES_ID>
  <IS_RECURSIVE>1</IS_RECURSIVE>
  <RANKING>1</RANKING>
  <RULECRITERIA>
    <CRITERIA>TAG</CRITERIA>
    <CONDITION>0</CONDITION>
    <PATTERN>MYTAG</PATTERN>
  </RULECRITERIA>
  <RULECRITERIA>
    <CRITERIA>TAG</CRITERIA>
    <CONDITION>0</CONDITION>
    <PATTERN>TAG2</PATTERN>
  </RULECRITERIA>
  <RULEACTION>
    <ACTION_TYPE>assign</ACTION_TYPE>
    <FIELD>entities_id</FIELD>
    <VALUE>0</VALUE>
  </RULEACTION>
</RULES>

or a JSON file :

{
   "name"         : "myname",
   "uuid"         : "4b340550242239.64159797",
   "description"  : "My description",
   "comment"      : "My comment",
   "is_active"    : 1,
   "match"        : "OR",
   "sub_type"     : "RuleOCS",
   "entities_id"  : 0,
   "is_recursive" : 1,
   "ranking"      : 1,
   "criterias"    : [{
      "criteria"     : "TAG",
      "condition"    : 0,
      "pattern"      : "MYTAG" 
   }, {
      "criteria"     : "TAG2",
      "condition"    : 0,
      "pattern"      : "MYTAG2" 
   }],
   "actions"      : [{
      "field"        : "entities_id",
      "action_type"  : "assign",
      "value"        : 0
   }]
}

Json export seems to be the simpliest way, since it doesn't require to create or parse an XML document.

MoYo : XML is the simplest way to store and edit files.

Orthagh : IMHO, XML is too verbose, and requires a parser to be used. In return, this is a standard in all languages.

Json is easier to use with php, it requires only the functions json_encode and json_decode on an array or object.
MoYo : JSON is maybe easier to use but it is not a reason to use it. It is easier to buy pizza but I make mine.

Orthagh : You're right, anyway I started with this format and it is less difficult to use than I thought.
In my draft development, I use the php class "SimpleXML". This lib is enabled by default on php> 5.1.2 (see : http://www.php.net/manual/en/simplexml.requirements.php)

MoYo : export / import must be problematic if only based on ID (for criteria and actions). On 2 GLPI objects may be similar but not have the same ID (entities, users...).
Walid yes, that's what I tried to explain below. We must, I think, base the search on names, and not ID

Possible errors

one or more criteria doesn't exists refuse to import rule
one or more action value doesn't exists refuse to import rule

MoYo : on update what is the process ? What about local changes that may have been done ?
MoYo : I do not understand last 2 problems... WHat's about ?
Walid : see below

We need to check the rule and it's action/criteria before writing it in DB to avoid importing unexisting value.

A rule criteria doesn't exists

For example : I add a new LDAP criteria in glpi_rulerightparameters on the source GLPI. I want to export my rules on a new one, and the criteria doesn't exists. what shoud the process do ?

A criteria or action value doesn't exists

My action value is "assign entity toto" : if the entity doesn't exists in the target GLPI, the rule process must be stopped.

Orthagh. During the upgrade of an existing rule, I think we should remove the criteria and actions dependent of this rule and add imported.

It is not possible to find a match if they have just been updated, except also adding an uuid on these actions and rules.

FK case :

We need to ensure that the foreign keys exported is present in the glpi before import rules.

  • On export, we encode in the xml the 'name' field of the fk instead of its id
  • During import, we verify that the name exists in the table foreign key. If it does not exist, we refuse the import of the rule.

The "true" import is played after viewing a report of refusal and after acceptance of the user

//TODO : add a datatype for actions & criteria

GUI

page "global rules maintenance"

page "global export rules" :

MoYo : Is there a interest of global export ? Check All + masive action may be a simplest solution.
Walid: I think yes. I work on a test GLPI and create all my rules. I then want to import all changes on the production GLPI. Might be treated later, but I think it's an interesting possibility

MoYo : on import for a list of rules, choice of destination entity and which rules to import must be possible I think.
Walid : yes you're right for rules that are entity based

Duplicating rules (See : https://forge.indepnet.net/attachments/1084/duplicate_rules.diff)

  • The new rules after the duplication have to be inactive.
  • We can use the massives actions to select rules. On the redirect page, show a form with all selected rules and for each, display an input text and a textarea for their new names and descriptions

MoYo : a simplest way will be to duplicate rules and simply rename it (adding duplicate on the name for example). Manual update to change names may be done after.
Walid : ok, duplicate the rule and regenerate an uuid

Orthagh : Ok for me

rules_export.png (34.5 KB) orthagh, 03/09/2012 05:37 PM

rules_maintenance.png (4.83 KB) orthagh, 03/09/2012 05:48 PM

rules_duplicate.png (9.31 KB) orthagh, 03/12/2012 10:49 AM

duplicate_rules.diff Magnifier (3.25 KB) orthagh, 03/13/2012 05:28 PM