This article explains 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.
To surface more assets than images, such as slides, slide elements, text elements, email elements, and PDFs, please use the Custom Content Connector.
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.
How does the Custom Content Connector work
Templafy is the client requesting images from the server. Templafy requests 4 API endpoints 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.
Required Endpoints
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.
OAuth Details
In order to Authenticate, 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.
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:
content-type: application/x-www-form-urlencoded
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"
}
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
Response
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.
[
{
"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
}
]
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 filter images on name and tags.
- pageNumber (integer, required): Page number of a paginated result that is being requested, Templafy first requests pageNumber=1.
Response
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".
[
{
"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"
}
]
Note
|
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"
Query parameters:
- assetId (string): Id of the image.
Response
An object containing:
- downloadUrl (string): Generated shared access link to the full-size image. Must be a pre-signed image URL providing access to the image without bearer access token.
{
"downloadUrl": "downloadurl" //pre-signed url
}
ImportantOnce 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
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'
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
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.
Comments
Article is closed for comments.