Core | Essentials | DAM (4.37)

# PAP Connector and PAP client

You need the PAP (Public Access Platform) Connector if you want to connect third party systems to your 4ALLPORTAL, e.g. if you need to publish assets on a platform or website.
With the PAP it is possible to meet these needs by configuring a boolean trigger field (free for Typo3). If this field changes, an event triggers and the workflow starts (see graphic below).
The PAP client executes the PAP connector's PULL method.

# How does the PAP Connector work?

The PAP reacts to events of the CoreEngine. After changes in trigger fields, the PAP distributes this information to an appropriate connector for further processing. The PAP is the standard connection to the 4ALLPORTAL. Because the entire event management logic persists in the CoreEngine, the interfaces between systems are not stressed. Data only exchanges after an update, creation or deletion of a bean.

# Architecture

When the PAP Manager receives an event from the event management, it checks for which connector(s) this event is relevant. It analyzes whether it is a CREATE, UPDATE or DELETE event (depending on the condition set in the connector's configuration file).
These events are stored in an individual connector table and assigned a sequential ID.

Please note: Only the last relevant event for a bean with a unique bean ID is kept!

# Configuring the PAP Connector

Store the configuration file <connector_name>.xml in folder modules/<module_name>/connectors.

# Example configuration

<?xml version="1.0" encoding="UTF-8"?>
<connector>
   <connector_name>spare_part</connector_name>
   <paps>
      <pap key="data_id" class="com.cm4ap.ce.pap.UrlPushConnector"> <!-- Information to connect -->
         <parameters>
            <entry key="url">file:///usr/local/mam/cclone/4ap_pac/data-id/{$id.right(3)}/{$id}{if $_event.event_type != 0}{if $_event.object_type == 0}/sidecar.xml{else}/{$_derivate.type}/{$_derivate.index}/index.{$_derivate.extension}{/if}{else}{if $_event.object_type == 1}/{$_derivate.type}{/if}{/if}</entry>
            <entry key="unzip" class="java.lang.Boolean">true</entry>
         </parameters>
      </pap>
      <pap key="image_id" class="com.cm4ap.ce.pap.UrlPushConnector"> <!-- Information to connect -->
         <parameters>
            <entry key="url">file:///usr/local/mam/cclone/4ap_pac/mat-id/{$pac_image_id.right(3)}/{$pac_image_id}{if $_event.event_type != 0}{if $_event.object_type == 0}/sidecar.xml{else}/{$_derivate.type}/{$_derivate.index}/index.{$_derivate.extension}{/if}{else}{if $_event.object_type == 1}/{$_derivate.type}{/if}{/if}</entry>
            <entry key="unzip" class="java.lang.Boolean">true</entry>
         </parameters>
      </pap>
   </paps>
   <conditions> <!-- All have to return true. It should be possible to access fields through relations -->
      <condition>
         <value1 type="field">
            <value>data_shellpath</value>
         </value1>
         <operator>like</operator>
         <value2 type="value">
            <value>%/Material Images/___/%</value>
         </value2>
      </condition>
      <condition>
         <value1 type="field">
            <value>pac_image_id</value>
         </value1>
         <operator>is not</operator>
         <value2 type="value">
            <value/>
         </value2>
      </condition>
   </conditions>
   <dimensions>
      <entry key="locale" class="array">
         <value>de_DE</value>
         <value class="null" />
      </entry>
      <entry key="channel" class="array">
         <value>print</value>
      </entry>
   </dimensions>
   <fields>
      <field>data_name</field>
      <field>data_subsubtype</field>
      <field>data_shellpath</field>
      <field>sap_material_id</field>
      <field>pac_image_id</field>
      <field>pac_image_folder</field>
   </fields>
   <trigger_fields>
      <trigger_field>data_name</trigger_field>
      <trigger_field>data_subsubtype</trigger_field>
      <trigger_field>data_shellpath</trigger_field>
      <trigger_field>sap_material_id</trigger_field>
      <trigger_field>pac_image_id</trigger_field>
      <trigger_field>pac_image_folder</trigger_field>
      <!--<trigger_field>data_file_info_hash</trigger_field>-->
   </trigger_fields>
   <triggers>
      <trigger>
         <selector>field or relation</selector>
         <dimensions>
            <entry key="locale" class="array">
               <value>de_DE</value>
               <value class="null"/>
            </entry>
            <entry key="channel" class="array">
               <value>print</value>
            </entry>
         </dimensions>
      </trigger>
   </triggers>
   <derivates> <!-- Derivate keys -->
      <derivate>Web</derivate>
   </derivates>   
</connector>

# Description of elements

# connector_name

The name of the connector must be unique in each database, because the name of the connector table generates like this: connector_<connector_name>. Connector events are also accessed via the connector name.

# paps

The PAP actions entered here are executed one after the other in the specified order.

# Configuring a PAP action
Element Description
key name of a PAP action
class java class, derived from com.cm4ap.ce.event.ConnectorEventListener, is initialized on start or reload of the CoreEngine
parameters content of the XML tag entry: parameters of an action parsed to properties of the above classes

# conditions

Conditions determine whether beans from the workflow are processed at all. In conditions, event variable _event can also be used with an embedded event object, e.g.:

{$_event.value_old}

# dimensions

Dimensions are applied to the "getBeans" call to specify multidimensional fields.

# fields

These fields (metadata) are appended to the respective bean during the "getBeans" call.

Please note: The fields from fields can be from relations to other modules. For this purpose, they should be designed similarly to fields from the search.

# trigger_fields

Every change in the fields entered here triggers the workflow (see Triggers).

Please note: This parameter will soon be no longer supported. Currently, the fields configured here are transferred to triggers.

# trigger

Here triggers are configured.

# derivates

Similar to trigger_fields, a change to the derivatives entered here will trigger the connector.

# PAP actions

# Implementation

To implement a new PAP action, extend class com.cm4ap.ce.event.ConnectorEventListener, e.g.

public class my_new_PAP_action extends ConnectorEventListener {..}

The parameters from the parameter configuration are transferred to the defined properties of the class (if transferable yet).

# UrlPushConnector

Java class com.cm4ap.ce.pap.UrlPushConnector represents the PAP action for storing the affected bean objects and their associated derivatives to a specific URL path, e.g.:

<pap key="data_id" class="com.cm4ap.ce.pap.UrlPushConnector"> <!-- Information to connect -->
   <parameters>
      <entry key="url">file:///usr/local/mam/cclone/4ap_pac/data-id/{$id.right(3)}/{$id}{if $_event.event_type != 0}{if $_event.object_type == 0}/sidecar.xml{else}/{$_derivate.type}/{$_derivate.index}/index.{$_derivate.extension}{/if}{else}{if $_event.object_type == 1}/{$_derivate.type}{/if}{/if}</entry>
      <entry key="unzip" class="java.lang.Boolean">true</entry>
   </parameters>
</pap>
Key Description
url url-based destination path (e.g.: file:///share/...). A template from the Template Engine can be used here.
unzip specifies whether the destination file (if a ZIP archive), is unpacked instead of being stored
false (default): nothing happens
true: will be unpacked

# PAP client

The PAP client executes the PAP connector's PULL method. It was implemented as a Jetty server and is based on the REST interface of the 4ALLPORTAL.

# Start

java -jar cmservice-pap-client.jar --configuration <config>.xml

The following execution parameters are supported:

Short form Long form Description
-b –batch batch mode (application exits after one run)
-c –configuration configuration file (required)
-D –debug outputs DEBUG messages
-e –encoding character encoding (default: UTF-8)
-h –help help (outputs supported parameters)
-l –log outputs a file's log
-m –max_threads <max_threads> maximum of threads (default: 16)
-p –port server port (default: 8192)
-t –timeout connection timeout in seconds (default: 600 seconds)
-v –verbose outputs INFO messages
-d –nodb no use of local database

# Example configuration of the PAP client

<?xml version="1.0" encoding="UTF-8"?>
<pap-client>
   <!-- PAP Client -->
   <!-- use RESTful API -->
   <legacy-api>true</legacy-api>
   <!-- period in seconds -->
   <period>10</period>
   <!-- remote host configuration -->
   <remote>
      <url>https://domain.net</url>
      <!-- route of the cluster, if only one cluster must be called -->
      <route/>
      <customer>mandant</customer>
      <username>username</username>
      <password>password</password>
   </remote>
   <!-- set use='true' to use keystore for SSL connections, otherwise all
   SSL connections will be accepted by default -->
   <keystore use="false">
      <!-- default path is '<configuration path>/<remote domain>.jks' -->
      <path />
      <!-- default password is 'changeit' -->
      <password>changeit</password>
   </keystore>
   <!-- proxy configuration -->
   <!-- default port is 8888 -->
   <!-- <proxy>
      <host>localhost</host>
      <port>8888</port>
      </proxy> -->
   <!-- PAP connector name -->
   <connector>spare_part</connector>
   <actions>
      <entry
         key="small"
         class="com.ce4ap.pap.client.conf.PAPDerivateAction">
         <!-- source = usage or name of derivate -->
         <source>HIR</source>
         <!-- target file as java URI -->
         <destination>file:///usr/local/SAP/{matid.left(3)}/{matid}.jpg</destination>
      </entry>
   </actions>
</pap-client>

Please note: destination is determined via the Template Engine.

# How does the PAP client work?

After execution, an additional file <configuration_name>.key is created. This file contains an API key to allow access to internal functions of the PAP client. E.g.:

4m651565t2uec4gmhmsnef7u0l

After a successful connection with the 4ALLPORTAL a second file <configuration_name>.dat is created. This second file contains the information about the last execution or synchronization. E.g.:

{"eventId":121641,"connectorHash":"ee4930140bf9909136208201131a6835"}

# Keystore

To create a keystore or to add a certificate to an existing keystore, use the following command:

keytool -import -file <certificate> -alias <e.g. host name> -keystore <keystore file>

# Local database

All synchronized beans are stored (if not explicitly disabled) in the local database (MapDB) in the file <configuration_name>.db.
This information is used e.g. when deleting a bean's derivative.

Please note: If you want a full synchronization, we recommend deleting both the local database and the cache file <configuration_name>.dat.

← PDF export →

Request missing documentation