![No UI](https://img.shields.io/static/v1?label=UI&message=none&color=inactive) The General Connector is providing a standard interface for the implementation of new connectors or migrators. Supported products: - Frontify (frontify): [Sample Configuration](https://docs.brix.ch/celum_connectors/frontify_connector) Replace the placeholder {product} with the name in parenthesis. The {key} placeholder should be replaced with a descriptive name (it allows to have several configurations for the same product). [MINITOC] ## 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](http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html) cron expression specifying how often and when the clean-up task should run. ##### generalConnector.sanitize.cronExpression > type: String, required: no, default: - A [Quartz](http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html) 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: false 1 ##### generalConnector.{product}.{key}.scope > type: String, **required: yes**, default: -, products: *all* A [Search Util 2](https://docs.brix.ch/celum_extensions/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:///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 `:`. 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//...` Insomnia can be used to execute the query. Make sure you set a bearer token with enough permissions. ## 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` #### 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) #### 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) | ## 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).