Composants


Les composants sont les objets principaux utilisés par FlowerDocs. Grâce à l’API Javascript, ils peuvent être manipulés par des scripts pour satisfaire des besoins spécifiques dans le développement de solutions verticales.

Instancier un composant

Chaque catégorie de composant peut être manipulée à l’aide de l’API Javascript à travers un objet spécifique. Pour instancier un composant, les constructeurs suivants peuvent être utilisés :

var newDocument = new Document();
var newTask = new Task();
var newFolder = new Folder();
var newVFolder = new VirtualFolder();

Chacun de ces objets disposent de fonctions :

  • communes à tous les composants
  • spécifiques / propres à une catégorie de composant

Accès aux informations internes

Plusieurs informations sont maintenues par la plateforme FlowerDocs pour des besoins internes au fonctionnement de la plateforme. En fonction des informations, les fonctions suivantes sont exposées pour y accéder ou les modifier (quand la modification est autorisée) :

Fonctions Description
getId() Récupération de l’identifiant du composant
setId(String id) Définition de l’identifiant du composant
getName() Récupération du nom du composant
setName(String name) Définition du nom du composant
setClassId(String name) Définition de la classe du composant
getClassId() Récupération de l’identifiant de la classe de composant
String getCategory() Récupération de la catégorie
getACL() Récupération de l’ACL référencée par le composant
setACL(String aclId) Définition de l’ACL à appliquer
getStatus() Récupération du statut du composant
setStatus(String status) Définition du statut du composant (cf. Javadoc)
getVersion() Récupération de la version du composant
setVersion(long version) Définition de la version du composant
getCreationDate() Récupération de la date de création du composant
getLastUpdateDate() Récupération de la date de mise à jour du composant
getOwner() Récupération du propriétaire du composant

Gestion des tags

Les tags d’un composant peuvent être manipulés grâce à l’API Javascript à l’aide de plusieurs fonctions. La fonction getTags() permet de déterminer les tags déjà présents sur un composant en retournant un tableau contenant les noms de chacun des tags d’un composant.

Ajout ou modification d’un tag

Pour ajouter un tag sur un composant, la fonction addTag(name, value, readonly) peut être utilisée. Le deuxième paramètre value peut être une chaîne de caractères ou un tableau de chaînes de caractères pour définir plusieurs valeurs.

L’utilisation de cette fonction pour un tag déjà présent sur le composant écrase les valeurs existantes. Elle permet ainsi de modifier les valeurs d’un tag.

Le troisième paramètre readonly est un booléen permettant d’indiquer si le tag doit être affiché en lecture seule ou non.

Récupération d’un tag

Afin d’accéder aux valeurs d’un tag présent sur un composant, les fonctions getTagValue(name) et getTagValues(name) sont exposées sur l’objet composant. La première retourne la première valeur d’un tag (chaîne de caractères), la seconde retourne un tableau contenant l’ensemble des valeurs d’un tag.


Récupération de la valeur d'un tag sur une tâche

var task = new Task();
task.addTag("Montant", "1234", false);
if(task.getTags().includes("Montant")){
    console.info('Le montant est de ' + task.getTagValue("Montant"));
}


Les classes de composants définissent des typologies de composants. Grâce à l’API Javascript, elles peuvent être manipulées par des scripts pour accéder au modèle de données d’un scope.

Récupérer une classe de composants

Chaque catégorie de classe de composants peut être manipulée à l’aide de l’API Javascript à travers un objet spécifique. Une instance de cet objet peut être récupérée avec les fonctions suivantes :

  • Classe de documents : JSAPI.get().documentClass()
  • Classe de dossiers : JSAPI.get().folderClass()
  • Classe de dossiers virtuels : JSAPI.get().virtualFolderClass()
  • Classe de tâches : JSAPI.get().taskClass()


A partir de cet objet, il est possible de récupérer des classes de composants d’une même catégorie. Pour cela, une fonction get est exposée. Elle permet d’interroger en premier lieu le cache côté client. Si une ou plusieurs classes n’ont pas déjà été mises en cache, les services exposés par FlowerDocs Core seront interrogés pour récupérer les classes manquantes.

JSAPI.get().documentClass().get(["Document"], 
	function(classes){
		console.info("Success!");
	},
	function(error){
		console.error("Document classes could not be got: " + error);
	}
);

Informations d’une classes de composants

Les classes de composants disposent d’informations utilisées par le Core ou l’interface graphique. Elles peuvent être récupérées à l’aide des fonctions suivantes :

Fonctions Description
getId() Récupération de l’identifiant de la classe de composants
getLocalizedDisplayName() Récupération du nom de la classe internationalisé en fonction de la langue de l’utilisateur courant
getLocalizedDescription() Récupération de la description de la classe internationalisée en fonction de la langue de l’utilisateur courant
getTagReferences() Récupération des références de tag portées par la classe de composants

