Aller au contenu principal
Version: Any 26

Sync API

L'API de synchronisation alimente Any depuis un référentiel source (GED tierce, base documentaire, application métier) sans passer par l'API REST. Votre programme Java construit un message par document, avec ses métadonnées, ses contenus et ses relations, puis le dépose dans une file de messages. Any consomme la file de façon asynchrone et crée ou met à jour les documents.

Pour reprendre de gros volumes de documents existants, préférez l'import en masse ; pour importer depuis des CSV, Documentum, SharePoint ou un système de fichiers sans programmer, voir le File system importer. Pour piloter Any de façon synchrone, voir l'API REST.

La destination du message dépend de l'archive que vous ajoutez au classpath : l'offre SaaS ou une installation sur site (on premise).

Contenu de l'archive et configuration​

L'API est livrée sous la forme d'une archive par type d'environnement :

  • Any_Sync_API_aws_<version>.zip pour l'offre SaaS ;
  • Any_Sync_API_local_<version>.zip pour une installation sur site.

Chaque archive contient le jar du fournisseur de messagerie, provider-awsMessagingProvider ou provider-jmsMessagingProvider, avec toutes ses dépendances, dont provider-messagingAPI qui porte les interfaces nécessaires pour construire le message. Ajoutez au classpath tout le contenu de l'archive, pas seulement les jars d'Any.

Les jars ne contiennent aucun fichier settings.json : ajoutez au classpath le vôtre, qui décrit la connexion.

Offre SaaS. Votre responsable de compte vous fournit les identifiants et les paramètres de connexion de votre environnement hébergé. Le fichier a la forme suivante :

{
"aws-messaging": {
"s3": {
"credentials": {
"access_key_id": "[keyId]",
"secret_access_key": "[accessKey]"
},
"region": "eu-west-1",
"store": {
"bucket": "[bucketname]",
"root_directory": "sync/tmp"
}
},
"sqs": {
"credentials": {
"access_key_id": "[keyId]",
"secret_access_key": "[accessKey]"
},
"queue": {
"input": "[queueName]",
"methods": "[queueName]",
"output": "[queueName]"
},
"region": "eu-west-1"
}
}
}

Les files sont de type FIFO : le nom de chaque file doit se terminer par le suffixe .fifo. Avec une file sans ce suffixe, des documents peuvent être créés en double et, lors d'une grosse synchronisation, l'arbre des versions peut être mal détecté.

Sur site. Le fichier désigne le serveur ActiveMQ et les files à utiliser :

{
"mdb-messaging": {
"queues": [
{ "name": "input", "queue": "input" },
{ "name": "methods", "queue": "methods" },
{ "name": "output", "queue": "output" }
],
"jms_server_address": "tcp://[ActiveMQServerIP]:[ActiveMQServerPort]",
"temp_folder": "/_Dev/tmp/mdb"
}
}

Construire un message​

Créez un objet IMessageSynchronization pour chaque document :

IMessageSynchronization msg = new MessageSynchronization();

Opération. Elle indique ce qu'Any doit faire du document :

  • ADD : crée le document. S'il existe déjà un document de même identifiant, la synchronisation de ce document est ignorée ;
  • REPLACE : remplace le document de même identifiant, ou le crée s'il n'existe pas. Si le message contient des contenus ou des relations, tous ceux déjà présents sont supprimés et remplacés par ceux envoyés ;
  • UPDATE : met à jour le document de même identifiant. Seules les métadonnées envoyées sont modifiées, il n'est pas nécessaire de les envoyer toutes ;
  • REMOVE : supprime le document désigné par SyncRootId et SyncObjectId.
msg.setOperation(Operation.REPLACE);

Identifiants. sync.root_id et sync.object_id conservent le lien avec votre référentiel source. Ensemble, ils identifient le document : Any s'en sert pour savoir s'il existe déjà ou quel document mettre à jour.

msg.setSource("ExternalRepository");
msg.setSyncRootId("0000000000000");
msg.setSyncObjectId("0000000000000");
msg.setVersion("1.0");

Si vous connaissez l'identifiant du document dans Any, utilisez-le à la place des deux identifiants précédents :

msg.setSource("ExternalRepository");
msg.setAnyID("g_c_ff4e05dc-7a61-4fc8-a667-98d29461acf2");
msg.setVersion("1.0");

Métadonnées. Les métadonnées simples et multivaluées sont acceptées. Le module de configuration « mapping » d'Any détermine les métadonnées d'aspect qui sont initialisées. L'exemple suivant parcourt les propriétés d'un objet Documentum :

IMsgJsonObject properties = new MsgJsonObject();

String attrName = metadata.getName();
Object value;

// Multivalued metadata
if (isRepeating) {
List<Object> values = new ArrayList<>();
int count = metadata.getValueCount(attrName);

for (int index = 0; index < count; index++) {
if (isTime) {
Date time = metadata.getListTime(attrName, index);
value = time.getDate();
} else {
value = metadata.getListString(attrName, index);
}
if (value != null)
values.add(value);
}
properties.setList(attrName, values);
}
// Single-valued metadata
else {
if (isTime)
value = metadata.getTime(attrName).getDate();
else
value = metadata.getString(attrName);

if (value != null)
properties.set(attrName, value);
}

msg.setProperties(properties);

Contenus. Any gère plusieurs formats pour un même objet : le format principal, ses représentations PDF ou tout autre format complémentaire. Désignez le format principal, puis ajoutez chaque contenu avec son chemin de fichier (ou null si vous passez un InputStream), son nom de format, son extension DOS et un tag. Le tag vaut view ou edit (constantes IFormat.TAG_VIEW et IFormat.TAG_EDIT) et précise si le format sert à la consultation ou à l'édition.

