![No UI](https://img.shields.io/static/v1?label=UI&message=none&color=inactive) *Showpad Connect* synchronizes the assets in CELUM with Showpad. The assets in Showpad can be tagged with the CELUM keywords in node reference fields. The scope and data types are configurable, it is not recommended to synchronize all the assets. Asset availability is also taken into account. The synchronization is happening immediately, asset changes or new assets should be visible in Showpad in a few seconds. It is possible to have several scopes associated with different settings. The scope is defined by the {id}. The same information fields can be used for the same division. If there are multiple tag or asset divisions, there have to be Showpad information fields for each division. The {id} *default* is reserved for default settings, those will be added automatically to all configurations, but can be overwritten by the individual configurations. It is **not recommended to synchronize localization (country and language)**, as it is a temporary solution which requires an (S)FTP server to work, and will be replaced by API calls as soon as the Showpad API is ready for it. **Important: Upgrade to v1.1.0 or above before January 31st 2021. After that, older versions won't be working anymore due to changes in the Showpad API.** [MINITOC] ## Properties To be configured in {home}/appserver/conf/custom.properties ##### showpad.license > type: String, **required: yes**, default: - The license key for the plugin (product: showpad), provided by *brix*. ##### showpad.clientId > type: String, **required: yes**, default: - The Showpad client id. ##### showpad.clientSecret > type: String, **required: yes**, default: - The Showpad client secret. ##### showpad.username > type: String, **required: yes**, default: - The Showpad username. ##### showpad.password > type: String, **required: yes**, default: - The Showpad password. ##### showpad.localization.protocol > type: String, required: no, default: ftp The protocol for the localization ftp or sftp. ##### showpad.localization.username > type: String, required: no, default: - The username for the (s)ftp login for the localization. ##### showpad.localization.password > type: String, required: no, default: - The password for the (s)ftp login for the localization. ##### showpad.localization.host > type: String, required: no, default: - The host for the (s)ftp server for the localization. ##### showpad.localization.port > type: Integer, required: no, default: - The port for the (s)ftp server for the localization. ##### showpad.localization.path > type: String, required: no, default: - The remote folder to which the localization files should be uploaded. ##### showpad.localization.filePrefix > type: String, required: no, default: - The prefix to use for the localization files. ##### showpad.localization.assetColumn > type: String, required: no, default: assetId The column name for the asset ID in the localization csv file. ##### showpad.localization.languageColumn > type: String, required: no, default: language The column name for the language in the localization csv file. ##### showpad.localization.countryColumn > type: String, required: no, default: country The column name for the country in the localization csv file. ##### showpad.{id}.downloadFormats > type: semicolon separated list of `:>file extension 1>,,...` (lower-case without dot) e.g. `1:txt,pdf;2:jpg,png;3:mp3`, > **required: yes**, > default: `1:ppt,pptx,pps,ppsx,xls,xlsx,doc,docx,key,pages,numbers,pdf,txt,rtf,mp3,m4a,wav,jpg,jpeg,png,mov,wmv,mp4,m4v,3gp,mpg,mpeg,avi,asf,flv,dwg,dxf,stl,iges,step,epub,ibooks,rvt` Make sure the download format generates files with [extensions supported by Showpad](https://help.showpad.com/hc/en-us/articles/211957069-Supported-file-types). *Attention:* zip files are not supported in general, only some special cases. Assets with extensions for which no download format was specified are ignored. ##### showpad.{id}.externalId > type: Long, **required: yes**, default: - Information field id to store the external id (see below). ##### showpad.{id}.status > type: Long, **required: yes**, default: - Information field id of the status dropdown (see below). ##### showpad.{id}.externalIdTags > type: Long, **required: yes**, default: - Information field id to store the external id for tags (see below). ##### showpad.{id}.asset.search > type: String, **required: yes**, default: - A filter expression ([search util 2](https://docs.brix.ch/celum_extensions/search_util_2)). This defines which assets are in scope and synchronized with Showpad. All versions **before v1.3** use the old syntax: A filter expression using the [anura syntax](https://docs.brix.ch/anura/api#search). This defines which assets are in scope and synchronized with Showpad. Attention: the `search_` prefix has to be dropped and `search` was renamed to `text`. Ampersand (`&`) can be escaped by using `&`. Additionally, there is a node by name filter: One of `node_contains` or `node_startswith` has to be set to apply this filter. It also requires the `node_type` (id) and optionally a `node` (id) to limit the search. The `language` parameter is also taken into consideration for the node search. E.g. `showpad.asset.search=node=1234&node_recursive=true&infofield=7,true` would find all assets linked to the node *1234* (or any sub-node) where the information field *7* (a checkbox) is true (checked). ##### showpad.{id}.asset.search.userId > type: Long, required: no, default: API-user The id of the user with which the search is executed. Only assets visible for this user will be returned. ##### showpad.{id}.asset.deleteOutOfScope > type: Boolean, required: no, default: false If set to true, all assets out of scope will be deleted in Showpad, otherwise the expiration date will be set to the current day at 0:00 (so the asset will be expired immediately in Showpad). ##### showpad.{id}.asset.division > type: String, required: no, default: - The division name to which the assets should be added. Blank indicates global. ##### showpad.{id}.tags > type: List (comma-separated), required: no, default: - Comma-separated list of node reference information field ids which should be added as tags. ##### showpad.{id}.tags.withPath > type: Boolean, required: no, default: false Export tags with path to root (true) or just the node name (false). ##### showpad.{id}.tags.division > type: String, required: no, default: - The division name to which the tags should be added. Blank indicates global. ##### showpad.{id}.asset.description > type: String, required: no, default: - The description for the asset in Showpad. `infofield_` for an info field (text, text area or their localized version followed by `:`, e.g. `infofield_133:de`) or `name` (asset name), `originalFileName`, `assetType:` or `static_`, e.g. `static_this is an example`. ##### showpad.{id}.asset.expiresAt > type: String, required: no, default: - The *expires at* property of the asset in Showpad. `infofield_` (has to be date type), `versionDate`, `creationDate`, `validFrom` or `validTo`. ##### showpad.{id}.asset.hideLabel > type: String, required: no, default: - The *hide label* property for the asset in Showpad. `infofield_` (has to be a checkbox) optionally followed by a `:` if the asset type doesn't have this info field or one of `static_true`, `static_false`. ##### showpad.{id}.asset.isAnnotatable > type: String, required: no, default: - The *is annotatable* property for the asset in Showpad. `infofield_` (has to be a checkbox) optionally followed by a `:` if the asset type doesn't have this info field or one of `static_true`, `static_false`. ##### showpad.{id}.asset.isDivisionShared > type: String, required: no, default: - The *is division shared* property for the asset in Showpad. `infofield_` (has to be a checkbox) optionally followed by a `:` if the asset type doesn't have this info field or one of `static_true`, `static_false`. ##### showpad.{id}.asset.isDownloadable > type: String, required: no, default: - The *id downloadable* property for the asset in Showpad. `infofield_` (has to be a checkbox) optionally followed by a `:` if the asset type doesn't have this info field or one of `static_true`, `static_false`. ##### showpad.{id}.asset.isEditable > type: String, required: no, default: - The *is editable* property for the asset in Showpad. `infofield_` (has to be a checkbox) optionally followed by a `:` if the asset type doesn't have this info field or one of `static_true`, `static_false`. ##### showpad.{id}.asset.isPersonal > type: String, required: no, default: - The *is personal* property for the asset in Showpad. `infofield_` (has to be a checkbox) optionally followed by a `:` if the asset type doesn't have this info field or one of `static_true`, `static_false`. ##### showpad.{id}.asset.isSensitive > type: String, required: no, default: - The *is sensitive* property for the asset in Showpad. `infofield_` (has to be a checkbox) optionally followed by a `:` if the asset type doesn't have this info field or one of `static_true`, `static_false`. ##### showpad.{id}.asset.isShareable > type: String, required: no, default: - The *is shareable* property for the asset in Showpad. `infofield_` (has to be a checkbox) optionally followed by a `:` if the asset type doesn't have this info field or one of `static_true`, `static_false`. ##### showpad.{id}.asset.name > type: String, required: no, default: - The name for the asset in Showpad. If nothing is specified, Showpad will use the file name. `infofield_` for an info field (text, text area or their localized version followed by `:`, e.g. `infofield_133:de`) or `name` (asset name), `originalFileName`, `assetType:` or `static_`, e.g. `static_this is an example`. showpad.asset.onlyShareEntireDocument > type: String, required: no, default: - The *only share entire document* property for the asset in Showpad. `infofield_` (has to be a checkbox) optionally followed by a `:` if the asset type doesn't have this info field or one of `static_true`, `static_false`. ##### showpad.{id}.asset.releasedAt > type: String, required: no, default: - The *released at* property of the asset in Showpad. `infofield_` (has to be date type), `versionDate`, `creationDate`, `validFrom` or `validTo`. ##### showpad.{id}.asset.useOptimized > type: String, required: no, default: - The *use optimized* property for the asset in Showpad. `infofield_` (has to be a checkbox) optionally followed by a `:` if the asset type doesn't have this info field or one of `static_true`, `static_false`. ##### showpad.{id}.localization.language > type: String, required: no, default: - Value to use for the language of a Showpad asset. Either a static value `static_` or the value(s) of a node referencing information field `infofield_`. The node has to be named like a locale. If not, the default system language should be used to read the node's name, it can be specified with `infofield_:`. ##### showpad.default.localization.country > type: String, required: no, default: - Value to use for the country of a Showpad asset. Either a static value `static_` or the value(s) of a node referencing information field `infofield_`. The node has to be named like a locale. If not, the default system language should be used to read the node's name, it can be specified with `infofield_:`. ##### ~~showpad.{id}.asset.externalServiceId~~ > type: String, required: no, default: CELUM Name of the external service id in Showpad. Because this is not working at the moment, the external asset ids in Showpad are prefixed by this value and the external service id is left blank. ##### ~~showpad.{id}.asset.url~~ > type: String, required: no, default: - An url, the asset id can be inserted with <id>, e.g. `https://dam-demo.brix.ch/main/opennodeview.do?assetId=`. This value will be saved as url on the Showpad asset. The idea was to have a direct link to the asset in CELUM, but this is currently not working either, and therefore it cannot be set. ##### showpad.threads > type: Integer, required: no, default: 10 The number of threads used by Showpad Connect. At least 2. ##### showpad.debounceTimeInSeconds > type: Integer, required: no, default: 5 The number of seconds before an asset update is synchronized with Showpad. 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 unnecessairy requests to Showpad. ##### showpad.cleanup.cronExpression > type: String, required: no, default: `0 1 * * * ?` 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. ##### showpad.sanitize.cronExpression > type: String, required: no, default: `0 0 1 * * ?` 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. ## Migrator With the migrator, assets already in Showpad can be synchronized with the ones in CELUM. The migrator requires a separate license and is not part of the standard connector. **The Migrator is using the same scopes as the connector.** This means that it is only looking for an asset in CELUM in the defined scope. Also keywords which aren't under a root node of one of the specified node referencing information fields which should become tags, are not considered when looking for a match for a tag from Showpad (see *showpad.{id}.tags* property). ##### showpad.migration.migrationMode > type: Boolean, required: yes, default: `true` If this is set to true, the connector is prevented from synchronizing assets. It is highly recommended doing the migration first and only start the connector after everything is cleaned up. ##### showpad.migration.tempFolder > type: String, required: yes, default: - The folder to use for temporary files. Assets coming from Showpad will have to be saved locally before they can be loaded into CELUM. ##### showpad.{id}.migration.asset.migrate > type: Boolean, required: yes, default: `false` Whether to migrate assets or not. It is recommended to migrate tags first. ##### showpad.{id}.migration.asset.method > type: String, required: yes, default: `md5` The mapping method to use for the migration of assets, either by `name` or `md5`. ##### showpad.{id}.migration.asset.downloadFormatId > type: Long, required: yes (only for md5), default: - The download format used to calculate the checksum for the assets in CELUM. ##### showpad.{id}.migration.asset.assetTypeId > type: Long, required: yes, default: - The asset type which should be assigned to assets created in CELUM or to those assets that have no asset type. This is required to be able to set properties. ##### showpad.{id}.migration.asset.nodeId The node to which newly created assets should be linked to. ##### showpad.{id}.migration.asset.updateInCelum > type: String, required: yes, default: `empty` One of `all` (update all information fields in CELUM with the values from Showpad), `empty` (just update empty information fields with the values from Showpad), `none`. This property uses the property mapping defined for the scope. ##### showpad.{id}.migration.tags.migrate > type: Boolean, required: yes, default: `true` Whether tags should be migrated or not. It is recommended to first migrate the tags, then the assets and then start the connector's sanitize task after enabling it. Tags will be synchronized by name (default system locale). ##### showpad.{id}.migration.tags.nodeId > type: Long, required: yes, default: - The node to which unknown tags should be added (tags existing in Showpad but not found in CELUM). Unless you plan to clean up this node first and move the tags to the correct places, add a node referencing information field which has this node (or a parent of this node) as root node, so unknown tags can still be added to assets using this information field. ## Installation The information fields below have to be added to all the asset types which should be exportable to Showpad. Additionally, the field for the Showpad ID has to be added to the keyword node type (or the one(s) which are used for the tags). The fields can be added to an existing or a new fieldset. The fields shouldn't be editable but can be visible. After this modification, follow the [standard installation guide](https://docs.brix.ch/celum_extensions#plugin-installation-update). **Important**: Create a different information field for each division unless the configuration sets are completely distinct. It is possible to use the same information field for the external ID of assets and tags even though they have different divisions configured, but the tag division and asset division represented by this information field have to be consistent across all configuration sets. false 1 false ## Jobs #### Initial Sync Task This task is to export all assets from Celum within the defined scopes to Showpad. Only assets without Showpad ID are exported. This task is the quickest way to get all assets into Showpad when using the connector and no migration was done before. #### Migration Task The migration task runs the tag or asset migration or both, depending on the configuration. This task is used to migrate the tags from Showpad to Celum, and then to migrate the assets from Showpad to Celum. #### 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). This task is usually run once at night in connector mode. #### 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 Showpad. 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 in connector mode. ## Compatibility Matrix | Showpad Connect | CELUM | Comment | :----- | :----- | :----- | 1.0 and above | 5.13.3 | | 1.1.0 and above | 5.13.4 | | 1.2.0 | 6.x (tested with 6.8) | | 1.3.0 | 6.x (tested with 6.8) | breaking change, see [showpad.{id}.asset.search](https://docs.brix.ch/celum_connectors/showpad#showpad-id-asset-search) ## Release Notes ##### 1.0 > Released 2020-07-01 Initial version ##### 1.1.0 > Released 2020-10-26 Implemented changes to the Showpad API ##### 1.2.0 > Released 2021-06-17 Fixed node.getParentPath bug for Celum 6.x ##### 1.3.0 > Released 2021-11-01 Switched to the more convenient search util 2