Création d'une table enregistrée Documentum

De EjnTricks

Au niveau d'une docbase, tout est objet et il est interdit d'interroger directement la base de données. En effet, cela pourrait corrompre les données, dans le cas d'un insert/update/delete malheureux, et la gestion des droits d'accès ne serait plus pris en compte. Cependant, il est parfois utile d'avoir un accès direct à cette base de données, dans le cas de table de référentiel ou d'un chrono, cf article Création d'un chrono. Mais pour ce faire, il faut respecter quelques règles et bonnes pratiques pour s'éviter de mauvaises surprises.


Hand-icon.png Votre avis

Nobody voted on this yet

 You need to enable JavaScript to vote


Study icon.png Définition

Une table enregistrée est une référence vers un objet de la base de données (table, vue ...) qui va permettre d'interroger directement les données, comme si la requête était du SQL. Comme à chaque fois, il existe un type documentum dm_registered, sous type de dm_sysobject, qui sera instancié pour chacune des tables enregistrées.

A noter que le type hérite de dm_sysobject et donc l'utilisation d'ACL est possible, ce qui sera bien utile. A cela s'ajoute quelques attributs spécifiques:

Nom Type Repeating Description
table_name CHAR(64) Non Indique le nom de l'objet dans la base.
table_owner CHAR(64) Non Indique le propriétaire de l'objet dans la base.
column_count INTEGER Non Indique le nombre de colonne
owner_table_permit INTEGER Non Permissions sur la table pour tous le propriétaire.
group_table_permit INTEGER Non Permissions sur la table pour tous le groupe associé à la table.
world_table_permit INTEGER Non Permissions sur la table pour tous les utilisateurs.
synonym_for CHAR(254) Non Indique le nom de la table liée.
column_name CHAR(64) Oui Indique le nom de la colonne
column_datatype CHAR(64) Oui Indique le type de la colonne.
column_length INTEGER Oui Dans le cas d'une chaîne de caractères, indique sa taille
is_key BOOLEAN Oui Indique si un index est posé sur la colonne.

Mais en fait, beaucoup d'attributs seront renseignés lors de la création de la table enregistrée, et suffiront largement dans le cas nominal.

Les informations sur les colonnes sont optionnelles et tout fonctionne même si elles ne sont pas renseignées:

  • column_name
  • column_datatype
  • column_length
  • is_key


Icon-database.png Création d'une table enregistrée

Le premier réflexe serait de créer une instance du type dm_registered, comme pour un document ou répertoire, à l'aide de la séquence

API> create,c,dm_registered
.
.
.
API>save,c,l

Cependant, il existe la commande DQL register qui va permettre de mettre en place la table enregistrée avec un minimum de configuration.

Prenons le cas d'une table avec le nom mycompany_users. Celle-ci contient deux colonnes de type VARCHAR2(128) firstname et lastname. La création s'effectuera donc ainsi:

DQL> register table dm_dbo.mycompany_users (firstname String(128), lastname String(128))

Dans ce cas, les informations sur les colonnes sont fournies. Cela peut être fastidieux, cela reste une bonne pratique. Cependant, si la table contient la colonne surname, il sera toujours possible de l'interroger malgré quelle ne soit pas déclarée.


Icon-database-search.png Utilisation d'une table enregistrée

L'objectif est de fournir un accès "direct" à la base de données. Il est donc possible d'écrire des requête DQL comme du SQL, à avoir:

  • Pour un SELECT: SELECT * FROM dm_dbo.<table_name> WHERE col1='val1' ...
  • Pour un INSERT: INSERT INTO dm_dbo.<table_name> (col1, col2) VALUES ('val1', 'val2')
  • Pour un UPDATE: UPDATE dm_dbo.<table_name> set col1 = 'val1' WHERE col2='val2' ...
  • Pour un DELETE: DELETE from dm_dbo.<table_name> WHERE col1='val1' ...


Icon-database-delete.png Suppression d'une table enregistrée

Comme pour la création, il est possible de supprimer une table enregistrée de trois façons:

  • commande API destroy,c,<r_object_id>.
  • commande DQL DELETE dm_registered object WHERE object_name='<table_name>'.
  • commande DQL UNREGISTER dm_dbo.<table_name>. Le préfixe dm_dbo (ou le propriétaire de la table enregistrée) n'est pas nécessaire, mais préférable, cf les bonnes pratiques.

Mais en tout état de cause, seule l'instance de dm_registered est supprimée. L'objet dans la base de données reste valide. Etant un objet de type dm_sysobject, il faut que l'ACL associée à la table enregistrée autorise la suppression, droit DELETE, sur l'objet.


Warning-icon.png Bonnes pratiques

La création de la table est donc extrêmement simple. Mais sans aucune rigueur, cela peut devenir une vraie galère à utiliser.

Icon File Owner.png Propriétaire de la table

