Introduction
This tutorial will show you how to transfer document attributes into an iModel using the Synchronization API. In this tutorial, a file is synchronized from blob storage to an iModel.
Prerequisites
To store document attributes in an iModel, complete the following tasks before proceeding:
- Create an iModel.
- Create a connection.
For a detailed guide you can follow the Synchronize a file from Azure Blob Storage tutorial up to "Run a Connection" step. Once you have completed these tasks, the next steps will walk you through syncing a file along with its document attributes to an iModel.
1. Document Attributes
Most documents share a common set of general properties, such as a document name and creation date. In addition to these, you can define custom attributes for your documents.
To create and store custom attributes in an iModel, you need to define a Document Attribute schema and run a connection with the specified attributes. During the synchronization process, the connector will use the defined schema to process and insert the attributes into the iModel.
2. Define a Document Attributes schema
The document attributes schema is an ECSchema saved as a JSON file that defines custom attributes. The Synchronization API passes this schema to the file processing connector, which uses it to store document attributes in the iModel.
{
"$schema": "https://dev.bentley.com/json_schemas/ec/32/ecschema",
"name": "NAME_OF_YOUR_SCHEMA",
"version": "VERSION_OF_YOUR_SCHEMA",
"alias": "ALIAS_OF_YOUR_SCHEMA",
"label": "LABEL_OF_YOUR_SCHEMA",
"references": [{
"name": "DocumentMetadata",
"version": "01.00.00"
}],
"items": {
"NAME_OF_YOR_CLASS": {
"schemaItemType": "EntityClass",
"label": "LABEL_OF_YOUR_CLASS",
"properties": [{
"name": "NAME_OF_YOUR_PROPERTY",
"type": "PrimitiveProperty",
"label": "LABEL_OF_YOUR_PROPERTY",
"typeName": "string"
}],
"baseClass": "DocumentMetadata.DocumentLink"
}
}
}
You can read more about schema properties in the ECShema documentation. Once generated the schema should be stored at a blob storage. For the next steps, only the URL of this file will be required.
3. Run a connection with Document Attributes
A run can be manually initiated by sending a run start request. Custom attributes and their schema should be included in the request body.
Below is the schema used in this tutorial.
{
"$schema": "https://dev.bentley.com/json_schemas/ec/32/ecschema",
"name": "iModelBridge",
"version": "01.00.00",
"alias": "IMB",
"description": "This is an example of Document Attribute Schema",
"label": "iModelBridge",
"references": [{
"name": "DocumentMetadata",
"version": "01.00.00"
}],
"items": {
"IMBDocumentLink": {
"schemaItemType": "EntityClass",
"label": "IMBDocumentLink",
"properties": [{
"name": "Suitability",
"type": "PrimitiveProperty",
"label": "Suitability",
"typeName": "string"
}, {
"name": "Revision",
"type": "PrimitiveProperty",
"label": "Revision",
"typeName": "string"
}, {
"name": "DocumentType",
"type": "PrimitiveProperty",
"label": "DocumentType",
"typeName": "string"
}],
"baseClass": "DocumentMetadata.DocumentLink"
}
}
}
Request
Send a POST request to the synchronization/imodels/manifestConnections/CONNECTION_ID/runs endpoint with a valid connection ID to run a connection:
- Authorization header with valid Bearer token is required.
- CONNECTION_ID which should be started for processing.
Request Body
Request body is defined in the Create ManifestConnection Run documentation.
To store document attributes in an iModel, the following properties must be set:
documentAttributeSchemaUrl- The URL of a JSON file containing the document attribute schema, as defined in iTwin.js.documentAttribute- A document attribute consists of:className- Specifies the ECClass in the schema to be used for the document. Classes are derived from the DocumentMetadata Class.properties- Defines the properties to be set for the document. These properties are derived from both the specified class and the user-defined schema.
In the example, the document has four attributes:
CodeValue– This serves as the file correlation ID, mandatory.Revision– In the schema defined property, the revision number of the document.Suitability– In the schema defined property, the suitability of the document.DocumentType– In the schema defined property, the type of the document.
{
"documentAttributeSchemaUrl": "https://blobstoragelocation/documentAttributeSchema.json",
"sourceFiles": [{
"id": "FILE_ID",
"name": "FileName.dgn",
"url": "https://myaccount.blob.core.windows.net/files/FileName.dgn?sv=2012-02-12&st=2009-02-09&se=2009-02-10&sr=c&sp=r&si=YWJjZGVmZw%3d%3d&sig=dD80ihBh5jfNpymO5Hg1IdiJIEvHcJpCMiCMnN%2fRnbI%3d",
"connector": "MSTN",
"documentAttribute": {
"className": "ProjectwiseDynamic:PWDocumentLink",
"properties": {
"Revision": "R01",
"Suitability": "S01",
"DocumentType": "Design",
"CodeValue": "FILE_ID"
}
}
}]
}
Response
On a successful request, the operation returns HTTP status code 202 (Accepted), indicating that the request has been accepted for processing and will be executed in the background. If an active run is already in progress for this connection, a new run is added to the queue. The response includes a Location header that points to the created run.
4. Check if Document Attributes are populated successfully
You can check if custom attributes are stored in iModel in 2 ways:
- In the iModel Console, execute the query
Select * from DocumentMetaData.DocumentLinkorSelect * from NAME_OF_YOUR_SCHEMA.NAME_OF_YOUR_CLASS.
- When viewed in Design Review, the data can be accessed by clicking on an element and checking its properties under the Document Link group.
