General Connector

No UI

The General Connector is providing a standard interface for the implementation of new connectors or migrators.

Supported products:

Replace the placeholder {product} with the name in parentheses. The {key} placeholder should be replaced with a descriptive name (it allows to have several configurations for the same product).

Properties

To be configured in {home}/appserver/conf/custom.properties

generalConnector.license

type: String, required: yes, default: -

The license key for the plugin (product: generalConnector), provided by brix. The license contains information about all products and whether the connector or migrator for the product is enabled (optionally dated).

generalConnector.threads

type: Integer, required: no, default: 10

The number of threads used by the connector. At least 2.

generalConnector.debounceTimeInSeconds

type: Integer, required: no, default: 10

The number of seconds before an asset update is synchronized. It is not recommended to set this value to less than 5, because there may be other plugins triggering changes and then the same asset will be synchronized several times, causing unnecessary requests.

generalConnector.cleanup.cronExpression

type: String, required: no, default: 0 0 * * * ?

A Quartz cron expression specifying how often and when the clean-up task should run.

generalConnector.sanitize.cronExpression

type: String, required: no, default: -

A Quartz cron expression specifying how often and when the sanitize task should run.

generalConnector.replaceLocalhost

type: string, required: no, default: -, version: 1.2.2

Currently, we could only download files from the app server via download link if we extract the storage url and then replace 127.0.0.1 or localhost by host.docker.internal. So in a local docker environment without real public URL you can set this property to host.docker.internal.

generalConnector.{product}.{key}.connectorEnabled

type: Boolean, required: no, default: false, products: all

Enable the connector for a product configuration (set to true to enable and false to disable).

generalConnector.{product}.{key}.externalAssetId

type: Integer, required: yes, default: -, products: all

The text information field for the external asset id. Each product and key has to have a different field.

generalConnector.{product}.{key}.exportStatus

type: Integer, required: yes, default: -, products: all

The dropdown information field for the export status. Each product and key has to have a different field.

This field can be used for the Asset Marker.

Important: Assets which are no longer in the scope, but were already synchronized, are not updated in the other system anymore after deleting or expiring them. Only if they are in the scope again will they be updated.

Template:

    <dropdown id="?" name="{product}Status">
        <labels>
            <label lang="en">{product} status</label>
            <label lang="de">{product}-Status</label>
        </labels>
        <required>false</required>
        <options>
            <option index="1">
                <labels>
                    <label lang="en">Not exported</label>
                    <label lang="de">Nicht exportiert</label>
                </labels>
            </option>
            <option index="2">
                <labels>
                    <label lang="en">Exported</label>
                    <label lang="de">Exportiert</label>
                </labels>
            </option>
            <option index="3">
                <labels>
                    <label lang="en">Exported (inactive)</label>
                    <label lang="de">Exportiert (inaktiv)</label>
                </labels>
            </option>
        </options>
        <default>1</default>
    </dropdown>
generalConnector.{product}.{key}.scope

type: String, required: yes, default: -, products: all

A Search Util 2 expression. All assets within the scope are synchronized.

generalConnector.{product}.{key}.scopeUser

type: Integer, required: no, default: api-user, products: all

A user Id to perform the search with. This gives the possibility to also use permissions to define the scope.

generalConnector.{product}.{key}.tags

type: List of Integer, required: no, default: -, products: all

A comma-separated list of node referencing information field ids.

generalConnector.{product}.{key}.locales

type: List of Locale, required: no, default: default system locale, products: all

A comma-separated list of locales. If the value for the first locale is empty, the next locale is tried, and so on.

generalConnector.{product}.{key}.metadata

type: List of String, required: no, default: -, products: all

Other metadata that is exported (loaded automatically, do not list external id, status, tags or custom fields). A comma-separated list of information field ids or name, previewWidth, previewHeight, thumbUrl, previewUrl, largePreviewUrl, alternativePreviewFileName, assetType, fileCategory, assetStatus, availability, fileExtension, originalFileName, originalFileSize or fileProperties (any file property changes result in the file properties to be loaded automatically)

This is required to trigger changes on subscription (because if the scope i.e. the export status doesn't change, the connector is doing nothing as long as the tags don't change, unless a property configured here changes). Also the information fields are only loaded if specified here.

generalConnector.{product}.{key}.expireAssets

type: Boolean, required: no, default: false, products: all

Whether assets should be just expired (true) or deleted (false) in the external system.

generalConnector.{product}.{key}.downloadFormatId

type: Integer, required: no, default: original, products: all

generalConnector.{product}.{key}.dateFormat

type: String, required: no, default: yyyy-MM-dd, products: all

The java simple date format used for conversions.

generalConnector.{product}.{key}.prefix

type: String, required: no, default: -, products: all

The prefix to add to the CELUM (asset) id before saving it as external id in the other product.

Has to be unique for every configuration. Additionally one prefix cannot be incorporated in front of another one. E.g. Celum and CelumTest would not be ok. Celum and ABCelum would be ok, although not recommended. The recommended naming is to take the key suffixed with underline. E.g. if there are two configurations called icons and images, then take icons and images as prefixes. Also it is not recommended to end the prefix with a number (the recommended underline suffix will prevent this).

generalConnector.{product}.{key}.baseUrl

type: String, required: yes, default: -, products: frontify

The base URL.

generalConnector.{product}.{key}.token

