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:
- What is the Classic Custom Content Connector?
- How does the Custom Content Connector Work?
- Step-by-Step Guide
- Authentication
- Folders
- Images
- Download Image
- Troubleshooting
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.
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.
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:
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"
|
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
|
Request example:
GET - https://example.com/images/624645fd-4ce7-4358-b573-151f94051232
Response example:
{
"downloadUrl":"downloadurl" //pre-signed url
}
|
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
Comments
0 comments
Article is closed for comments.