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
|
|
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
}
|
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.