Showpad Connect

No UI

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.

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 <download format id>:>file extension 1>,<file extension 2>,... (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. 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).

type: String, required: yes, default: -

A filter expression (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. 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 &amp;.

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_<id> for an info field (text, text area or their localized version followed by :<language>, e.g. infofield_133:de) or name (asset name), originalFileName, assetType:<language> or static_<custom static text>, 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_<id> (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_<id> (has to be a checkbox) optionally followed by a :<default value> 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_<id> (has to be a checkbox) optionally followed by a :<default value> 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_<id> (has to be a checkbox) optionally followed by a :<default value> 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_<id> (has to be a checkbox) optionally followed by a :<default value> 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_<id> (has to be a checkbox) optionally followed by a :<default value> 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_<id> (has to be a checkbox) optionally followed by a :<default value> 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_<id> (has to be a checkbox) optionally followed by a :<default value> 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_<id> (has to be a checkbox) optionally followed by a :<default value> 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_<id> for an info field (text, text area or their localized version followed by :<language>, e.g. infofield_133:de) or name (asset name), originalFileName, assetType:<language> or static_<custom static text>, 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_<id> (has to be a checkbox) optionally followed by a :<default value> 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_<id> (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_<id> (has to be a checkbox) optionally followed by a :<default value> 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_<locale> or the value(s) of a node referencing information field infofield_<id>. 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_<id>:<locale>.

showpad.default.localization.country

type: String, required: no, default: -

Value to use for the country of a Showpad asset. Either a static value static_<locale> or the value(s) of a node referencing information field infofield_<id>. 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_<id>:<locale>.

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=<id>. 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 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 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.

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.

<dropdown id="?" name="showpad_status">
    <labels>
        <label lang="en">Showpad status</label>
        <label lang="de">Showpad-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>

<text id="?" name="showpad_id">
    <labels>
        <label lang="en">Showpad ID</label>
        <label lang="de">Showpad ID</label>
    </labels>
    <required>false</required>
</text>

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

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