How to build a Classic Custom Content Connector API?

About this article

Available for Templafy Hive and Templafy One.

This article will guide you on how to integrate your Digital Asset Management system (DAM) with Templafy's Library, enabling users to insert images from your DAM directly into documents, presentations, and emails. 

If you wish to surface more assets than images, such as slides, slide elements, text elements, email elements, and PDFs, please use the Custom Content Connector. 

If you wish to configure your custom connector in the admin portal, please see here.

 

What is the Classic Custom Content Connector?

To ensure users have fast access to approved content, and for organizations to continue to manage content within the DAM, the Custom Content Connector surfaces images from your (DAM) to the Templafy library or task pane. 

The screenshot below demonstrates how images from the company DAM are available to be inserted directly into a word document.

 

How does the Custom Content Connector work?

Templafy is the client requesting images from the server. Templafy requests 4 APIs which are detailed in the article below, the Custom Content Connector that you build will need to receive these requests and respond with data formatted as per the examples below.

 

 

Prerequisites

Admin access in Templafy tenant Admin access in "external system name" Library and connectors modules enabled Content Connector enabled DAM to support Bearer authentication

 

All the names and values in this article are case sensitive.

 

Step-by-step guide:

All connections to Templafy must be on HTTPS. The base URL, client id and client secret are configured in the Templafy admin panel, instructions here, the grant_type is always client_credentials.

Authentication

POST- https://example.com/oauth2/token

Request example:

{
grant_type: "client_credentials",
client_id: "632b27ff-1698-45ce-abb1-5a1542275a7", //example client id
client_secret: "632b27ff-1585486b1-5a0545832a7577" //example client secret
}

Response example:

{
"access_token": "632b27ff-1698-45ce-abb1-5a0f142a75a7", //example access token id
"expires_in": 3600,
"token_type": "Bearer" 
}

OAuth Details

Templafy sends an OAuth request with a client id and client secret to the host URL configured in the Templafy admin portal. The expected response includes an access token and expiry in the format listed below.

Templafy will continue to use the access token for all subsequent requests. 

OAuth type:

This integration uses Client Credentials for machine-to-machine authentication. All requests from Templafy use the same client id and client secret, therefore, user-based authentication such as Authorization Code is not yet available.

For user-based asset requests, Templafy sends the user data as a header value e.g. 

x-templafyuser: "currentuser@example.com"

OAuth refresh mechanism: 

Templafy will continue to request content with the token provided. Once the token expires, your server needs to respond to the content requests with an HTTP 401 unauthorized error. Templafy will then request another OAuth token and repeat the process. Templafy does not use the response expiry to refresh the token.

OAuth headers:

OAuth requests use the header "content-type: application/x-www-form-urlencoded"

 

Folders

GET - https://example.com/folders

This is the API endpoint that Templafy will request to the external service in order to get the folders, that should be shown in the Templafy interface. If the external image service doesn’t have folders, an empty array can be returned.

Header values:
- Authorization: "Bearer access_token"
- x-templafyuser: "currentuser@example.com"

Query Parameters:
- navigationPath (string): Hierarchical path identifying a parent folder

Returns:
An array of objects containing:
- id (string): ID of the folder
- name (string): Name of the folder
- navigationPath (string): Hierarchical path identifying the folder
- parentFolderId (string): ID of the parent folder

 

Folder Examples

GET - https://example.com/folders
Response:

[
{
"id": "101",
"name": "All Images",
"navigationPath": "100/101",
"parentFolderId": "100"
}
]

If the response contains 1 folder and navigation path, Templafy will display 1 folder to select from:

 

If the user clicks into the All Images folder to surface folders or images within, Templafy will request the new folder endpoint

GET - https://example.com/folders?navigationPath=101

Response example:

[
{
"id": "110",
"name": "Business Images",
"navigationPath": "100/101/110",
"parentFolderId": "101"
},
{
"id": "111",
"name": "Marketing Images",
"navigationPath": "100/101/111",
"parentFolderId": "101"
},
{
"id": "112",
"name": "Product Images",
"navigationPath": "100/101/112",
"parentFolderId": "101"
}
]

The 3 folders returned are rendered in Templafy as below:

 

 

Images

GET - https://example.com/images

This is the API endpoint that Templafy will request to the external service in order to get the images in a folder that should be shown in the Templafy interface.

Header values:
- Authorization: "Bearer access_token"
- x-templafyuser: "currentuser@example.com"

