Service declaration file
Service declaration file contains services
element, which is an
array of individual service declarations. A service declaration is a dictionary containing
three mandatory elements named systemId
, serviceName
, and
factoryClass
, and one optional element named params
.
Details of the elements are as follows:
systemId
This string value uniquely identifies a target content repository. This identifier should preferably contain only English alphanumeric characters. Use dots, dashes, and underscores to enhance readability. Avoid any other special characters and unicode characters. Identifier once chosen for the target system must remain consistent across all service declarations for the same system. This identifier is also used in Unica Platform configuration for onboarding the respective system.
The following are some examples of valid system identifiers:
WCM AEM Example WCM_1.0 AEM_1_1 DX-CORE DX
You can write different plugins for different versions of the same system. In such case, different identifiers must be used to identify each version distinctly. Alternatively, the same plugin may contain different versions of service implementations specific to the respective versions of the corresponding system. In such case, different systemIds must be carefully assigned to the respective service declarations. For example, two different versions of WCM, namely 1.0 and 2.0 may contain different APIs for content search service, thereby causing following service entries for respective versions:
- systemId: WCM_1.0 serviceName: simple-search factoryClass: com.hcl.wcm.service_1_0.WcmSimpleSearchService - systemId: WCM_2.0 serviceName: simple-search factoryClass: com.hcl.wcm.service_2_0.WcmSimpleSearchService
The two entries may belong to the same plugin or may be placed in two different plugins for the sake of implementation clarity. Content Integration Framework does not impose any restrictions.
serviceName
This string value uniquely identifies the given service for corresponding system. It can either be a name of Standard service, or an appropriately chosen name for the custom service. Standard services are discussed in subsequent sections.
factoryClass
This is a fully qualified path to the Java class providing service implementation.
params
Provides a way to supply static parameters to the service to control, or modify, service behavior according to the parameter values. In short,
params
can be used to hold static key-value configuration for service implementations. This can include certain standard service parameters as well as any custom parameters that a service might want to use. Parameter values are converted into the objects of closest matching primitive wrapper classes, such as Integer, Long, Double, String etc. A parameter value can also be a map, array, or list of other values (plugins must verify the runtime-type of these values before using them).
Service declaration file also contains certain properties pertaining to the target content repository. These properties are covered under systems root element. The following is an example of such entry containing all the supported properties:
systems:
YOUR_SYSTEM_ID:
params:
param1: value1
param2:
k1: v1
k2: v2
param3: 100
additionalFeatures:
securityPolicy: false
content:
paginatedSearch: true
paginatedList: true
anonymousContent: true
categorization: lenient
This example entry shows the default values considered for each property mentioned herein in case no such entry is present for the given target repository. Thus, this entry is optional unless one or more of these default considerations do not hold true for the target content repository. Below section briefs the significance of each property:
params
- Provides a way to supply static parameters to the respective
plugin to control or alter plugin behavior according to the parameter values. In short,
params can be used to hold static key-value configuration for plugin implementations.
This can include predefined standard system parameters as well as any custom parameters
that a respective plugin might want to use. Parameter values are converted into the
objects of closest matching primitive wrapper classes, such as Integer, Long, Double,
String etc. A parameter value can also be a map, array, or list of other values (plugins
must verify the runtime-type of these values before using them).
additionalFeatures | securityPolicy
- This setting must be set to true
when content is protected inside respective system using Unica's security policies.
additionalFeatures | content | paginatedSearch
- This feature flag is
used to convey whether content repository supports paginated content search results or
not. User experience is altered accordingly for showing content search result.
additionalFeatures | content | paginatedList
- This feature flag is used
to convey whether content repository supports paginated content listing or not. User
experience is altered accordingly for showing content list.
additionalFeatures | content | anonymousContent
- This feature flag is
used to convey whether publicly accessible content should be expected from the content
repository or not. If it is set to true, plugin must return publicly accessible URL for
each content. If contents cannot be made publicly accessible using HTTP(S) URL, plugin
developer must set this flag to false. In such case, users will not be able to see or
download the contents fetched from the repository. If the target system does not provide
anonymously-accessible URL for the content, you must implement the
resource-loader
service to allow download of protected content.
additionalFeatures | content | categorization
- This property can be set
to either strict or lenient. If it is left out, it is assumed to be
lenient by default. Content is generally organized in different categories. Value of
this property provides a hint about the structural similarities of contents across
categories. Strictly organized contents are assumed to be heterogeneous. Such contents
may not share any attributes across categories. For example, insurance products can be
considered as strictly categorized. Life insurance, Automobile insurance, Health
insurance, Travel insurance etc. have very few attributes in common. Such products
possess exclusive attributes relevant to the category they belong to. Whereas leniently
categorized contents are assumed to be homogeneous by and large. They share most of
their attributes across categories. For example, products in an e-commerce application
can be considered leniently categorized since most of the products across all categories
have similar attributes such as product title, description, SKU, price, manufacturer,
discount, imagery, rating, offers, weight, warranty information etc.
Value of this property helps in deciding whether users should be allowed to pick contents across categories while using Content Integration feature in Centralized Offers Management. Strict will restrict users to the contents of relevant category, whereas lenient will allow users to choose content from any category regardless of the category used for setting up attribute mapping.
In addition to standard system parameters, any custom parameters can also be declared similarly. Likewise, the Additional parameters section in Platform configuration can also be utilized for admin configurable system parameters. Note that the Additional parameters in Platform configuration does not support nested & collection (array & dictionary) parameters. It must be a simple key: value pair, wherein key & value is separated by a colon & a space. Each key/value pair must be on separate line.
For example,
param1: value1
param2: 2
param3: 1.2
The Additional parameters in Platform configuration as well as system parameters from YML file can be obtained by invoking getParams() method on standard SystemConfig object available to each service.