Accès aux références de tags

Chaque classe de composants détient une liste de références de tags. Ces références permettent d’associer des classes de tags à une typologie de composant.

A partir d’une classe de composants, la fonction getTagReferences() expose les références de tags sous la forme d’un tableau d’objets. Pour chacun de ces objets, les fonctions suivantes peuvent être utilisées :

Fonctions Description
getTagName() Récupération du nom de la référence de tag
getLocalizedDescription() Récupération de la description de la référence internationalisée en fonction de la langue de l’utilisateur courant
getPattern() Récupération du pattern de la référence de tag
getDefaultValue() Récupération de la valeur par défaut de la référence de tag
getOrder() Récupération de la position de la référence de tag
isMandatory() Détermine si le tag est obligatoire
isMultivalued() Détermine si le tag est multivalué
isReadonly() Détermine si le tag est en lecture seule
isTechnical() Détermine si le tag est technique


Cette section décrit comment consommer les services exposés par FlowerDocs directement depuis l’API JS.

Accès à un service de composants

Tout comme la couche de service, un service par catégorie de composant est mis à disposition :

  • Document : JSAPI.get().document()
  • Dossier : JSAPI.get().folder()
  • Dossier virtuel : JSAPI.get().virtualFolder()
  • Tâche : JSAPI.get().task()

Ces services consomment les web services SOAP exposés par FlowerDocs Core, leurs utilisations impliquent donc l’application des mêmes contrôles de cohérence et de sécurité.


Chaque fonction exposée par ces services accepte deux paramètres de type fonction :

  • successCallback : un callback exécuté en cas de succès
  • errorCallback : un callback, optionnel, exécuté en cas d’erreur

Créer des composants

Après l’instanciation d’un objet composant et l’avoir initialisé, il est possible de le créer dans FlowerDocs à l’aide du service approprié. Les services de composants exposent la fonction create(components, successCallback, errorCallback). Le premier paramètre de cette fonction correspond à un tableau des composants à créer. Le paramètre successCallback est une fonction appelée de manière asynchrone en cas de succès de la création avec en paramètre le tableau des composants créés. Le troisième paramètre errorCallback est une fonction facultative exécutée si une erreur survient.


var folder = new Folder();
folder.setName('Mon dossier');
folder.setClassId('Folder');
JSAPI.get().folder().create([folder], function (created) {
  console.info('Le dossier ' + created[0].getName() + ' a été créé');
}, function(error){
  console.error(error);
});

Récupérer des composants

Un service de composant permet de récupérer, à partir des services exposés par FlowerDocs Core, des composants stockés. Le premier paramètre ids à fournir est un tableau des identifiants des composants à récupérer. Les deux autres paramètres de type fonction peuvent être fournis pour réagir respectivement au succès et à une erreur de l’opération.


JSAPI.get().document().get([id], function (documents) {
  console.info('Le document ' + documents[0].getName() + ' a été récupéré');
}, function(error){
  console.error(error);
});

Un composant peut également être récupéré de manière dynamique en fonction de sa catégorie :

var reference = new ComponentReference(id, 'DOCUMENT');
JSAPI.get().getComponentGetAPI().getComponent(reference.getCategory(), reference.getId(), function (doc) {
  console.info('Le document ' + doc.getName() + ' a été récupéré');
}, function(error){
  console.error(error);
});

Rechercher des composants

Des composants peuvent être recherchés à l’aide des services de composants et d’un objet SearchRequest fourni en paramètre de la fonction search(request, successCallback, errorCallback).

La paramètre successCallback est une fonction appelée une fois que la recherche a abouti avec le tableau des résultats trouvés en accord avec la requête fournie. De manière optionnelle, la fonction errorCallback peut être passée en paramètre pour réagir à une éventuelle erreur.

Mettre à jour des composants

Tout comme les services de composants permettent la création de composants, il est possible de les utiliser pour mettre à jour des composants. Pour cela, la fonction update(components, successCallback, errorCallback) est exposée. Elle s’utilise de la même façon que la fonction de création.


JSAPI.get().document().get([id], function (documents) {
    documents[0].setName("updated");
    JSAPI.get().document().update([documents[0]], function (updated) {
        console.info('Le document ' + updated[0].getName() + ' a été mis à jour');
    });
});

Supprimer des composants

Afin de supprimer de manière physique (ou définitive) des composants, la fonction doDelete(ids, successCallback, errorCallback) est mise à disposition. Le premier paramètre ids à fournir est un tableau des identifiants des composants à supprimer. Les deux autres paramètres de type fonction peuvent être fournis pour réagir respectivement au succès et à une erreur de l’opération.

