Articles in this section

How to build a Classic Custom Content Connector API?

Updated
Follow

About this article

The Classic Custom Content Connector is available for both 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. 

Sections in this article:

Prerequisites

 

 

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.

mceclip0.png

 

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.

 

mceclip0.png

 

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. In the Request, 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
"expires_in": 3600, //integer that represents the lifespan of the token in seconds
"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. The access token will then be preemptively refreshed 20 seconds before it expires. In this case, the expires_in property sent in the token response must be greater than 20 seconds. 


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 example:

[
{
"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:

mceclip4.png

 

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:

mceclip3.png

 

 

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"

 

 
  • previewUrl must 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

mceclip6.png

 

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

 

 
  • downloadUrl must 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, 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

 

 

Related articles

Comments

0 comments

Article is closed for comments.