flownative / neos-canto
Neos integration for Canto
Installs: 507
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 4
Forks: 5
Open Issues: 4
Type:neos-package
Requires
- php: ^8.0
- ext-json: *
- behat/transliterator: ~1.0
- flownative/oauth2-client: ^4.0.2
- guzzlehttp/guzzle: ^6.5.8 || ^7.4.5
- neos/flow: 7.0 || ^8.0 || ^9.0 || dev-main
- neos/media: ^7.0 || ^8.0 || ^9.0 || dev-main
This package is auto-updated.
Last update: 2024-10-14 11:04:37 UTC
README
Canto adaptor for Neos
This Flow package allows you to use assets (ie. pictures and other documents) stored in Canto in your Neos website as if these assets were native Neos assets.
About Canto
Canto offers a extensive solutions for digital asset management. The software makes working with pictures, graphics and video files easier.
Key Features
- seamless integration into the Neos media browser
- automatic import and clean up of media assets from Canto
- mapping of metadata from Canto to Neos
Installation
The Canto connector is installed as a regular Flow package via Composer.
For your existing project, simply include flownative/neos-canto
into
the dependencies of your Flow or Neos distribution:
$ composer require flownative/neos-canto
Enabling Canto API access
- In Canto go to Settings > Configuration Options > API > API Keys
- Click "Create API Key"
- Fill in a name that helps you understand what the key is for
- Fill in the "Redirect URL", using
https://<www.your-site.com>/flownative-canto/authorization/finish
, using your own domain(!) - Note down "App ID", "App Secret" and "Website" of the new key
Allow client credentials mode for API key
To be able to use the Canto connection from the command line or to use the webhook feature described below, client credentials mode must be enabled.
- In Canto go to Settings > Configuration Options > API > API Keys
- Edit the API key you use for the Neos integration
- Enable "Support Client Credentials Mode" and click "Save"
Configure the Canto connection
You need to set the "App ID" and "App Secret" from the generated API key as well as the URLs you are using to access Canto (since they depend on your setup.)
The URLs are a base URI built using the "Website" value appended with api/v1
and an URI used for authentication that uses the top-level domain of the "Website"
in https://oauth.canto.global/oauth/api/oauth2
.
Set those values using the environment variables
FLOWNATIVE_CANTO_OAUTH_APP_ID
FLOWNATIVE_CANTO_OAUTH_APP_SECRET
FLOWNATIVE_CANTO_API_BASE_URI
FLOWNATIVE_CANTO_OAUTH_BASE_URI
or directly in Settings.yaml
Neos: Media: assetSources: 'flownative-canto': assetSourceOptions: appId: '1234567890abcdef' appSecret: '1234567890abcdef1234567890abcdef' apiBaseUri: 'https://acme.canto.global/api/v1'
and Objects.yaml
Flownative\Canto\Service\CantoOAuthClient: properties: baseUri: value: 'https://oauth.canto.global/oauth/api/oauth2'
Using the Canto asset source in Neos
In the Media module you should see two asset sources, one called "Neos" and one called "Canto". If you switch to the Canto asset source and are not yet (or no longer) logged in to Canto, you will be redirected to the Canto login and asked to authorize access for Neos. After a redirect back to Neos you can now browse/search Canto and use assets from it in Neos as usual.
Custom Field mapping from Canto to Neos
Canto offers "custom fields" to add arbitrary data to assets. Those can be mapped to asset collections and tags in Neos, to make them visible for the users.
The configuration for this looks like that:
Flownative: Canto: mapping: # map "Custom Fields" from Canto to Neos customFields: # Foo Bar Baz # the name in Canto, for readbility 'meta_multichoice_0': # the custom field id in Canto asAssetCollection: false # map to an asset collection named after the field valuesAsTags: false # map field values to Neos tags; if true # an asset is assigned a tag corresponding to # the value include: [] # only include the listed field values as tags exclude: [] # exclude the listed field values as tags
- The key used is the custom field identifier from Canto (not the name!)
asAssetCollection
set totrue
exposes the custom field as an asset collection named like the custom field.- If
valuesAsTags
is set totrue
, each distinct value of the custom field is exposed as a tag in the asset collection and assets are grouped below the tag whose value they are assigned on the Canto side. - With
include
you can specify which values to consider, if this is used, only those will be exposed on the Neos side. - If only a few values should be excluded,
exclude
can be used. All values are exposed in Neos, except those listed here.
Note: Right now ths feature only makes sense if both asAssetCollection
and
valuesAsTags
are set to true
.
Note: The asset collections and tags must be created manually on the Neos side (for now.)
Change notification from Canto
The package provides webhooks that can be used to notify of changes in Canto.
When assets in Canto are modified, those hooks trigger the needed update on the Neos side.
- For metadata updates the changes are transferred to the imported asset, as far as the metadata is used in Neos.
- If new versions are added, those are imported and replace the existing asset in Neos.
Enabling webhooks in Canto
- In Canto go to Settings > Configuration Options > API > Webhooks
- Generate some random string for use as "Secure Token"
- Configure webhooks for "Update Metadata", "Add New Version"
- Use the matching URL for each hook as shown below
- Chose JSON as "Content Type"
- Fill in the "Secure Token"
- Click "Add"
Note: The webhook URL must be prefixed with the publicly accessible hostname of your Neos instance, and HTTPS should be used to secure the secure token!
Configure secure token in Neos
Set the "Secure Token" value using the environment variable
FLOWNATIVE_CANTO_WEBHOOK_TOKEN
or directly in Settings.yaml
Flownative: Canto: webhook: token: 'some-random-string-of-your-choice'
Cleaning up unused assets
Whenever a Canto asset is used in Neos, the media file will be copied automatically to the internal Neos asset storage. As long as this media is used somewhere on the website, Neos will flag this asset as being in use. When an asset is not used anymore, the binary data and the corresponding metadata can be removed from the internal storage. While this does not happen automatically, it can be easily automated by a recurring task, such as a cron-job.
In order to clean up unused assets, simply run the following command as often as you like:
./flow media:removeunused --asset-source flownative-canto
If you'd rather like to invoke this command through a cron-job, you can add two additional flags which make this command non-interactive:
./flow media:removeunused --quiet --assume-yes --asset-source flownative-canto
Credits and license
This plugin was sponsored by Paessler and its initial version was developed by Robert Lemke and Karsten Dambekalns of Flownative.
See LICENSE for license details.