Upload Component to a Catalog

Introduction

This tutorial will take you through the process of uploading a component to a catalog in an organization.

By the end of this walk-through, you will be able to utilize the API endpoints in order to upload components to a catalog and associate additional documents to the uploaded component.

Info

Skill level:

Basic

Duration:

20 minutes

Prerequisites

This tutorial assumes that you already have:

A tool such as Postman that can be used to execute http calls. These calls can also be made using the TryIt button in the API documentation.
User must be affiliated with an Organization and should either be an Organization Administrator or have “Upload” and “Read” permission at Organization level to upload components to catalog.
For more information about User Management please visit our Bentley Communities Licensing, Cloud, and Web Services wiki page.
A design file is required to upload a component. Design file is a CAD file, used in CAD applications i.e. MicroStation, Revit etc. Library API supports three types of files to upload a component i.e. rfa, dgn and cel.
In this example we will upload a component from rfa file, though dgn and cell files can also be used to upload the component with same steps. You should have one of these files to upload a component.

Postman

Get

You will need to register an application to use the iTwin Platform APIs. You can use the Register button to automatically create your first single page application (SPA). This will allow you to configure Authorization Code Flow for your SPA application and get the correct access token.

Once generated, you will be shown a few lines of code under the button.

IMJS_AUTH_CLIENT_CLIENT_ID - this is the unique identifier for your application. Displayed on application details page as Client ID.
IMJS_AUTH_CLIENT_REDIRECT_URI - specifies where users are redirected after they have chosen whether or not to authenticate your app. Displayed on application details page as one of Redirect URIs.
IMJS_AUTH_CLIENT_LOGOUT_URI - specifies where users can be returned to after logging out. Displayed on application details page as one of Post logout redirect URIs.
IMJS_AUTH_CLIENT_SCOPES - list of accesses granted to the application. Displayed on application details page as Scopes.

Or optionally: Register and configure your application manually following instructions in Register and modify an Application tutorial. Make sure that your application is associated with iModels, Library, RealityData and Storage APIs and has realitydata:read imodels:read imodels:modify library:read library:modify storage:read storage:modify scopes enabled.

Register a basic SPA App for this tutorial

Requires you to sign in. Will automatically generate a Single page application (SPA) that is required to complete this tutorial. You will be able to manage your SPA from your My apps page.

2. Get a token

Before you can make a request to the APIs, a user token is needed. There are several ways to get it.

Implement Authorization Code Flow in the application

Follow this article to implement Authorization code workflow in your application.

Here you can use Client ID generated from previous registration step.

Grab a user token from Api reference “Try it” Section

Go here
Click Try it button.
Under the Authorization section, select authorizationCode from the dropdown.
After the sign in popup closes, the Authorization header with token value should be visible beneath the HTTP request dropdown.
Copy & paste the Authorization value for this tutorial.

Use user token to replace JWT_TOKEN dynamic parameter in the next steps.

3. Create a new Catalog

The Library API is used to create and manage catalogs. A POST call to the https://api.bentley.com/library/catalogs endpoint will create a new catalog. Only displayName is required for creating a new catalog. It must be unique so if you get a Conflict error then you will need to replace displayName with unique value. See the Library API documentation for descriptions of the different properties.

The POST call will return a new catalog instance. The id can be used to upload component to the catalog. The catalog Id is also used in other Library API endpoints. You may want to save this Id to use in other endpoints.

In case you already have id of an existing catalog, it can be used to upload the component, instead of creating a new catalog.

Request Syntax

HTTP

POST https://api.bentley.com/library/catalogs HTTP/1.1

Request Headers

HTTP

Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Request Body

JSON

{
    "displayName": "Tutorial Sample Catalog",
    "description": "Tutorial Sample Description",
    "region": "US",
    "hashtags": ["SampleHashtag1", "SampleHashtag2"]
}

Response Headers

HTTP