msg.setPrimaryContentFormat("formatName");
  • Avec un chemin de fichier :

    String formatID = msg.addContent(filePath, "formatName", "DosExtension", "");
    messagingProvider.queue(messagingProvider.getQueueName(QueueType.INPUT), msg);
  • Avec un InputStream : récupérez l'identifiant de format généré, associez-y le flux dans une Map, puis passez cette Map à la mise en file.

    Map<String, InputStream> contents = new HashMap<String, InputStream>();
    String formatID = msg.addContent(null, "formatName", "DosExtension", "");
    contents.put(formatID, inputStream);
    messagingProvider.queue(messagingProvider.getQueueName(QueueType.INPUT), msg, contents);
  • Avec une référence externe : Any ne stocke pas le contenu, il conserve un lien et y accède directement à son emplacement d'origine.

    String formatID = msg.addExternalContent("formatId", "formatName", "DosExtension", 1024L);
    messagingProvider.queue(messagingProvider.getQueueName(QueueType.INPUT), msg);
  • Depuis un référentiel source configuré dans Any : indiquez le nom du protocole défini dans la configuration d'Any pour ce type de source, et l'identifiant qui permet à Any de récupérer le contenu dans ce référentiel.

    String formatID = msg.addContent("sourceName", "contentId", "formatName", "DosExtension", "", 1024L);
  • Avec une pièce jointe : elle se rattache à un contenu et ne porte aucune métadonnée, hormis un nom extrait automatiquement du nom de fichier. Fournissez le fichier, le type de contenu et l'extension DOS.

    String formatID = msg.addAttachment(filePath, "formatName", "DosExtension");

Propriétés de suivi. Trois propriétés facilitent la supervision d'une synchronisation : Source nomme le référentiel d'origine, BatchNumber identifie un lot et SentBy donne l'expéditeur affiché dans Any.

msg.setSource("ExternalRepository");
msg.setBatchNumber("Batch-0001");
msg.setSentBy("My integration");

Room. Pour rattacher le document à une room, indiquez son identifiant : le lien est statique (sans collection). Vous pouvez appeler la méthode plusieurs fois pour plusieurs rooms.

msg.addRoom("demo_room__room0001");

Ignorer l'existant. Avec l'opération ADD, un document déjà présent avec les mêmes identifiants est ignoré. Avec setIsIgnoreExisting(true), Any ne cherche pas s'il existe : le document est toujours créé.

msg.setIsIgnoreExisting(true);

Tâche. Pour rattacher le document à une tâche créée dans Any, indiquez son type et ses destinataires (identifiants des utilisateurs). Sans destinataire, la tâche est affectée à admin.

  • task_indexing : l'utilisateur complète les métadonnées du document ; Any met ensuite à jour ses emplacements en conséquence ;
  • task_authoring : les destinataires participent à la rédaction du document ; l'acceptation de la tâche envoie le document dans la file d'export (output), pour un traitement par un développement spécifique ;
  • task_distribution : la tâche de diffusion du document.
msg.setTaskType("task_indexing");
msg.setTaskRecipients(Arrays.asList("john.doe", "jane.doe"));

Relation. Une relation se déclare sur le parent, uniquement dans le sens parent vers enfant. L'identifiant Any de la cible étant inconnu, on la désigne par son SyncRootId et, facultativement, sa version ; sans version, la relation ne vise pas une version précise. Si le document cible est introuvable, la relation n'est pas affichée : vous pouvez donc la pousser avant que la cible soit synchronisée. Avec l'opération REPLACE, les relations envoyées remplacent toutes les relations existantes.

msg.addRelatedChild("is_related_to", "childId", versions);

Package. Pour créer un package, envoyez un objet sans contenu et ajoutez ses composants avec addComponent. Le deuxième paramètre, à true, indique que l'identifiant fourni est l'identifiant externe. La liste de tags de version fige une version précise ; à null, c'est la dernière version qui est liée au package.

msg.addComponent("00000000000", true, null);

Commentaires. parentCommentId ne sert que pour répondre à un commentaire existant, sinon passez null. Si commentId est null, il est généré automatiquement.

msg.addComment(String parentCommentId, String commentId, String userId, String comment, Date creationDate);

Arbre des versions. Par défaut, Any reconstruit l'arbre des versions des documents synchronisés : deux documents de même root_id et de object_id différents sont deux versions d'un même document. La version la plus haute est la dernière ; elle reçoit le tag latest dans la métadonnée version_tags, et les versions plus anciennes ne sont plus modifiables et apparaissent grisées dans Any. Pour afficher chaque version comme un document indépendant et empêcher cette reconstruction, appelez :

msg.setCreateAsNewObject(true);

Tags de version. Pour imposer les tags de la version, utilisez setVersionTags. Le tag latest reste géré par Any : il est posé sur la version la plus haute et ne se force pas.

msg.setVersionTags(Arrays.asList("approved"));

Envoyer le message​

Récupérez d'abord le fournisseur de messagerie, qui correspond à l'archive présente dans le classpath :

IMessagingProvider messagingProvider = MessagingProviderLoader.getMessagingProvider();

Mettez ensuite le message en file :

// Content passed as InputStream
messagingProvider.queue(messagingProvider.getQueueName(QueueType.INPUT), msg, contents);

// Content passed as file path
messagingProvider.queue(messagingProvider.getQueueName(QueueType.INPUT), msg);