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 the 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 and credentials (username and password).
Authentication process
Step 1: The Kordiam application sends the authorization request to the /oauth2/token endpoint
(Example for WordPress: http://localhost/wp-json/wp-desk-net/v1/oauth2/token).
Step 2: The 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).
Example:
Header name: Authorization
Header value: Basic YXBpXzVkNGJlMDM5NDQwYTkwMDQxMjYyMTU6NWQ0YmUwMzk0NDBjNTQ3OTkwNjM2OQ== (Decode value: api_5d4be039440a9004126215:5d4be039440c5479906369)
Step 3: If the authorization header is valid, the CMS generates a token (you can use your own method for the token generation).
Currently, we do not store received tokens, but fetch a new token with each request. This means we send a new oauth request to get the token each time.
Please note: If the token expires and is replaced on the CMS side, please let us know, otherwise the links of the articles created in the CMS will no longer be returned to Kordiam.
Step 4: CMS sends a response to the Kordiam application.
Example for a successful response:
{"access_token":"mk4m99hy-iuwq-y93x-t36q-x4opshytog3b","token_type":"bearer","expires_in":943199}
Step 5: Then for creation the connection from Kordiam to the CMS, Kordiam sends a POST request to the /statuses endpoint with statuses, connected to the publication.
Note: Since we also have API methods for working with publication statuses, you can also simply get the statuses by calling the Kordiam API (zhe logic of Step 5 is still there for the old versions support).
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
- a story was deleted 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
- element custom fields
- element "deleted" flag
- task: assigned user, deadline date and time, task status, confirmation status, task note, task content, cost, text length, custom fields
- publication: status, publication date and time, platform, category, or type, custom fields.
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":
Request data: “grant_type=client_credentials&api_key=_api_key_&api_secret=_api_secret_”
Successful response example:
{"access_token":"mk4m99hy-iuwq-y93x-t36q-x4opshytog3b","token_type":"bearer","expires_in":943199}
POST "/statuses" - sent after saving connection settings in the Kordiam app):
{"platform":99003,"activeStatuses":[{"id":5,"name":"Published","triggersExport":true},{"id":4,"name":"Top story","triggersExport":true},{"id":2,"name":"Proposal","triggersExport":true},{"id":1,"name":"No Status","triggersExport":true}],"deactivatedStatuses":[{"id":3,"name":"Accepted","triggersExport":false}]}
POST "/publication" - Story was created in Kordiam
PUT "/publication/[publication id]" e.g "/publication/9369832" - Story was updated in Kordiam
{"id":1212538,"slug":"Slug","title": "title","tasks":[{"id":1214010,"format":{"id":18,"name":"Text"},"status":{"id":2,"name":"Received"},"assignee":{"id":99038,"name":"org1@trashmail.com"},"content":"<p>Text message.<\/p>","headline":"Headline"}],"publication":{"id":1157281,"status":{"id":1,"name":"No Status"},"platform":99003,"single":{"start":{"date":"2019-08-13","time":"19:30"}}}}
Important: for /publication and /files requests, Kordiam expects the response:
JSON: {"cmsEditLink": "Link_1","cmsOpenLink": "Link_2","id": 123, "cmsOpenLinkTitle": "Open Link Title", "cmsEditLinkTitle": "Edit Link Title"}
Where
- cmsEditLink - URL to open publication in CMS for edit
- cmsOpenLink - URL to view publication in CMS
- cms_id - Publication id in CMS
- cmsOpenLinkTitle - Title of the open link (to be displayed on Story List only) - optional field
- cmsEditLinkTitle - Title of the edit link (to be displayed on Story List only) - optional field
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, task assignments, custom fields, links to open and edit the element in external system, is publication main (true/false) for the element (if the feature is enabled).
- 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, custom fields)
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}
Common questions
What if my CMS is down?
If the request from Kordiam to your service fails for some reason, we mark it in our logs and try to send the data 5 times more with a 1 sec interval. After that the data is lost.
If you are aware of a problem on your side, you can always get the latest version of the element via API.
In case of any further questions, please ask the Customer Success team at Kordiam: support@kordiam.io.
Comments
0 comments
Please sign in to leave a comment.