HTTP/1.1 201 Created
content-length: 937
content-type: application/json
date: Thu, 24 Jun 2021 14:44:18 GMT
request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: 5262b13f-394e-49b8-95ea-a5361d2513a3
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US

Response Body

JSON

{
    "catalog": {
      "id": "7f427c30-8dce-4803-81dc-e8681a3bd757",
      "displayName": "Tutorial Sample Catalog",
      "description": "Tutorial Sample Description",
      "region": "US",
      "createdDateTime": "2021-09-06T06:03:56.1923267Z",
      "lastModifiedDateTime": "2021-09-06T06:03:56.1923267Z",
      "hashtags": ["SampleHashtag1", "SampleHashtag2"]
    }
}

4. Referenced Entities

A component can have referenced entities i.e. Category, Application and Manufacturer. These are optional properties of a component to be uploaded, in case this information is not provided with request body, upload process will try extract the same from the design file, provided design file contains this information.

The Library API provides endpoints to create and manage these referenced entities. For this example, we will not use referenced entities in the upload and instead make use of information provided in the design file.

You can use following TryIt options in the Library API documentation to create these entities.

Library API documentation to create Category

Library API documentation to create Application

Library API documentation to create Manufacturer

5. Upload Component

A component can be uploaded using rfa, dgn or cel file. In this example we will use rfa file to upload component to the catalog. Upload component is a multi-step process. Make an upload request with upload request body, then upload the design file and/or TypeCatalog file and after that you can optionally add any additional reference documents to the newly uploaded component. TypeCatalog files are only used optionally with rfa files, so this will not be required in case of dgn or cel files.

5.1 Make Upload Component Request

In the first step, create upload component request body and make a POST call to https://api.bentley.com/library/upload-component endpoint. There is an option to make component a “TypeCatalog” component by setting isTypeCatalog property to true. A TypeCatalog Component expects to upload a text file (must have txt extension) as well along with the design file.

In this example we will use TypeCatalog component. Only fileName and catalogIds is required to upload a component to a catalog, in case catalogIds not provided, component will be uploaded to user organization and won’t belong to any catalog. Provide catalog Id (retrieved in previous steps) to catalogIds field, this field expects a collection of catalogIds, in case a component should be uploaded to multiple catalogs, you can provide multiple catalog Ids in this field.

Upload is a long running activity and response contains location header value, this will be used to track the progress. You may want to save this header value, which will be used in next steps.

See the Library API documentation for descriptions of the different properties.

Request Syntax

HTTP

POST https://api.bentley.com/library/upload-component HTTP/1.1

Request Headers

HTTP

Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Request Body

JSON

{
    "fileName": "TutorialSampleFile.rfa",
    "componentName": "Tutorial Sample Component",
    "description": "Tutorial Sample Description",
    "searchTags": [
        "SampleTag1",
        "SampleTag2"
    ],
    "catalogs": [
        "7f427c30-8dce-4803-81dc-e8681a3bd757"
    ],
    "category": null,
    "application": null,
    "manufacturer": null,
    "isTypeCatalog": true
}

Response Headers

HTTP

HTTP/1.1 202 Accepted
content-length: 973
date: Mon, 06 Sep 2021 15:05:38 GMT
location: https://api.bentley.com/library/jobs/2517713600604274285_b4ac4d02-bc16-48a3-a468-b277ea74a7cb
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
x-correlation-id: 2d4f3784-74c9-4e8d-bf81-939a27b16f54
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US

Response Body

JSON

