How to link a library element to a GLPI table - ericferon/glpi-archimap GitHub Wiki

Pre-conditions

• You are creating or modifying a library (see How to create or modify a library stored on the GLPI repository)
• You have access to (a copy of) the GLPI DB schema and you know the table name, its fields and the foreign key tables of the GLPI asset that you want to link

Steps

1. Right-click on the library's shape that you want to link and select "Link to repository"
   If the menu "Link to repository" doesn't appear, you have probably not assigned a name to this shape

2. A new window opens with a list of fields to fill in :
   
   
   

• Stencil id (mandatory) : you must choose a shape's unique name among all libraries. Once saved, you shouldn't change it !
• Access type (mandatory) : currently, only "Local, via SQL" is available
• Main table (mandatory) : you enter the name of the asset's table name
• Main table columns (mandatory) : you enter a comma-separated list of the fields that the "autocomplete" function must search on.
  The fields are not limited to the main table : they may belong to joined tables, with the right table prefix.
  You may add an "as" alias if you want to distinguish (some of) them from other joined columns (hereafter) with a name that you can use in the "Display as" or "CSS Class" hereafter.
  The first column name in this list is considered as the main asset identifier, from a user perspective, and will always be displayed in the search results.
• Join criteria (optional) : if you have foreign key(s) in your main table, you can enter here the (left) join statement(s).
  The fields that you want to use from these joined table(s) can be mentioned either in the "Main table columns", either in the "Join columns" hereafter.
• Join columns (optional) : a comma-separated list of columns from the main or joined tables.
  The column names will typically be prefixed with the table name where they come from ("table.column" notation) and an alias can be assigned to them ("as" notation).
  These columns will not be used in the search, but well for displaying the search results (in "Display as").
  They can also be used in composing the "CSS Class" names.
• Selection criteria (optional) : You can enter here a selection criteria expressed as an SQL WHERE clause (without the WHERE)
• Sort criteria (optional) : A comma-separated list of fields to be used in an SQL ORDER BY clause (without the ORDER BY).
• Display as (optional) : this field specifies how the search results will be displayed for selection by a user.
  The first column mentioned in the "Main table columns" is always displayed (even when this "Display as" field is empty), because it is considered as the main asset identifier, from a user perspective. It's typically the name of the asset.
  When this "Display as" field is filled in, the field is interpreted, instantiated with search result values and displayed just after the default display explained here above.
  This field is a sequence of tokens separated by a + sign (concatenation sign).
  Each token is :
  • either an unambiguous column name or an alias mentioned in the fields "Main table columns" or "Join columns" (advice : use aliases)
  • either a character string between single quotes
• CSS Class (optional) : this field specifies how one or more CSS class names will be added to the shape. The shape can then change its appearance, depending on how styles have been associated to the CSS class(es) (see How to change the appearance of a library element according to its custom properties).
  The field is interpreted, instantiated with search result values and added to the HTML shape's style. After instantiation, this field must produce a semicolon-separated list of CSS class names (or only one CSS class name without semicolon). Like "Display as", this field is a sequence of tokens separated by a + sign (concatenation sign).
  Each token is :
  • either an unambiguous column name or an alias mentioned in the fields "Main table columns" or "Join columns" (advice : use aliases)
  • either a character string between single quotes.
    Do not forget to include semicolon(s) in these character strings, if you specify several CSS class names.
• Object Class (required) : this is the name of the PHP class used by GLPI to manage the asset. You find it in the source code, either in the directory 'inc' for GLPI core assets, either in the directory 'plugins/pluginname/inc' for plugins assets, in a file whose name is ending by '.class.php'.
• Link (optional) : you may define here an hyperlink to another GLPI screen or another application. You define this hyperlink with a sequence of tokens separated by a + sign, in the same way as the 'Display as' field.
• SQL statement : this field shows you the SQL statement that will be executed on the GLPI database, based on the fields 'Main table', 'Main table columns', 'Join criteria', 'Join columns', 'Selection criteria' and 'Sort criteria' that you have filled in
• SQL results : this table shows you the 5 first results of the SQL statement

3. Click 'Save' or 'Cancel'

Post-conditions

You have linked one library shape to a GLPI table