Attention cette opération est irréversible, elle doit donc être utilisée avec précaution.


JSAPI.get().document().doDelete([id], function () {
    console.info('Le document ' + id + ' a été supprimé définitivement');
});

Manipuler les fichiers

En plus des tags associés à un document, des fichiers peuvent lui être associés. L’API Javascript permet leurs manipulations à travers différentes fonctions de consultation ou de modification.

Accès aux fichiers

A partir d’un objet Document, la fonction getDocumentFiles() expose un tableau d’objets DocumentFile à partir desquels les fonctions suivantes peuvent être utilisées :

Fonctions Description
getId() Récupération de l’identifiant du fichier
setId(String id) Définition de l’identifiant du fichier
getName() Récupération du nom du fichier
setName(String name) Définition du nom du fichier
getFormatCode() Récupération du format du fichier
setFormatCode(String formatCode) Définition du format du fichier
getCreationDate() Récupération de la date de création du fichier

var doc = JSAPI.get().getLastComponentFormAPI().getComponent();
doc.getDocumentFiles().forEach(function(file){
   console.info('The document has file: '+file.getId());
});

Les identifiants des fichiers peuvent également être récupérés, depuis un document, à l’aide de la fonction getFiles().

Modification des fichiers

La liste des fichiers d’un objet Document peut être initialisée ou modifiée à l’aide de l’API Javascript. Pour cela, les fonctions addFile(tempFileId) ou setFiles(tempFileIds) peuvent être utilisées. Les modifications apportées à l’objet seront prises compte uniquement dans le cas d’une création de document.


function createDocument(tempFileId, callback){
    var doc = new Document();
    doc.setName('Mon document');
    doc.setClassId('Document');
    doc.addFile(tempFileId);
    JSAPI.get().document().create([doc],function(created){
        callback(created[0]);
    });
}
function uploadTextFile(text, callback){
    var formData = new FormData();
    formData.append('file', new File([new Blob([text])], 'my-file.txt'));
    $.ajax({
        url: './upload',
        data: formData,
        processData: false,
        contentType: false,
        type: 'POST',
        success: function (data) {
            callback(data.split('|')[0]);
        }
    });   
}

uploadTextFile('Some text content', (tempFileId)=>{
    createDocument(tempFileId,(doc)=>{
        JSAPI.get().getNavigationAPI().goToComponentPlace(doc.getCategory(), doc.getId(), false);
    });
});

Versioning

Si la gestion de version (ou versioning) est activé pour un document, les informations liées à ses différentes versions peuvent être consultées grâce aux fonctions suivantes :

Fonctions Description
getVersionSeriesId() Récupération de l’identifiant de VersionSeries
getVersionLabel() Récupération du libellé de la version courante
isCurrentVersion() Détermine si le document est la version courante

Un dossier peut contenir des composants : ses enfants. Les enfants d’un dossier peuvent être des composants de n’importe qu’elle catégorie mais uniquement les documents et sous-dossiers sont affichés dans FlowerDocs GUI.

Fonctions Description
addChildren(String folderId, ComponentReference[] children, boolean replace) Ajout d’enfants à un dossier
deleteChildren(String folderId, ComponentReference[] children) Suppression d’enfants d’un dossier

Ajout de contenu

Afin d’ajouter un composant dans un dossier, il est nécessaire de le référencer comme enfant du dossier à l’aide d’un objet ComponentReference. A partir de cette référence, la fonction addChildren(id, childReferences, replace, successCallback) exposée par le service JSAPI.get().folder() peut être utilisée. Le booléen replace permet d’indiquer si le contenu du dossier doit être remplacer par les nouveaux enfants référencés.


var childReference = new ComponentReference("documentId", "DOCUMENT");
JSAPI.get().folder().addChildren("folderId", [childReference], false, function(){
    console.info("The document has been added as child");
});

Suppression de contenu

Un composant peut être supprimé d’un dossier afin qu’il ne soit plus référencé comme un de ses enfants grâce à la fonction deleteChildren(folderId, childReferences, successCallback)


var childReference = new ComponentReference("documentId", "DOCUMENT");
JSAPI.get().folder().deleteChildren(folderId, [childReference], function () {
    console.info('The document has been removed from folder');
});

Manipuler les pièces jointes

Afin de contextualiser le traitement d’une tâche, des composants peuvent être attachés à une tâche. C’est la notion de pièce jointe. Les pièces jointes d’une tâche peuvent être manipulées à l’aide de l’API Javascript.

L’ajout de composants en tant que pièces jointes d’une tâche peut être réalisé à l’aide des deux fonctions suivantes :

  • addAttachment(attachmentId, componentId, category) pour attacher un seul composant à partir de son identifiant componentId
  • addAttachments(attachmentId, componentIds, category) pour attacher plusieurs composants à partir de leur identifiant fourni dans un tableau componentIds