{
    "uploadComponent": {
        "fileName": "TutorialSampleFile.rfa",
        "componentName": "Tutorial Sample Component",
        "description": "Tutorial Sample Description",
        "sessionId": "70f72644-ef2f-4673-a327-ff0140b448a8",
        "searchTags": ["SampleTag1", "SampleTag2"],
        "isTypeCatalog": true,
        "_links": {
            "catalogs": [{
                "href": "https://api.bentley.com/library/catalogs/7f427c30-8dce-4803-81dc-e8681a3bd757"
            }],
            "typeCatalogUploadUrl": {
                "href": "https://componentscenprodeussa01.blob.core.windows.net/private-temporary-type-catalog-files/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288.typecatalog?sv=2018-03-28&sr=b&sig=cpt24N23osjV3be6KmAHU2T%2FweVO0%2Fb%2FcRLFS3nQYW0%3D&se=2021-09-06T16%3A15%3A22Z&sp=rcw"
            },
            "designFileUploadUrl": {
                "href": "https://componentscenprodeussa01.blob.core.windows.net/private-temporary-design-files/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288.design?sv=2018-03-28&sr=b&sig=xJGhNSl5Ti0VHvIdhcqqRws6d7zgxMyK05xAwgrSrx4%3D&se=2021-09-06T16%3A15%3A22Z&sp=rcw"
            }
        }
    }
}

5.2 Upload Files

Response from upload request contains temporary urls to upload files under _links property value. Please note in this case there are two urls. _links->designFileUploadUrl to upload the design file and since this is a TypeCatalog Component, there is another url _links->typeCatalogUploadUrl to upload TypeCatalog text file. In case isTypeCatalog property is set to false in upload request, response will have only one file upload url _links->designFileUploadUrl. TypeCatalog text file must be uploaded before uploading the design file.