Dans la commande présentée, la table est indiqué sous le nom dm_dbo.mycompany_users. Au niveau du serveur, la valeur dm_dbo sera automatiquement remplacée par le propriétaire de la docbase.

Il est fortement recommandé de toujours faire ainsi pour les raisons suivantes:

  • Lorsque l'on effectue un select, il faut spécifier le propriétaire de la table, sinon le serveur suppose qu'elle appartient à l'utilisateur effectuant la commande select. Et si tel n'est pas le cas, une erreur sera remontée, ce qui sera expliqué plus tard dans l'article.
  • Une table enregistrée est généralement utilisée dans du code effectuant des requêtes. Il serait fastidieux de devoir connaître le propriétaire de la table avant chaque requête. Et il est beaucoup plus simple et homogène de mettre que des requête du type select ... from dm_dbo.table_name

Icon ACL.png Droits d'accès

La gestion des droits d'accès se décompose en deux parties. La première porte sur les propriétés owner_table_permit, group_table_permit et world_table_permit. Ces trois propriétés vont permettre de spécifier si les utilisateurs déclarés peuvent effectuer les opérations parmi:

  • SELECT
  • UPDATE
  • INSERT
  • DELETE

Il faut donc spécifier une combinaison des valeurs suivantes:

Valeur Description
0 Aucun accès.
1 SELECT possible.
2 UPDATE possible.
4 INSERT possible.
8 DELETE possible.

Par exemple, il faut spécifier:

  • 5 (1 + 4) pour autoriser l'insertion et la selection.
  • 7 (1 + 2 + 4) pour l'insertion, la mise à jour et l'insertion.
  • 15 (1 + 2 + 4 + 8) pour tout autoriser.

Il faut bien avouer que cela est très puissant et sécurisant. En effet, imaginons qu'une table enregistrée soit mise en place sur une table du schéma Documentum, par exemple sur r_object_id et object_name de la table dm_sysobject_s, il pourrait être dangeureux qu'une personne effectue une requête du type INSERT ou UPDATE, car les sécurités Documentum ne seront pas prises en compte...


La deuxième définition des droits d'accès est directement liée à l'héritage du type dm_registered. Etant un type fils de dm_sysobject, il est possible de spécifier une ACL sur la table enregistrée. Par conséquent, il est important de mettre en place une ACL qui donne un droit suffisant, à savoir WRITE, aux utilisateurs devant travailler sur la table enregistrée. Le point un peu particulier est que le droit de lecture est suffisant pour effectuer des injections/mise à jour/suppression.

Il ne faut pas confondre les droits affectés par l'ACL et ceux définis par les attributs XXX_table_permit.

Mais comment cela est il utilisé ? Prenons le cas d'une requête SELECT. Pour retourner les résultats, le serveur effectue les opérations suivantes:

  • Récupération de la clause FROM afin de rechercher l'instance dm_registered dont l'object_name est égal au nom de la table, et owner_name est égal au préfixe ou le nom de l'utilisateur connecté si le préfixe n'est pas fourni, d'où l'importance de toujours enregistrer avec dm_dbo et toujours mettre cette valeur dans les requêtes. Par conséquent, si l'ACL ne donne pas le droit de lecture sur l'objet dm_registered correspondant, le serveur va considéré que la table enregistrée n'existe pas et lèvera une erreur.
  • Vérification des droits en fonction des propriétés XXX_table_permit sur l'objet dm_registered et en fonction de l'utilisateur effectuant la requête. Si l'utilisateur essaye d'effectuer une commande INSERT sans avoir le droit 8 disponible, le serveur lèvera une erreur.


C'est pourquoi, il est recommandé de toujours effectuer une requête de ce type après avoir effectué la création:

update dm_registered object 
set world_table_permit = 1, set group_table_permit = 1, set owner_table_permit = 1,
set acl_name = '<generic_registered_acl>', set acl_domain = 'dm_dbo'
where object_name = '>table_name<'

Où:

  • Les droits sont spécifiés en SELECT uniquement pour tout le monde. Il sera possible d'affiner ensuite
  • l'ACL generic_registered_acl est une ACL créé pour gérer les tables enregistrées dans la docbase. A faire à chaque projet finalement, et en général appartenant au docbase_owner, d'où set acl_domain = 'dm_dbo'.

Icon Personnalisation.png Nom des tables

Il est fortement recommandé de toujours mettre le nom des tables enregistrées en minuscule. Ainsi les développeurs n'auront aucune question à se poser, et cela est beaucoup plus homogène.

De plus, il est préférable, dans la mesure du possible, de donner le même nom sur la table enregistrée que l'objet en base.


title= Informations complémentaires

L'utilisation de la commande REGISTER est de loin la plus optimale, car nous n'avons pas à nous soucier de toutes les informations techniques. Etant un sous type de dm_sysobject, l'objet est lié à un répertoire dans la docbase. Par défaut, les instances sont stockées dans le cabinet /System.