Abstract

This message describe how to export assets from any EngageOne® Server/Compose version using Asset Promotion Command – APC. The second part covers technical information how APC works and how to connect it to server data.

Purpose

In my previous message Upgrading or migrating EngageOne® Compose Server? Find the option best for your environment,I mentioned about new command line tool called Asset Promotion Command – APC. APC closely relates to Asset Promotion server feature, which is available in EngageOne® Compose Server/Compose 4.4.3 version -for more information about Asset Promotion feature go to EngageOne® Compose documentation. Asset Promotion feature was designed to improve promoting assets between a test and a production environments and because it is server feature, it requires access to the source (for export) and the target (for import) server REST or SOAP API. Obviously, we cannot use Asset Promotion API in older versions then 4.4.3 to export assets to standard "promotion bundle". In order to overcome this limitation I assumed that we could use internal Asset Promotion's java API (no any SOAP/REST API) which reads directly data layer - database and active-drive - and creates standard "promotion bundle". 
Asset Promotion Command – APC is just an implementation of this idea, so we can use it for exporting all supported assets from any EngageOne® Compose Server version and subsequently import this bundle to a server in version 4.4.7 or newer. Current APC alpha version depends on the current EngageOne® Compose base code, which means that, covers asset types supported in 4.4.7 version up to current 4.4.9 version.

APC Features:

1. Exports assets from any EngageOne® Compose version -  assumption is that v 3.1.2 is the oldest supported. Older versions might require db schema upgrade to 3.1.2 version.
2. List communities (domains) from any version
3. Supports the same set off assets/configurations like the latest Asset Promotion server version for all older versions.
4. Exported "promotion bundle" is compatible with the newest EngageOne® Compose version.
5. Only reads data – does not affect anyhow the source EngageOne® Compose instance, so export can be executed on running production instance.
6. Configurable feature flags - allows desensitizing for database schema changes made through particular versions or features existing only in newer versions.
7. No installation required – can be run on any machine with access to EngageOne® Compose Server database and Active Drive on the production environment
8. Simple configuration properties file - only four things to configure.
9. Runs on Windows and Linux operating systems marked as supported by EngageOne® Compose Server documentation

Asset types coverage

APC alpha version supports export of the same set of asset types like the current server version of Asset Promotion. Below are lists of supported and not yet supported asset types.

Supported assets and configurations:

1. Folders
2. Templates
3. Active contents
4. Delivery channels
5. Delivery options definitions
6. Delivery options associations to folder and templates
7. Devices
8. Document class definitions
9. Document class values for folders, templates and active contents
10. Output variables defined in templates

Not supported yet assets and configurations:

1. Data maps
2. Template/Active content version history (only current version is exported/imported)
3. Key maps
4. Lookup tables
5. RTF files
6. Output variables defined out of templates
7. Recipients
8. Access rights to folders, templates, active contents
9. Retention rules definitions
10. Retention rules associations to folder and templates
11. Spell checkers
12. Workflows definitions
13. Projects

How does it work?

APC connects directly to EngageOne® Compose database in order to get metadata of assets in selected community. Next, APC reads EngageOne® Compose config-settings.xml file (or its potentially modified copy) in order to get active-drive path. When all metadata and files are available for reading and coping, APC executes asset promotion internal java export API and creates standard "promotion bundle". APC uses only current EngageOne® Compose version code and bypass any REST/SOAP network API of server instance. 
Because APC needs only access to database and active-drive it does not matter if server is up or down or even APC can use backup copy of database. In the case of using backup copy you need to take into a count that database refers to full path of original asset's files on active-drive. Therefore, if you use copy of active-drive instead of original instance (modified copy of config-settings.xml file) you need to update some database table's records fields in order to be consistent with location of current active-drive copy.

Requirements

• Java 8/(11 very soon) installed
• Access to EngageOne® Compose database – or its copy
• Read access to active-drive path or to its copy but mapped with the same path like server gets it

APC Files

APC consist of about 80 Mb only

• promotion-cmd.jar – APC main jar file
• apc.bat – Windows version of command run script
• apc.sh – Linux version of command run script
• apc.properties – default properties configuration file
• apc.log – log file
• lib – folder with dependency jar files

How to configure APC

The apc.properties file is a default file you can change or copy and keep for different server instances. You need to set up four things in a properties file: output folder, optional compatibility feature flags, path to config-settings.xml file and database connection details. Below are all supported properties with description:

1. export.output.root.folder - Output root folder where standard "promotion bundles" will be exported
   e.g. export.output.root.folder=c:/temp/eos_promotion/export
2. Optional feature flags for backward compatibility with older versions database schema:
   feature.flag.videoAssociation.enabled=false
   feature.flag.field.sub_type.exist=false
   feature.flag.field.template_complete.exist=false
   feature.flag.field.template_type.exist=false
   feature.flag.field.effective_date_selection.exist=false
   feature.flag.field.bypass_ocp.exist=false
   feature.flag.field.fast_process_flag.exist=false
   feature.flag.table.TEMPLATE_AVAIL_DEVICES.exist=false
3. repository.xmlPath - Path to config-settings.xml file (or its copy) 
   e.g. repository.xmlPath= c:/somePath/config-settings.xml
   NOTE - only config-settings.xml 's entry for active-drive is used by APC see below
   <namespace name="com.pb.engageone">
      <setting>
         <key>active.drive</key>
         <value>C:/example/eos-installed/active-drive</value>
      </setting>
   </namespace>
   
   
4. Database connection properties - MS SQL or Oracle – DB connection properties to server DB or its copy 
   db.driverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver or db.driverClassName=oracle.jdbc.OracleDriver
   db.url=jdbc:sqlserver://myExample.pbeo.net:1433;databaseName=EngageOneDB 
   db.username=dbUserExample 
   db.password=passwordExample 
   db.defaultTransactionIsolation=READ_UNCOMMITTED

How to use it

In order to get all command options help just type:

apc –h

Then you get the following help page:

The basic use case is to export all assets from specified community, so you need to specify command goal –g export and name of the community e.g. for -c "myCommunity" , so the command is:

apc -g export -c myCommunity

Output files as a "promotion bundle" will be exported to <export.output.root.folder>/myCommunity/<timestamp> folder and every time you run this command new < timestamp > folder is created. If you want to use other than default apc.properties file, you need to specify path to this file using -p switch e.g.:

apc -g export -c myCommunity -p c:/apc/apc.production.properties

... and that's it.

If you want to try out APC alpha version, please download it from here

https://work.pb.com/:u:/g/personal/tomasz_kupka_pb_com/EcaAlEoAd9FLsdGMuVkr0FoBekxBItVhCdOhGfvrLB9OsA?e=4LzBJS

Last step 

In order to complete assets migration to target server, you have to use this <export.output.root.folder>/myCommunity/<timestamp> folder as a input for Asset Promotion Import on target  EngageOne® Compose Server - see EngageOne® Compose Server documentation for more details about Asset Promotion server feature.

Feel free to give me any comments and suggestions. 

------------------------------
Tomasz Kupka
Knowledge Community Shared Account
Shelton CT
------------------------------