L’utilisation de ces fonctions nécessitent en entrée l’identifiant de la pièce jointe et la catégorie de composant attendue (définies sur la classe de tâche). Les modifications des pièces jointes d’une tâche nécessitent d’être sauvegardées à l’aide des fonctions create ou update exposées par l’objet JSAPI.get().task().


JSAPI.get().task().get([id], function (tasks) {
    let task = tasks[0];
    task.addAttachments('Appendices', documentId, 'DOCUMENT');
    JSAPI.get().task().update([task], function (updated) {
        console.info('The document has been attached to task');
    });
});

Sur le même principe, les identifiants des composants attachés à une tâche peuvent être récupérés à l’aide de la fonction getAttachmentIds() exposée sur l’objet Task.

Répondre à des tâches

La notion de réponses à une tâche permet aux utilisateurs de prendre des décisions sur le traitement de tâches. Pour chaque décision prise, un comportement spécifique peut être ainsi ajouté pour prendre en compte cette décision et appliquer le traitement adéquat.

Une réponse peut être appliquée à une ou plusieurs tâches à l’aide de la fonction answer(ids, answer) avec pour paramètres :

  • un tableau d’identifiants de tâches
  • un objet Answer (ou ReasonedAnswer) représentant la réponse à appliquer

var taskAPI = JSAPI.get().task();
taskAPI.answer([id], new Answer("Validate"), function(){
    JSAPI.get().getNotificationAPI().sendInformation("Answer was applied");
});

Assignation de tâches

Assigner des tâches

Une tâche doit être assignée à un utilisateur afin d’être traitée. FlowerDocs met ainsi à disposition plusieurs mécanismes d’assignation dont fait partie l’API JavaScript. La fonction assign(ids, userId) permet d’assigner une ou plusieurs tâches à un utilisateur à l’aide de :

  • un tableau d’identifiants de tâches
  • l’identifiant de l’utilisateur auquel assigner les tâches

JSAPI.get().task().assign([id], 'sarah.hubert', function () {
    console.info('The task ' + id + ' has been assigned');
});

L’utilisateur auquel une tâche est assignée peut être récupéré grâce à la fonction getAssignee() exposée sur l’objet Task.

Réagir à une assignation

L’assignation d’une tâche à un utilisateur peut nécessiter dans certains cas des actions au niveau de l’interface graphique. Pour cela, l’API JavaScript met à disposition des hooks permettant de réagir au lancement du processus d’assignation par une action native de l’interface graphique :

  • depuis un formulaire d’indexation avec les actions d’assignation et d’appropriation
  • depuis le menu contextuel ouvert à partir de résultats de recherche avec ces mêmes actions


Ces hooks permettent de réagir ou interrompre le processus en réagissant avant l’envoi de la requête à FlowerDocs Core ou après. Un hook d’assignation est une fonction prenant en entrée les trois paramètres suivants (fournis par FlowerDocs GUI) :

  • un tableau des tâches à assigner
  • l’identifiant de l’utilisateur auquel assigner les tâches
  • un objet executor permettant de bloquer l’exécution de l’assignation et/ou de la reprendre par la suite avec son contexte

JSAPI.get().task().registerBeforeAssign(function(tasks, assignee, executor){
  // Action à effectuer avant l'assignation
});

JSAPI.get().task().registerAfterAssign(function(tasks, assignee, executor){
  // Action à effectuer après le processus d'assignation
});

L’objet executor fourni en entrée du hook permet de bloquer le processus d’assignation afin d’attendre l’exécution d’un traitement asynchrone. En effet, lorsqu’un traitement asynchrone doit être finalisé avant la reprise du processus d’assignation, il est possible de l’interrompre en appelant la fonction executor.hold() et de le reprendre une fois terminé avec executor.resume().

Dans les exemples ci-dessous, le traitement asynchrone est simulé par l’utilisation d’un timeout de 5 secondes :


JSAPI.get().task().registerBeforeAssign(function(tasks, assignee, executor){
    executor.hold();
    setTimeout(function(){
      executor.resume();
    }, 5000);
});

JSAPI.get().task().registerAfterAssign(function(tasks, assignee, executor){
    executor.hold();
    setTimeout(function(){
      executor.resume();
    }, 5000);
});

Informations liées à un processus

Fonctions Description
getWorkflow() Déterminer l’identifiant du traitement de la tâche
setWorkflow(String workflow) Définir l’identifiant du traitement de la tâche
getParticipants() Déterminer les identités ayant participées au traitement
addParticipant(String participant) Ajout d’un participant à une tâche