Query parameters:
- navigationPath (string, required): Hierarchical path identifying the folder that holds the images.
- searchQuery (string, not required): Search query passed along from the Templafy interface. Can be used
to for instance filter images on name and tags
- pageNumber (integer, required): Page number of a paginated result that is being requested, Templafy first requests pageNumber=1

Returns:
An array of objects containing:
- id (string): ID of the image
- height (integer): Height of the image in pixels
- width (integer): Width of the image in pixels
- mimeType (string): Mime type of the image. E.g. 'image/jpeg'.
- previewUrl (string): Link to a thumbnail size image signed with short life signature
- folderId (string): ID of the containing folder
- name (string): Name of the image
- tags (string): Tags of the image, comma-separated. E.g. "sun, summer"

 

Important notes on Image requests

- previewUrl needs to be a pre-signed image URL providing access to the image without bearer access token

- Pagination: as the user scrolls down through images in the library, Templafy will increase the pageNumber count in its request

 

Request example:

GET - https://example.com/images?navigationPath=&pageNumber=1

Response example:

[
{
"id": "624645fd-4ce7-4358-b573-151f940510f8", //image guid
"height": 100,
"width": 100,
"mimeType": "image/jpeg", //image/png
"previewUrl": "https://mydam.com/preview/624645fd-4ce7-4358-b573-151f940510f8.png",
"folderId": "",
"name": "crayons",
"tags": "color, kids, crayon"
},
{
"id": "624645fd-4ce7-4358-b573-151f940510f9", //image guid
"height": 100,
"width": 150,
"mimeType": "image/png",
"previewUrl": "https://mydam.com/preview/624645fd-4ce7-4358-b573-151f940510f9.png",
"folderId": "",
"name": "harbour bridge",
"tags": "sydney, australia, bridge"
}
]

 

Templafy will display all images returned as soon as the library loads. If the server doesn't return a folder structure, the images will be displayed in the task pane

 

Request example:

GET - https://example.com/images?navigationPath=images&pageNumber=1&searchQuery=harbour

Response example:

[
{
"id": "624645fd-4ce7-4358-b573-151f94051232", //image guid
"height": 100,
"width": 150,
"mimeType": "image/jpeg",
"previewUrl": "https://mydam.com/preview/624645fd-4ce7-4358-b573-151f94051232.png",
"folderId": "",
"name": "harbour",
"tags": "sydney, australia, bridge"
}
]

 

Download Image

GET - https://example.com/images/{assetId}

This is the API endpoint that Templafy will request to the external service in order to get the download Url of a specific image, which will then be downloaded by Templafy and given to the user. 

Header values:
- Authorization: "Bearer access_token"
- x-templafyuser: "currentuser@example.com"

URL Path parameters:
- assetId (string): Id of the image

Returns:
An object containing:
- downloadUrl (string): Generated shared access link to the full-size image

 

Important note on image download

- downloadUrl needs to be a pre-signed image URL providing access to the image without bearer access token

 

Request example:

GET - https://example.com/images/624645fd-4ce7-4358-b573-151f94051232

Response example:

{
"downloadUrl": "downloadurl" //pre-signed url
}

 

Once the API is ready, in order to finalize the linkage between Templafy and the external DAM, the final configuration must be made in the Templafy Admin center where the Base URL, Client ID, API Key must be specified. See the external related article called "How to configure a Classic Custom Content Connector integration"

 

Troubleshooting

1. No MediaTypeFormatter...of type 'Folder[]' from content with media type 'text/html'

No MediaTypeFormatter is available to read an object of type 'Folder[]' from content with media type 'text/html' 

If Templafy receives this error - please try adding a forward slash "/" to the end of the URL host in Templafy's configuration. E.g. https://company.com/images/ instead of https://company.com/images

 

2. No MediaTypeFormatter...of type 'Asset[]' from content with media type 'text/plain'

No MediaTypeFormatter is available to read an object of type 'Asset[]' from content with media type 'text/plain'.

If Templafy receives this error, it's likely Templafy receives a response from the Content Connector without the header 'Content-Type' = 'application/json'

 

3. Unexpected character encountered

Unexpected character encountered while parsing value: <. Path '', line 0, position 0.

If Templafy generates this error, your Content Connector may be sending Templafy JSON files with invisible characters or unsupported encoding such as UTF-8 BOM. Notepad editors such as Notepad ++ or Visual Studio Code can help remove UTF-8 BOM encoding, details here.

 

Related articles

How to enable a Classic Custom Content Connector?