This is the high-level description for Desk-Net's integration with K4, which is used to establish a bi-directional communication between Desk-Net 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 Desk-Net automatically creates a story in K4 with subsequent synchronization of data.
The K4 integration can be configured for a specific publication platform within Desk-Net. Whenever elements are created within Desk-Net, 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 Desk-Net using the REST-API of Desk-Net. Keep in mind, that it might take up to 60 seconds for the changes within K4 to be recognized by Desk-Net.
What are the requirements for this integration?
Mainly, you must be a customer of Vjoon K4 and of Desk-Net. 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@desk-net.com for detailed pricing information.
What integration method is being used?
The K4 integration implements the default interface of Desk-Net. In order to enable it within Desk-Net, just use the "Default" integration for Desk-Net 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 Desk-Net to content in K4, we need to make clear what is the corresponding counterpart in each system.
| Desk-Net | K4 | Notes |
| Platform | Publication | Platforms in Desk-Net match publications in K4 |
| Platform-Category | Publication Category | Categories of platforms in Desk-Net match categories of publications in K4 |
| Element | Article | Desk-Net 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 Desk-Net element is represented within the Keywords metadata field of K4 |
| Element-Note | Metadata Desk-Net Notes | The note of a Desk-Net element is represented within the Desk-Net Notes metadata field of K4 |
Runtime Requirements
- The application supports K4 statuses and task workflows. However, statuses can only be set from Desk-Net when articles are created using the status workflow.
- The names of categories must be identical in Desk-Net and K4.
- Single publication dates must be used in Desk-Net.
- The labels of single publications in Desk-Net 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, Desk-Net Element ID, Desk-Net Publication ID and Desk-Net Notes must exist and must be writable within the execution of the Edit Metadata task.
- The configuration (see below) must contain a mapping of Desk-Net platforms to K4 publications.
- The configuration (see below) must contain a mapping of Desk-Net 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 Desk-Net‘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 Desk-Net servers.
mp.jwt.verify.issuer=https://xxx.xxx.xxx/oauth/token
On the Desk-Net 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 Desk-Net. 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 Desk-Net and K4 entities
Every platform channel in Desk-Net 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 Desk-Net 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 Desk-Net 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 Desk-Net's REST-API, this also causes Desk-Net 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 Desk-Net and the K4 integration, changes to articles are not transmitted to Desk-Net, when Desk-Net updated this article within the last 30 seconds.
Comments
0 comments
Please sign in to leave a comment.