This is the high-level description for Kordiam's integration with K4, which is used to establish a bi-directional communication between the content calendar tool Kordiam and servers running the Vjoon K4 publishing software.
- What does the integration do?
- Requirements for this integration
- Costs
- Integration method
- Data mapping
- Configuration
What does the integration do?
Basically, a story planned and coordinated in the editorial calendar of Kordiam automatically creates a story in K4 with subsequent synchronization of data.
The K4 integration can be configured for a specific publication platform within Kordiam. Whenever elements are created within Kordiam, which publish to this platform, a new article is created in K4.
When the element gets updated (e.g. when the title changes), these changes are also propagated to K4, where the article or related metadata fields are being updated.
In addition, when articles or metadata fields related to an article, are being changed in K4, these changes are transmitted back to Kordiam using the REST-API of Kordiam. Keep in mind, that it might take up to 60 seconds for the changes within K4 to be recognized by Kordiam.
What are the requirements for this integration?
Mainly, you must be a customer of Vjoon K4 and of Kordiam. For specific technical pre-requisites, please see "Configuration", below.
Costs
Depending on how much support or additional customization you need, the typical price for such an integration is in between 0 and 5,000 USD or Euros.
Please contact us at support@kordiam.io for detailed pricing information.
What integration method is being used?
The K4 integration implements the default interface of Kordiam. In order to enable it within Kordiam, just use the "Default" integration for Kordiam publication platforms. Please find all relevant information about the Platform Integration here and on the following sites in our support area.
Data mapping of contents:
As the application maps content from Kordiam to content in K4, we need to make clear what is the corresponding counterpart in each system.
| Kordiam | K4 | Notes |
| Platform | Publication | Platforms in Kordiam match publications in K4 |
| Platform-Category | Publication Category | Categories of platforms in Kordiam match categories of publications in K4 |
| Element | Article | Kordiam elements match articles in K4 issues |
| Element Single Publication | Issue | The single publication of elements is matched by issues in K4 |
| Element Publication-Status | Article-Status | The publication status of an element is matched by the status of an article in the K4 article workflow |
| Element-Slug | Metadata Keywords | The slug of a Kordiam element is represented within the Keywords metadata field of K4 |
| Element-Note | Metadata Kordiam Notes | The note of a Kordiam element is represented within the Kordiam Notes metadata field of K4 |
Runtime Requirements
- The application supports K4 statuses and task workflows. However, statuses can only be set from Kordiam when articles are created using the status workflow.
- The names of categories must be identical in Kordiam and K4.
- Single publication dates must be used in Kordiam.
- The labels of single publications in Kordiam must match the names of issues in K4-statuses.
- A K4 task named Edit Metadata must exist, since it is used to update articles.
- No task may contain the word edit written in lower case. As this is used to determine when an article has been edited.
- K4 metadata fields Keywords, Due Date, Kordiam Element ID, Kordiam Publication ID and Kordiam Notes must exist and must be writable within the execution of the Edit Metadata task.
- The configuration (see below) must contain a mapping of Kordiam platforms to K4 publications.
- The configuration (see below) must contain a mapping of Kordiam publication statuses to a K4 article workflow.
Configuration
This tool can be configured using the configuration file application.properties, which is located in the config directory. It must not be moved elsewhere.
Java Runtime
This application requires the installation of a Java Development Kit (JDK) for Java 11. Pre-built binaries for specific platforms can be obtained from Adoptium, which is maintained by the Eclipse foundation.
Quarantine Flags
Under macOS, it might be necessary to remove quarantine flags from the archive or from the extracted directory containing the application.
sudo xattr -r -d com.apple.quarantine /path/to/k4_integration.zip
K4 Event Log
As this software monitors a K4 server's event log, the log file must be accessible for it.
Ports and HTTP-Proxy
The application must be reachable from Kordiam‘s cloud servers. It connects to a TCP Port, which can be specified in the
config/application.properties
file, which holds all important configuration options.
We suggest setting up a reverse proxy using a common web server (like NGINX or Apache2). This proxy should also handle the encryption of the connection between the cloud servers and the proxy using a valid SSL certificate.
Configuration Options
Network Settings
In order to configure the TCP port of the application use
quarkus.http.port.
quarkus.http.port=18080
The context path of the application can be changed using
quarkus.http.root-path .
Make sure to also match this path in the configuration of the reverse proxy.
quarkus.http.root-path=/desk-net
Security
The application uses a token based approach to secure its endpoints. The following value has to be configured in order for the token to be signed correctly. The address must point to the authorization endpoint which should be accessible from the Kordiam servers.
mp.jwt.verify.issuer=https://xxx.xxx.xxx/oauth/token
On the Kordiam side, the application is treated as a WordPress integration. The credentials provided in the Setup must match the following values, which must be provided in the configuration file as well.
desknet.plugin.username=XXXX
desknet.plugin.password=XXXX
Logging
To modify the log level use
quarkus.log.level .
Valid values are
TRACE , DEBUG , INFO , WARNING and ERROR .
The default log level is
INFO
which causes all messages with level
INFO , WARNING or ERROR
to get logged.
quarkus.log.level=INFO
API Connection to the K4 Server
The application uses SOAP to communicate with the targeted K4 server. Therefore, credentials have to be supplied.
desknet.k4.client.username=XXXX
desknet.k4.client.password=XXXX
The address of the K4 server is configured using
desknet.k4.url .
desknet.k4.url=https://xxx.xxx.xxx/K4Server
K4 Article Workflow
Articles in K4 are created using a so-called workflow channel. The name of this workflow channel must also be configured, as well as the name of the user for whom the task gets executed.
desknet.k4.article.workflow.channel=Article [Print]
desknet.k4.article.task.user=Administrator
When an article gets created, we also attach an InDesign file to it. The path to that file must be configured (relative to the start script).
desknet.k4.article.text.object.path=text.icml
In order to calculate the correct time, we need to set up the time zone in which the server runs.
desknet.k4.timezone=Europe/Berlin
Monitoring of K4 Event Log
The K4 integration monitors the K4 event log. We therefore need to configure where this file is stored and also name a file which is used to persist the timestamp of the last scanned entry. The value of
desknet.k4.eventlog.tasks
holds a comma separated list of task names. The integration scans the log for events of these tasks.
desknet.k4.eventlog.path=C:/Program Files/XXXX/ProgramData/vjoon/K4Server/logs/
desknet.k4.eventlog.filename=k4_event.log
desknet.k4.eventlog.lastscanentry=last_scan_entry.txt
desknet.k4.eventlog.tasks=Create Article,Edit Meta Data
Changes to articles in K4 must be propagated to the corresponding subject in Kordiam. Therefore, the connection has to be set-up as follows:
desknet.api.client.id=XXXX
desknet.api.client.secret=XXXX
desknet.api.client/mp-rest/url=https://desk-net.com/api
Mapping of Kordiam and K4 entities
Every platform channel in Kordiam must match a corresponding publication in K4. The following values configure the mapping. The first entry of
desknet.k4.platforms
identifies a Desk-Net platform channel, which gets mapped to the K4 publication, which is identified by the first entry of
desknet.k4.publications
… and so on.
desknet.k4.platforms=AAAA,BBBB
desknet.k4.publications=AAAA,BBBB
To obtain the IDs of Kordiam platforms, an HTTP-Request has to be made to
https://api.desk-net.com/#api-Platform-GetPlatforms
Since the application also matches the publication statuses of Kordiam elements and K4 articles, the configuration must contain information on how theses are mapped. The field
desknet.k4.status.k4
contains the names of K4 article workflow statuses. The field
desknet.k4.status.desknet
contains IDs of statuses supported by Desk-Net. The first K4 status is mapped to the first status listed in the list of Desk-Net statuses… and so on.
desknet.k4.status.k4=RAW,PUBLISHED
desknet.k4.status.desknet=1231231,12312233
In order to obtain the list of Desk-Net status IDs, an HTTP-Request has to be made to
https://api.desk-net.com/#api-Publication_status-GetPublicationStatuses
Feature: Replay-Protection
Whenever changes are made to elements using Kordiam's REST-API, this also causes Kordiam to send an update to related publication platforms of the element (like this K4 integration). In order to prevent an infinite loop of update requests between Kordiam and the K4 integration, changes to articles are not transmitted to Kordiam, when Kordiam updated this article within the last 30 seconds.
Comments
0 comments
Please sign in to leave a comment.