Platform-specific Integration

Introduction

This article provides general information about the Platform-specific or Platform Integration for connecting Kordiam to other systems, primarily content management systems (CMS). It is used to sending out data of stories and events including tasks and other information.

For an overview of the different options to connect Kordiam with a CMS see here.

A story in Kordiam can be assigned either to no platform, one platform or several platforms (e.g. to the website, the printed magazine and to a newsletter).

Each one of these platforms can be connected to a different external content management system (CMS) for a bidirectional data exchange. Example:

• An assigned story in Kordiam for platform „any CMS“ creates a task in „any CMS“.
• On the other side: An article, produced in a receiving system („any CMS“), leads/results to a story in Kordiam.
• This feature, by the way, is a performance criterion of Kordiam. Other softwares can't do it like this.

Data is sent over to that external system only if the story is assigned to that platform.

Activation

The integration can be activated by you in the settings/admin area of Kordiam. 

Choose the specific platform, for which you want to set up integration, on the platforms page (https://kordiam.app/objectsPage.htm). Go to Integrations tab and select the desired integration client for this platform.

Then just enter your endpoint’s URL, username and password. 

Authentication process

Step 1: Kordiam Application sends the authorization request to the /oauth2/token endpoint

Step 2: CMS receives the authorization request, then reads the authorization header and decodes it from base64 with a validation of the API User and API Secret (In this step we compare CMS API User/Secret with the received values)

Step 3: If the authorization header is valid, CMS generates a token (you can use your own method for the token generation).

Step 4: CMS sends a response to the Kordiam application.

Step 5: Then for creation the connection from Kordiam to CMS, Kordiam sends POST request to the /statuses endpoint with statuses, connected to the publication.

Trigger rules

When does Kordiam send data and updates?

Updates are sent for next operations:

• a story was created in Kordiam
• a story was updated in Kordiam

The data export is triggered, if at least one of the following fields was changed:

• element title
• element slug
• element status
• element note
• task: assigned user, deadline date and time, task status, task note, task content, cost
• publication: status, publication date and time, platform, category, or type.

On the Integrations tab, you can also set the Publication status, a post needs to be in, to trigger data export to the connected system.

Requests examples

POST "/oauth2/token"

POST "/statuses" - Sent after saving connection settings in Kordiam App)

POST "/publication" - Story was created in Kordiam

PUT "/publication/[publication id]" e.g. "/publication/9369832" - Story was updated in Kordiam

Data sent

For the create/update requests the following data is sent:

• Story ID
• Story title/description
• Slug
• Note
• Story status
• Custom fields
• Publication (i.e. assigned platforms with publishing date etc.) (ID, status (ID, name), platform (ID), category (ID, name), type (ID, name), publishing date and time
• Tasks (task ID, task (ID, name), task status (ID, name), task confirmation status (ID, name), assignee (ID, name, external ID), task note, deadline (date and time), cost (amount, currency), task content info)

JSON example

(an example file is attached at the end of this article)

{
  "id": 12812345234,
  "note": "_note_",
  "elementStatus": 1,
  "description": "_element_title_",
  "publication": {
    "id": 22,
    "status": {
      "id": 3,
      "name": "_pub_status_name_"
    },
    "platform": 23,
    "category": {
      "id": 24,
      "name": "_page_name_"
    },
    "single": {
      "start": {
        "date": "2016-07-22"
      }
    },
    "assignments": [
      true,
      true
    ]
  },
  "tasks": [
    {
      "id": 25,
      "format": {
        "id": 26,
        "name": "_text_"
      },
      "status": {
        "id": 2,
        "name": "Received"
      },
      "confirmationStatus": {
        "id": -2,
        "name": "No feedback requested"
      },
      "assignee": {
        "id": 3,
        "name": "email",
        "external_id": "_external_id_"
      },
      "deadline": {
        "date": "2008-07-21"
        "time": "11:11"
      },
      "note": "_task_note_",
      "cost": {
        "amount": 15,
        "currency": "EUR"
      },
      "content": "<p>TEXT</p>",
      "headline": "_headline_"
    },
    {
      "id": 29,
      "format": {
        "id": 1,
        "name": "_photo_"
      },
      "status": {
        "id": 2,
        "name": "Received"
      },
      "confirmationStatus": {
        "id": -2,
        "name": "No feedback requested"
      },
      "assignee": {
        "id": 3,
        "name": "email1"
      },
      "deadline": {
        "date": "2022-07-21"
      },
      "note": "_task_note_",
      "files": [
        {
          "cmsId": 3040900,
          "filename": "e-mails.png"
        }
      ]
    }
  ],
  "post_id": null
}

In case of any further questions, please ask the Customer Success team at Kordiam: support@kordiam.io.

JSON example file