File upload can be done by making a Http PUT request on the provided url via tool such as Postman or programmatically use Azure libraries to upload file (https://docs.microsoft.com/en-us/rest/api/storageservices/put-blob).

Request Syntax

HTTP

PUT https://componentscenprodeussa01.blob.core.windows.net/private-temporary-type-catalog-files/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288.typecatalog?sv=2018-03-28&sr=b&sig=cpt24N23osjV3be6KmAHU2T%2FweVO0%2Fb%2FcRLFS3nQYW0%3D&se=2021-09-06T16%3A15%3A22Z&sp=rcw HTTP/1.1

Request Headers

HTTP

x-ms-blob-type: BlockBlob

Request Body

HTTP

TypeCatalog File Binary Content

Request Syntax

HTTP

PUT https://componentscenprodeussa01.blob.core.windows.net/private-temporary-design-files/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288.design?sv=2018-03-28&sr=b&sig=xJGhNSl5Ti0VHvIdhcqqRws6d7zgxMyK05xAwgrSrx4%3D&se=2021-09-06T16%3A15%3A22Z&sp=rcw HTTP/1.1

Request Headers

HTTP

x-ms-blob-type: BlockBlob

Request Body

HTTP

Design File Binary Content

5.2 Get Upload Job Status

Upload component is a long running activity and runs in background, It starts once design file upload is complete. Response of upload request contains location header containing jobs endpoint with current upload job id, this is used to track the status of the background upload activity. Make a GET call to location header value (https://api.bentley.com/library/jobs/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288) to get the upload job status. Once upload activity is successfully complete, response of jobs endpoint “status” property value will be 'Success’. At this point, upload component is complete and a new component has been created. Response also provides link to this newly created component under _links->component->href property, which can be used to retrieve the component from repository.

Request Syntax

HTTP

GET https://api.bentley.com/library/jobs/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288 HTTP/1.1

Request Headers

HTTP

Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Response Headers

HTTP

HTTP/1.1 200 OK 
cache-control: no-cache
content-encoding: gzip
content-type: application/json
date: Mon, 06 Sep 2021 15:26:28 GMT
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
vary: Accept-Encoding
x-content-type-options: nosniff
x-correlation-id: 2aadd82c-527e-4761-80d7-c8fc8191242c
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US
x-ms-request-id: 2e67c236-b002-0069-7133-a37573000000
x-ms-version: 2017-04-17

Response Body

JSON

{
    "job": {
        "id": "2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288",
        "displayName": "TutorialSampleFile.rfa",
        "jobSize": 749568,
        "progress": 0,
        "status": "Success",
        "type": "Upload",
        "error": null,
        "_links": {
            "component": {
                "href": "https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7"
            }
        }
    }
}

5.3 Get Component

Property _links->component->href from the jobs response in the previous step, provides endpoint for the component created during upload activity. Make GET call to this endpoint (https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7) to retrieve the component. Response contains the component, you can note under _links property in the response, there is information/links about referenced entities of the component i.e. application, manufacturer and category. This is extracted from the design file during the upload activity. This information can only be extracted if design file used in the upload process contains information about referenced entities.

Request Syntax

HTTP

GET https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7 HTTP/1.1

Request Headers

HTTP

Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Response Headers

HTTP

HTTP/1.1 200 OK 
content-encoding: gzip
content-type: application/json
date: Mon, 06 Sep 2021 15:30:11 GMT
odata-version: 4.0
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
vary: Accept-Encoding
x-correlation-id: 007f78fc-200d-4b80-8f9d-3594e685a674
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US

Response Body

JSON

{
    "component": {
        "id": "57fefe11-df1d-40c7-ae1a-02e233b9a7c7",
        "displayName": "Tutorial Sample Component",
        "description": "Tutorial Sample Description",
        "state": "Draft",
        "createdDateTime": "2021-09-06T15:17:45.8834641Z",
        "lastModifiedDateTime": "2021-09-06T15:17:46.4509552Z",
        "supportedFileTypes": ["RFA"],
        "hashtags": ["SampleTag1", "SampleTag2"],
        "_links": {
            "catalogs": [{
                "href": "https://api.bentley.com/library/catalogs/7f427c30-8dce-4803-81dc-e8681a3bd757"
            }],
            "application": {
                "href": "https://api.bentley.com/library/applications/1418693a-8f60-4719-af0b-ceee1ad41e33"
            },
            "manufacturer": {
                "href": "https://api.bentley.com/library/manufacturers/d4485150-ad6d-4d76-a3e2-50a0f690afc9"
            },
            "category": {
                "href": "https://api.bentley.com/library/categories/63b7d70a-a426-4530-8c0f-3efd6a6c0da7"
            }
        }
    }
}

5.4 Modify Component

After the component is uploaded, next step can be to make changes in the component. A PUT call to https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7 endpoint updates the component. Let’s change the “state” property of the component. By default on upload, a component “state” property is set to 'Draft’. This property can have enum values Draft, Published, Checked, Approved and Archived. Let’s set the value to 'Published’. Also note Update Component request expects request body must contain all the desired properties since this will replace existing component with current component definition.

See the Library API documentation for descriptions of the different properties.

Request Syntax

HTTP

PUT https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7 HTTP/1.1

Request Headers

HTTP

Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Request Body

JSON

{
    "displayName": "Tutorial Sample Component",
    "description": "Tutorial Sample Description",
    "state": "Published",
    "catalogs": [
        "7f427c30-8dce-4803-81dc-e8681a3bd757"
    ],
    "category": "63b7d70a-a426-4530-8c0f-3efd6a6c0da7",
    "application": "1418693a-8f60-4719-af0b-ceee1ad41e33",
    "manufacturer": "d4485150-ad6d-4d76-a3e2-50a0f690afc9",
    "hashtags": ["SampleTag1", "SampleTag2"]
}

Response Headers

HTTP

HTTP/1.1 200 OK
content-encoding: gzip
content-type: application/json
date: Fri, 06 Sep 2021 15:37:05 GMT
odata-version: 4.0
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
vary: Accept-Encoding
x-correlation-id: 95bf368d-0d16-4913-b4ce-05caf4653c30
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US

Response Body

JSON

{
    "component": {
        "id": "57fefe11-df1d-40c7-ae1a-02e233b9a7c7",
        "displayName": "Tutorial Sample Component",
        "description": "Tutorial Sample Description",
        "state": "Published",
        "createdDateTime": "2021-09-06T15:17:45.8834641Z",
        "lastModifiedDateTime": "2021-09-06T15:37:06.1378844Z",
        "supportedFileTypes": ["RFA"],
        "hashtags": ["SampleTag1", "SampleTag2"],
        "_links": {
            "catalogs": [{
                "href": "https://api.bentley.com/library/catalogs/7f427c30-8dce-4803-81dc-e8681a3bd757"
            }],
            "application": {
                "href": "https://api.bentley.com/library/applications/1418693a-8f60-4719-af0b-ceee1ad41e33"
            },
            "manufacturer": {
                "href": "https://api.bentley.com/library/manufacturers/d4485150-ad6d-4d76-a3e2-50a0f690afc9"
            },
            "category": {
                "href": "https://api.bentley.com/library/categories/63b7d70a-a426-4530-8c0f-3efd6a6c0da7"
            }
        }
    }
}

6 Add Documents

Upload Component activity associate few documents to the component during the process. Design file and TypeCatalog file uploaded in previous steps are associated to the component as component design and typeCatalog documents respectively. Upload process also gets thumbnail image from the design file and associates it as thumbnail document. You can also associate additional documents after component is created. You can associate reference documents, images or even additional design files to the component. In this example we will associate a reference document to the component, other documents can also be associated with same steps, the only difference is setting the value of “purpose” property in document request body.

See the Library API documentation for descriptions of the different properties.

Adding document is a multi-step process, we will go through these steps next.

6.1 Create Document Instance

A POST call to https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents endpoint will create a new document instance for the component. displayName, purpose and extension are required properties. purpose can have enum values Design, Thumbnail, Reference, GalleryImage and TypeCatalog, depending upon which type of document you want to associate to a component. As we are associating a reference document, purpose should be set to 'Reference’. The POST call will return a new document instance. The id will be used in next steps, you may want to save this Id. At this moment a document instance has been associated to the component but there is no actual file attached to this document. We will do that in the next step.

Request Syntax

HTTP

POST https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents HTTP/1.1

Request Headers

HTTP

Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Request Body

JSON

{
    "displayName": "Tutorial Sample Document",
    "extension": "pdf",
    "purpose": "Reference",
    "available": false,
    "isActive": true,
    "version": null,
    "previousVersionId": null,
    "associatedDesignDocument": null
}

Response Headers

HTTP

HTTP/1.1 201 Created
content-length: 704
content-type: application/json
date: Mon, 06 Sep 2021 15:46:51 GMT
location: https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/bf15e508-3b59-49d5-a1b5-ea9ef9d66515
odata-version: 4.0
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
x-correlation-id: 63ca0126-3234-4bf4-846c-27c7e8e16458
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US

Response Body

JSON

{
    "document": {
        "id": "bf15e508-3b59-49d5-a1b5-ea9ef9d66515",
        "displayName": "Tutorial Sample Document",
        "extension": "pdf",
        "version": null,
        "previousVersionId": null,
        "purpose": "Reference",
        "size": -1,
        "available": false,
        "isActive": true,
        "createdDateTime": "2021-09-06T15:46:51.5524663Z",
        "lastModifiedDateTime": "2021-09-06T15:46:51.5524663Z",
        "_links": {
            "fileUrl": {
                "href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/bf15e508-3b59-49d5-a1b5-ea9ef9d66515.pdf?sv=2018-03-28&sr=b&sig=SeVWEiO2L83DOiSbpBBauY4OhnZaF3QqSIcZOvc6uC8%3D&se=2021-09-06T16%3A46%3A51Z&sp=rcw&rscd=attachment%3B%20filename%3DTutorial%2BSample%2BDocument.pdf"
            }
        }
    }
}

6.2 Upload Document File

Create Document response from the previous step contains a url in _links->fileUrl->href property. File upload can be done by making a Http PUT request on the provided url via tool such as Postman or programmatically use Azure libraries to upload file (https://docs.microsoft.com/en-us/rest/api/storageservices/put-blob).

Request Syntax

HTTP

PUT https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/bf15e508-3b59-49d5-a1b5-ea9ef9d66515.pdf?sv=2018-03-28&sr=b&sig=oft6xWrKourfRl5Nemd03duMS9pmi8zkiaPSE8Pynzw%3D&se=2021-09-08T10%3A51%3A03Z&sp=r&rscd=attachment%3B%20filename%3DTutorial%2BSample%2BDocument.pdf HTTP/1.1

Request Headers

HTTP

x-ms-blob-type: BlockBlob

Request Body

HTTP

File Binary Content

6.3 Update Document Instance

The last step in associating a document to component is to notify the system that file has been uploaded. This is achieved by setting “available” property of the document instance to true. Make a PUT call to https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/bf15e508-3b59-49d5-a1b5-ea9ef9d66515 endpoint to update the document. Update request expects request body must contain all the desired properties since this will replace existing document with current document definition.

Request Syntax

HTTP

PUT https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/bf15e508-3b59-49d5-a1b5-ea9ef9d66515 HTTP/1.1

Request Headers

HTTP

Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Request Body

JSON

{
    "displayName": "Tutorial Sample Document",
    "extension": "pdf",
    "version": null,
    "previousVersionId": null,
    "purpose": "Reference",
    "available": true,
    "isActive": true
}

Response Headers

HTTP

HTTP/1.1 200 OK
content-encoding: gzip
content-type: application/json
date: Mon, 6 Sep 2021 15:46:51 GMT
odata-version: 4.0
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
vary: Accept-Encoding
x-correlation-id: 3b4b2e41-3ea6-4597-bda0-6db60a038320
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US

Response Body

JSON

{
    "document": {
        "id": "bf15e508-3b59-49d5-a1b5-ea9ef9d66515",
        "displayName": "Tutorial Sample Document",
        "extension": "pdf",
        "version": null,
        "previousVersionId": null,
        "purpose": "Reference",
        "size": -1,
        "available": true,
        "isActive": true,
        "createdDateTime": "2021-09-06T15:46:51.5524663Z",
        "lastModifiedDateTime": "2021-09-06T15:54:47.206787Z",
        "_links": {
            "fileUrl": {
                "href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/bf15e508-3b59-49d5-a1b5-ea9ef9d66515.pdf?sv=2018-03-28&sr=b&sig=SeVWEiO2L83DOiSbpBBauY4OhnZaF3QqSIcZOvc6uC8%3D&se=2021-09-06T16%3A46%3A51Z&sp=rcw&rscd=attachment%3B%20filename%3DTutorial%2BSample%2BDocument.pdf"
            }
        }
    }
}

6.4 Get Component Documents

Make a GET call to https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents endpoint to get all the documents associated to the component. In this example we will get the documents from the component uploaded in the previous steps. Please note, response contains four document instances. Three of these documents Design, Thumbnail and TypeCatalog were created and associated to the component during upload activity, while we associated Reference document separately after component is created. You can download actual files from the url provided in _links->fileUrl-href property value in each document instance in the response. You can also use following API to get a particular document by it’s Id.

Library API documentation to get document by Id

Request Syntax

HTTP

GET https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents HTTP/1.1

Request Headers

HTTP

Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN

Response Headers

HTTP

HTTP/1.1 200 OK 
content-encoding: gzip
content-type: application/json
date: Wed, 08 Sep 2021 09:51:02 GMT
odata-version: 4.0
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
vary: Accept-Encoding
x-correlation-id: 2c094e5a-b770-4240-9aeb-67bca189263a
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US

Response Body

JSON

{
    "documents": [{
        "id": "3938de7f-ebf2-470f-b41a-d314fdb90ec7",
        "displayName": "TutorialSampleFile",
        "extension": "rfa",
        "version": "1",
        "previousVersionId": null,
        "purpose": "Design",
        "size": 749568,
        "available": true,
        "isActive": true,
        "createdDateTime": "2021-09-06T15:17:46.0180736Z",
        "lastModifiedDateTime": "2021-09-06T15:17:46.1465969Z",
        "_links": {
            "associatedDesignDocument": {
                "href": null
            },
            "fileUrl": {
                "href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/3938de7f-ebf2-470f-b41a-d314fdb90ec7.rfa?sv=2018-03-28&sr=b&sig=Smec6HJrZCKZGXYARrGkU1RWJuaO3jqmXKs3%2B5irnak%3D&se=2021-09-08T10%3A51%3A03Z&sp=r&rscd=attachment%3B%20filename%3DTutorialSampleFile.rfa"
            }
        }
    }, {
        "id": "4f618030-ba8c-4144-872e-c61842c3d90e",
        "displayName": "TutorialSampleFile.png",
        "extension": "png",
        "version": null,
        "previousVersionId": null,
        "purpose": "Thumbnail",
        "size": 0,
        "available": true,
        "isActive": true,
        "createdDateTime": "2021-09-06T15:17:46.2226747Z",
        "lastModifiedDateTime": "2021-09-06T15:17:46.3093526Z",
        "_links": {
            "associatedDesignDocument": {
                "href": "https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/3938de7f-ebf2-470f-b41a-d314fdb90ec7"
            },
            "fileUrl": {
                "href": "https://componentscenprodeussa01.blob.core.windows.net/public-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/4f618030-ba8c-4144-872e-c61842c3d90e.png"
            }
        }
    }, {
        "id": "f9d9f7ce-a014-4b54-b0a6-e351482ec3a5",
        "displayName": "TutorialSampleFile",
        "extension": "txt",
        "version": null,
        "previousVersionId": null,
        "purpose": "TypeCatalog",
        "size": 760,
        "available": true,
        "isActive": true,
        "createdDateTime": "2021-09-06T15:17:46.4256707Z",
        "lastModifiedDateTime": "2021-09-06T15:17:46.510613Z",
        "_links": {
            "associatedDesignDocument": {
                "href": "https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/3938de7f-ebf2-470f-b41a-d314fdb90ec7"
            },
            "fileUrl": {
                "href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/f9d9f7ce-a014-4b54-b0a6-e351482ec3a5.txt?sv=2018-03-28&sr=b&sig=1yb19XFDPtuEl6rYiFDLuCjz%2FO8a3r7h89KAHdFwvw8%3D&se=2021-09-08T10%3A51%3A03Z&sp=r&rscd=attachment%3B%20filename%3DTutorialSampleFile.txt"
            }
        }
    }, {
        "id": "bf15e508-3b59-49d5-a1b5-ea9ef9d66515",
        "displayName": "Tutorial Sample Document",
        "extension": "pdf",
        "version": "1",
        "previousVersionId": null,
        "purpose": "Reference",
        "size": 388077,
        "available": true,
        "isActive": true,
        "createdDateTime": "2021-09-06T15:46:51.5524663Z",
        "lastModifiedDateTime": "2021-09-06T15:54:47.206787Z",
        "_links": {
            "associatedDesignDocument": {
                "href": null
            },
            "fileUrl": {
                "href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/bf15e508-3b59-49d5-a1b5-ea9ef9d66515.pdf?sv=2018-03-28&sr=b&sig=oft6xWrKourfRl5Nemd03duMS9pmi8zkiaPSE8Pynzw%3D&se=2021-09-08T10%3A51%3A03Z&sp=r&rscd=attachment%3B%20filename%3DTutorial%2BSample%2BDocument.pdf"
            }
        }
    }]
}

Continue learning

Congratulation for completing Upload Component to Catalog tutorial! You should be able to upload components to catalogs and associate additional documents to the components.

Query and Download Component from a Catalog

Guide on querying and downloading components from a catalog.

Create a Component

Guide on creating a new component in an organization.

More resources that you may like

Library API

There are more capabilities, which could be used for managing components in library.

iTwin Library Sample App

Sample application that uses the Library API to create, upload and query components.