Skip to main content
Version: Any 26

Sync API

The synchronization API feeds Any from a source repository (a third-party ECM, a document database, a business application) without going through the REST API. Your Java program builds one message per document, with its metadata, contents and relations, then queues it. Any consumes the queue asynchronously and creates or updates the documents.

To migrate large volumes of existing documents, prefer the bulk import; to import from CSVs, Documentum, SharePoint or a file system without programming, see the File system importer. To drive Any synchronously, see the REST API.

The destination of the message depends on the archive you add to the classpath: the SaaS offer or an on-premise installation.

Archive content and configuration​

The API is delivered as one archive per type of environment:

  • Any_Sync_API_aws_<version>.zip for the SaaS offer;
  • Any_Sync_API_local_<version>.zip for an on-premise installation.

Each archive contains the messaging provider jar, provider-awsMessagingProvider or provider-jmsMessagingProvider, with all its dependencies, including provider-messagingAPI which holds the interfaces needed to build the message. Add the whole content of the archive to the classpath, not only the Any jars.

The jars contain no settings.json file: add your own to the classpath, describing the connection.

SaaS offer. Your account manager provides the credentials and the connection settings of your hosted environment. The file looks like this:

{
"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"
}
}
}

Queues are FIFO: the name of every queue must end with the .fifo suffix. With a queue lacking this suffix, documents may be created twice and, during a large synchronization, the version tree may be wrongly detected.

On premise. The file names the ActiveMQ server and the queues to use:

{
"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"
}
}

Building a message​

Create an IMessageSynchronization object for each document:

IMessageSynchronization msg = new MessageSynchronization();

Operation. It tells Any what to do with the document:

  • ADD: creates the document. If a document with the same identifier already exists, the synchronization of that document is skipped;
  • REPLACE: replaces the document with the same identifier, or creates it if it does not exist. If the message contains contents or relations, all those already present are removed and replaced by the ones sent;
  • UPDATE: updates the document with the same identifier. Only the metadata sent is modified, you do not need to send all of it;
  • REMOVE: deletes the document designated by SyncRootId and SyncObjectId.
msg.setOperation(Operation.REPLACE);

Identifiers. sync.root_id and sync.object_id keep the link with your source repository. Together they identify the document: Any uses them to know whether it already exists or which document to update.

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

If you know the identifier of the document in Any, use it instead of the two previous identifiers:

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

Metadata. Single-valued and multivalued metadata are accepted. The Any "mapping" configuration module determines which aspect metadata is initialized. The following example walks through the properties of a Documentum object:

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);

Contents. Any handles several formats for the same object: the primary format, its PDF representations or any additional format. Designate the primary format, then add each content with its file path (or null if you pass an InputStream), its format name, its DOS extension and a tag. The tag is view or edit (constants IFormat.TAG_VIEW and IFormat.TAG_EDIT) and tells whether the format is used for viewing or for editing.

msg.setPrimaryContentFormat("formatName");
  • With a file path:

    String formatID = msg.addContent(filePath, "formatName", "DosExtension", "");
    messagingProvider.queue(messagingProvider.getQueueName(QueueType.INPUT), msg);
  • With an InputStream: get the generated format identifier, associate the stream with it in a Map, then pass that Map when queuing.

    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);
  • With an external reference: Any does not store the content, it keeps a link and reaches the content directly at its original location.

    String formatID = msg.addExternalContent("formatId", "formatName", "DosExtension", 1024L);
    messagingProvider.queue(messagingProvider.getQueueName(QueueType.INPUT), msg);
  • From a source repository configured in Any: give the name of the protocol defined in the Any configuration for this type of source, and the identifier that lets Any retrieve the content from that repository.

    String formatID = msg.addContent("sourceName", "contentId", "formatName", "DosExtension", "", 1024L);
  • With an attachment: it is attached to a content and carries no metadata, apart from a name automatically extracted from the file name. Provide the file, the content type and the DOS extension.

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

Monitoring properties. Three properties help monitor a synchronization: Source names the origin repository, BatchNumber identifies a batch and SentBy gives the sender displayed in Any.

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

Room. To attach the document to a room, give its identifier: the link is static (without a collection). You can call the method several times for several rooms.

msg.addRoom("demo_room__room0001");

Ignore existing. With the ADD operation, a document already present with the same identifiers is skipped. With setIsIgnoreExisting(true), Any does not look for an existing one: the document is always created.

msg.setIsIgnoreExisting(true);

Task. To attach the document to a task created in Any, give its type and its recipients (user identifiers). Without a recipient, the task is assigned to admin.

  • task_indexing: the user completes the document's metadata; Any then updates its locations accordingly;
  • task_authoring: the recipients take part in writing the document; accepting the task sends the document to the export queue (output), for processing by a custom development;
  • task_distribution: the document distribution task.
msg.setTaskType("task_indexing");
msg.setTaskRecipients(Arrays.asList("john.doe", "jane.doe"));

Relation. A relation is declared on the parent, only in the parent-to-child direction. Since the Any identifier of the target is unknown, it is designated by its SyncRootId and, optionally, its version; without a version, the relation does not target a specific version. If the target document cannot be found, the relation is not displayed: you can therefore push it before the target is synchronized. With the REPLACE operation, the relations sent replace all the existing ones.

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

Package. To create a package, send a contentless object and add its components with addComponent. The second parameter, set to true, indicates that the identifier provided is the external identifier. The version tags list pins a specific version; when null, the latest version is linked to the package.

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

Comments. parentCommentId is only used to reply to an existing comment, otherwise pass null. If commentId is null, it is generated automatically.

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

Version tree. By default, Any rebuilds the version tree of the synchronized documents: two documents with the same root_id and different object_id are two versions of the same document. The highest version is the latest; it receives the latest tag in the version_tags metadata, and the older versions can no longer be edited and appear greyed out in Any. To display each version as an independent document and prevent this rebuild, call:

msg.setCreateAsNewObject(true);

Version tags. To impose the tags of the version, use setVersionTags. The latest tag remains managed by Any: it is set on the highest version and cannot be forced.

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

Sending the message​

First get the messaging provider, which matches the archive on the classpath:

IMessagingProvider messagingProvider = MessagingProviderLoader.getMessagingProvider();

Then queue the message:

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

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