Champ sélecteur simple SQL

Présentation générale

L’objectif de ce sélecteur SQL simple est de :

• permettre la sélection de données externes, issues d’une base de données relationnelle (sans montée en mémoire) et après sélection de mettre à jour certains champs du document de processus à partir de données récupérées depuis la requête SQL
• permettre leur affichage sous forme de vue (liste, grille, liens).

Cette page regroupe l’ensemble des informations nécessaires à la personnalisation de ce sélecteur.

Utilisation

Pour mettre en place la personnalisation, il suffit d’ajouter le champ sélecteur SQL simple dans un formulaire à l’aide Studio et créer une propriété de type Blob.

Il suffit ensuite de sélectionner une source de données (créée depuis l’administration ou d’utiliser le Gestionnaire de requêtes), de saisir :

• la requête SQL (elle doit être assez simple, sinon passer par une vue SQL) Au minimum le premier champ de la requête doit se trouver sur la même ligne que le terme “select” ;
• les paramètres en entrée ;
• les paramètres en sortie ;
• la colonne de filtre ;
• la colonne de tri ;
• et sélectionner les colonnes masquées.

Différents paramétrages générés peuvent être modifiés dans la zone Éléments XML fils de configuration.

Exemple d’éléments XML fils de configuration générés

Pour un ordre SQL simple de ce type

select id, login, firstName, lastName from vdoc_user

La zone d’Éléments XML fils de configuration affichera

<selector>
  <links>
    <link default="true" label="LG_DEFAULT_VIEW" name="defaultView">
      <view exportable="true" filterable="true" globalFilterColumns="login" name="Personne" paginable="true" provider="com.vdoc.kit.ui.providers.selectors.ExtendedQuerySelectorProvider" selectable="true" sortable="true">
        <column displaylabel="true" hidden="true" label="LG_PERSONNE_ID" name="id" zone="description" />
        <column displaylabel="true" label="LG_PERSONNE_LOGIN" name="login" zone="title" />
        <column displaylabel="true" label="LG_PERSONNE_FIRSTNAME" name="firstName" zone="description" />
        <column displaylabel="true" label="LG_PERSONNE_LASTNAME" name="lastName" zone="description" />
      </view>
    </link>
  </links>
</selector>

Utilisation dans le contexte d’une vue

À l’aide d’une fonction dans la vue

Pour afficher un champ de type Sélecteur SQL simple dans une vue, il suffit d’ajouter une colonne virtuelle et d’utiliser la fonction @VERSRESSOURCE (@TORESOURCE).

@VERSRESSOURCE(iResource; "propertyName"; "expression")

Où

• propertyName est le nom système du champ Blob
• et expression l’expression à évaluer (la colonne du SELECT).

Il faut conserver les guillemets !

En utilisant l’option “Affectation” du sous-formulaire

1. Allez dans la version du processus, dans la rubrique “champs”, et en créez un nouveau de type “texte”.
   Ce champ sera considéré “masqué” car nous ne l’utiliserons dans aucun sous-formulaire.
2. Ensuite, aller dans le diagramme du processus et accéder au sous-formulaire de l’étape contenant le Sélecteur SQL simple.
3. Cliquer sur l’élément #databaseSingleSelector afin d’ouvrir les propriétés et accéder à l’entrée “Affectation”.
4. Il suffit ensuite d’affecter à notre attribut cible (le champ caché précédemment créé) la colonne souhaitée du SELECT (visible dans la requête SQL du Sélecteur SQL simple).
5. Finalement, vous n’avez plus qu’à créer la vue en y ajoutant le champ masqué.

Avantages & inconvénients

• L’avantage principal de l’affectation est qu’elle permet, entre autres, d’effectuer des tris et des filtres sur notre colonne de vue contrairement à une colonne virtuelle qui ne le permet pas.
• Cependant, si vous ajoutez cette fonctionnalité alors que le processus contient déjà des documents, l’affectation ne permettra pas de visualiser l’information souhaitée des documents déjà existants (en effet, l’affectation se fait durant l’exécution de l’étape du workflow du processus et ne touchera donc que les nouveaux documents). La colonne virtuelle se basant directement sur le SELECT, la vue sera alors effective pour tous les documents, nouveaux comme anciens.
• Il convient donc de bien réfléchir avant de faire notre choix.

Prérequis

Affectation de valeurs aux champs du document par script

Abonnement d’un champ texte

Exemple de mise à jour des champs d’un document à partir de données récupérées depuis la requête SQL.

function onFieldChanged( field )
{
  if ( field.getName().equals("Field_DBSingle") ) // type Blob
  {
    var resource = Packages.com.vdoc.kit.utils.ConverterUtils.toResource(field.getValue());
    
    iWorkflowInstance.setValue("Field1",resource.getValue("colonneX"));
    iWorkflowInstance.setValue("Field2",resource.getValue("colonneY"));
  }
}

Abonnement d’un champ Donnée (et plus si affinité)

Présentation / Objectif du développement

Calculer un champ de donnée DU à partir d’une colonne texte retournée par un sélecteur SQL. Exemple ici : sélecteur SQL faisant une requête sur l’annuaire VDoc qui retourne un Pays (format texte) qui est ensuite transformé un champ donnée Pays (et en bonus abonnement sur le sous champ Monnaie du Pays tel que renseigné dans le DU) :

Réalisation

Administration > Créez la connexion externe à votre base de données SQL.