type: String, required: yes, default: -, products: frontify

The access token. You can create a token by going to https://<domain>/api/developer/token (basic:read and basic:write required).

generalConnector.{product}.{key}.chunkSize

type: Integer, required: no, default: 100 MB, products: frontify

The chunk size for file uploads.

generalConnector.{product}.{key}.projectId

type: String, required: yes, default: -, products: frontify

The project id. E.g. https://partners.frontify.com/projects/5066/... (in the API this is now referred to as library and not as workspace project).

generalConnector.{product}.{key}.title

type: String, required: yes, default: -, products: frontify

The value to use for the title (string value). Recommended: name.

generalConnector.{product}.{key}.description

type: String, required: no, default: -, products: frontify

The value to use for the description (string value).

generalConnector.{product}.{key}.skipExif

type: String, required: no, default: -, products: frontify

The value to use for skipExif (boolean value). Recommended: static_true.

generalConnector.{product}.{key}.workflowStatus

type: String, required: no, default: -, products: frontify

The value to use for workflowStatus (string value). Recommended: static_Approved.

generalConnector.{product}.{key}.directory

type: List of String, required: no, default: -, products: frontify

The directories to which the asset should be exported (comma-separated list of string values).

generalConnector.{product}.{key}.copyrightStatus

type: String, required: no, default: -, products: frontify

The value to use for the copyright status (string value). Recommended: static_PUBLIC. Since v1.0.5 the string values are mapped as follows (case insensitive):

  • COPYRIGHTED: "copyrighted", "true", "1"
  • PUBLIC: "public", "false", "2"
  • UNKNOWN: everything else

This makes it possible to use checkboxes, number and dropdown fields to set the copyright status.

generalConnector.{product}.{key}.copyrightNotice

type: String, required: no, default: -, products: frontify

The value to use for the copyright notice (string value).

generalConnector.{product}.{key}.fieldMappings

type: String, required: no, default: -, products: frontify, version: 1.2.1

Map a String value to a custom field in Frontify. Syntax: semicolon-separated list of <frontifyFieldId>:<stringValue>.

You can get the field IDs with GraphQL and one of the following query (replace with your id): Simple to identify by label {library(id:5066){customMetadataProperties{id,name}}}, extended {library(id:5066){customMetadataProperties{id,name,type{name},defaultValue,isRequired,helpText,creator{id,name},createdAt,modifier{id,name},modifiedAt}}}

You can see the ID of your library in the URL when you open it in the browser, right here: .../projects/<ID>/...

Insomnia can be used to execute the query. Make sure you set a bearer token with enough permissions.

generalConnector.valueMapping.{mappingId}

type: String, required: no, default: -, products: all, version 1.4.0

Define a mapping. Semicolon-separated list of {old value}:{new value}

Values

String value

  • static_{text} for static text
  • info_{id} for information fields (text, text area, number, double, checkbox (true/false), dropdown (taking the label, same as localized values), node referencing information field (multiple values are concatenated using comma as delimiter, locale can be specified the same way as for localized fields), date field (using configured conversion) or localized text(area) (using either the configured locales or the specified ones (taking the first which isn't empty) like this: info_123:en,de,fr))
  • name
  • filename
  • filesize
  • availableFrom
  • availableTo
  • assetType
  • created
  • assetId since 1.3.16
  • assetTypeId since 1.4.0
  • assetTypeIdMapping_{mappingId} since 1.4.0
  • nodeIdMapping_{fieldId}_{mappingId} since 1.4.0

Boolean value

  • static_true or static_false
  • info_{id} for checkbox information fields

Date value

  • static_{date} static date, using the conversion specified in the configuration
  • info_{id} for date information fields
  • availableFrom
  • availableTo
  • created

Long and Double value

  • static_{long i.e. double} for a static number
  • info_{id} for information fields (number, double, dropdown (item id), checkbox (0/1), date (ms since 1970))
  • availableFrom
  • availableTo
  • created
  • filesize
  • assetType (id)
  • assetId since 1.3.16

String list value

Comma-separated string values with some exceptions (e.g. static_something,info_333,info_777):

  • Not possible to directly specify more than one language when using the colon notation for localized text fields and node referencing fields
  • Not possible to have static strings with commas
  • The values of node referencing fields are not concatenated to a single value

Jobs

Initial Sync Task

This task is to export all assets from Celum within the defined scopes. Only assets without external ID are exported. This task is the quickest way to get all assets into other products using the connector if no migration was done before.

Sanitize Task

The sanitize task compares all assets and tags in both systems and corrects any mistakes (Celum is the master, only export status and ID might be updated there).

Clean-up Task

The main purpose of the clean-up task is to find assets in Celum which are not in the scope of the connector anymore and to remove them from Frontify. For most of the changes, this is detected automatically via listeners, but there are actions which cannot be detected immediately, like when an asset with date-controlled validity becomes available or unavailable. This task is usually run hourly.

Compatibility Matrix

General Connector CELUM
1.0 and above 6.4 and above
1.2 and above 6.4 and above (tested with 6.15)
1.4 and above 6.14 and above

Release Notes

1.0

Released 2020-05-01

Initial version

1.2

Released 2023-05-30

Updated Frontify library and added support for custom fields (currently, pick lists are not supported).

1.4

Released 2024-04-26

Mappings für Asset-Type, Noderef and Tag fields.