Studio > Créez un réservoir donnée et une table.

Studio > Allez dans le formulaire de processus puis :

• Créez un champ donnée (mono-valeur) pointant vers la table DU créée précédemment (ce champ sera calculé plus tard par script)
• Ajoutez un champ de type “Sélecteur SQL simple” (à positionner graphiquement “avant” le champ DU pour être logique / ergonomique) :
  • Créez le champ de type “Blob” associé
  • Indiquez dans ce composant, la requête SQL, dans notre cas : sql select id, login, fullName, country from vdoc_user
  • (option) Masquez la colonne “id” (utile en cas de débug uniquement)
  • (option) Dans les paramètres XML de ce composant (xml généré automatiquement), modifiez les clefs de traduction pour utiliser des clefs “existantes” (standard produit ou d’autres déjà créées en spécifique) sinon créez de nouvelles clefs de traduction. Dans notre cas, utilisation de 2 clefs standards :

<column displaylabel="true" label="LG_USER_LOGIN" name="login" zone="description" />
<column displaylabel="true" label="LG_USER_FULLNAME" name="fullName" zone="title" />

Personnalisez le code JavaScript suivant pour abonner le champ donnée (ici Pays) à partir de la valeur texte retournée par le sélecteur SQL (on s’appuie sur un viewController sur une vue du réservoir de donnée). A noter : il a 2 choix d’emplacement pour ce code JS :

1. comme ci-dessous en ajoutant une élément de script en haut de votre formulaire
2. en ajoutant ce code dans les abonnements de la version de processus dans une balise de type <script event="onChange" for="SelecteurSQLUtilisateur"

function onFieldChanged( field )
{
  if ( field.getName().equals("SelecteurSQLUtilisateur") )
  {
    if ( field.getValue() == null )
    {
      iWorkflowInstance.setValue("PaysDonnee",null);
      return;
    }

    // conversion en iResource
    var resource = Packages.com.vdoc.kit.utils.ConverterUtils.toResource(field.getValue());
    
    // récupération d'un view controller à partir de l'URI de la vue
    var viewController = Packages.com.vdoc.kit.utils.ViewUtils.getViewControllerByProtocolUri("uril://vdoc/resourceDefinitionView/DefaultOrganization/BD/DU:4/Pays/DEFAULT");
    
    // ajout de la contrainte - Partie Finale : colonne retournée par le Sélecteur SQL (ici country)
    viewController.addEqualsConstraint("sys_Title",resource.getValue("country"));
    
    // récupération du catalog DU à partir de l'URI
    var catalog = iWorkflowModule.getElementByProtocolURI("uril://vdoc/catalog/DefaultOrganization/BD/DU:4");
    
    // récupération de la donnée
    var data = Packages.com.vdoc.kit.utils.ViewUtils.evaluateFirst(viewController,catalog);
    
    // affectation
    iWorkflowInstance.setValue("PaysDonnee",data);
  }
}

Modèle de code plus générique et mieux commenté

function onFieldChanged( field )
{
  if ( field.getName().equals("[ChampBlobSelecteurSQL]") ) // Champ de type Blob
  {
    // En cas de vidage du sélecteur ...
    if ( field.getValue() == null )
    {
      iWorkflowInstance.setValue("[ChampDonneeAbonne]",null);
      return;
    }

    // conversion en iResource
    var resource = Packages.com.vdoc.kit.utils.ConverterUtils.toResource(field.getValue());
    
    // récupération d'un view controller à partir de l'URI de la vue (pour recherche dans le DU)
    var viewController = Packages.com.vdoc.kit.utils.ViewUtils.getViewControllerByProtocolUri("[URIDeLaVue]");
    
    // ajout d'une contrainte sur la vue - 1ière partie : champ de la table DU; Partie Finale : colonne retournée par le Selecteur SQL
    viewController.addEqualsConstraint("[ColonneDeRechercheDansLaDonnee]",resource.getValue("[ColonneSQLPourFiltre]"));
    
    // récupération du catalog DU à partir de l'URI
    var catalog = iWorkflowModule.getElementByProtocolURI("[URIDuCatalogDU]");
    
    // récupération de la 1ière donnée qui répond au critère
    var data = Packages.com.vdoc.kit.utils.ViewUtils.evaluateFirst(viewController,catalog);
    
    // affectation au champ du document
    iWorkflowInstance.setValue("[ChampDonneeAbonne]",data);
  }
}

Pour aller plus loin, il est aussi possible d’abonner / calculer un champ texte du document à partir d’un sous-champ de la donnée.

Par exemple ici : sélecteur SQL sur l’annuaire VDoc qui retourne un Pays (format texte) qui est transformé en Pays donnée DU (par le script ci-dessus) puis à partir du champ donnée Pays calcule d’un champ Monnaie à partir du contenu de la donnée. Pour cela indiquez simplement dans le champ (ici Monnaie) une formule de type :

Donnee.values.SousChampDeLaDonnee

Gestionnaire de requêtes SQL

L’objectif du gestionnaire de requêtes SQL est de permettre la mise en place d’une bibliothèque de requêtes SQL pouvant être utilisées par les concepteurs d’applications.

Pour créer des requêtes SQL dans la bibliothèque, aller dans l’application Studio VDoc Kit Application en cliquant sur le bouton Gérer (à la racine du Studio).

Articles complémentaires

• Sélecteur SQL multiple

Astuces