Introduction
The Global Export is one of two options for connecting Kordiam with webhooks 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.
Activation
Please ask the Customer Success team at Kordiam to turn on this feature for your organization (support@kordiam.io).
You need to provide us with the URL and token for the system that Kordiam should send the data to. If you connect this webhook to the CMS, we also need a platform (ID) which will serve as the main platform.
Authentication types
We have different methods for webhook authentication, depending on how you want to set up the connection. We have five ways to connect:
- via API and authentication by username token (bearer auth). So here it will be URL and persistent token.
- via SQS (Simple Queue Service)
- via API and authentication by JSON Web Token (JWT authentication). This will also be URL and persistent token
- via Bearer Token, similar to our API. Here we need api_key and api_secret
- via custom header settings
Trigger rules
Kordiam sends data in these cases:
- By default data is sent out regardless of the story status of the story (e.g. Pitch, Accepted, etc.; please note that the Story Status feature may be turned off for your account).
If you are an admin you can ask the Kordiam support team to exclude any status from the trigger logic (support@kordiam.io).
- At least one of the following fields is changed:
-
- Story title/description
- Slug
- Story status
- Note
- Groups
- Custom fields
- Producer (status, assignee, deadline date or time, note, task content, text length, custom fields)
- Publication (status, platform and category, publishing date or time, type, custom fields)
Requests sent by Kordiam
Note that "element" refers to a story and/or event in Kordiam.
- POST "[url]/element" - is sent on a story's/event's creation.
In the response Kordiam expects the model in json: { "id": 123} , where “id” is the story's identifier in your system. That is how the story is linked. - PUT "[url]/element/{id}" - is sent when a story/event is updated.
- DELETE "[url]/element/{id}" - is sent when a story/event is deleted.
The ID that is sent in PUT / DELETE requests is the REST ID that is provided by the external system (your system). This is the ID that Kordiam should receive as a response after an element has been created and sent to the external system. If Kordiam does not receive this ID, Kordiam will send the PUT/DELETE request with an empty (null) value. You can set/update this ID later, using the API.
Data sent
For the create/update requests the following data is sent:
- Story ID
- Story title/description
- Slug
- Note
- Story status (ID, name)
- Story modification date
- Story custom fields (ID, custom field ID, type, value)
- External element description (ID, link; used by external systems such as a CMS to store an ID of that system and a link to it in Kordiam)
- Tasks
(task ID, task (ID, name), task status (ID, name), confirmation status (ID, name), assignee (ID, email, external ID), task note, deadline (date and time), custom fields, text length (ID, name, max value, type (numeric value)), done (true/false) ) - Publication (i.e. assigned platforms with publishing date etc.)
(ID, status (ID, name), platform ID, category (ID, name), type (ID, name), scheduled publishing date and time, actual 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) ) - Groups: ID, name, parent ID, selected (true/false)
Request examples
New story/event creation
URI (to be provided by you): http://desknet.test.url/element
Headers:
{Accept=[application/json, application/*+json], Content-Type=[application/json;charset=UTF-8, Content-Length=[length], Authorization=[Bearer token]}
Request body:
{"id":123456,"tasks":[{"id":121314,"format":{"id":8,"name":"Text"},"status":{"id":1,"name":"Requested"}}],"publications":[{"id":145678,"status":{"id":1,"name":"No Status"},"platform":99999,"single":{"start":{"date":"2021-03-10"}}}],"elementStatus":{"id":1,"name":"pitch"},"title":"TEST request","groups":[{"id":20082,"name":"Team"}]}
Story/event update
URI (to be provided by you): http://desknet.test.url/element/123
Header:
{Accept=[application/json, application/*+json], Content-Type=[application/json;charset=UTF-8], Content-Length=[length], Authorization=[Bearer token]}
Request body:
{"id":123456,"tasks":[{"id":121390,"format":{"id":18,"name":"Text"},"status":{"id":1,"name":"Requested"},"assignee":{"id":1020304,"name":"test@desk-net.com"},"deadline":{"date":"2021-03-10"}}],"publications":[{"id":1157304,"status":{"id":1,"name":"No Status"},"platform":99999,"category":{"id":90000,"name":"Category 1"},"single":{"start":{"date":"2021-03-10"}}}],"elementStatus":{"id":2,"name":"accepted"},"title":"TEST for integration","groups":[{"id":20082,"name":"Team"}]}
Please refer to the API description for the meaning and composition of the fields: https://api.kordiam.app/#api-Story_/_Event_(Element)-GetElement
Note that the API contains more fields than the JSON files that Kordiam exports. If you need to have additional fields included please contact Kordiam support (support@kordiam.io).
JSON example
(an example JSON-file is attached at the end of this article)
{
"id": 13,
"slug": "_element_slug_",
"note": "_NOTE_",
"publications": [
{
"id": 22,
"status": {
"id": 23,
"name": "_pub_status_name_"
},
"platform": 4,
"category": {
"id": 33,
"name": "_page_name_"
},
"type": {
"id": 34,
"name": "_page_element_type_"
},
"single": {
"start": {
"date": "2016-10-30",
"time": "22:45"
},
"issue_label": "_LABEL_"
},
"published": {
"start": {
"date": "2222-02-02"
},
},
"assignments": [
true,
true
]
}
],
"elementStatus": {
"id": 4,
"name": "_NAME"
},
"title": "_element_title_",
"groups": [
{
"id": 19,
"name": "parent Department",
},
{
"id": 20,
"name": "child Departments",
"parent": 19,
"selected": true
}
],
"tasks": [
{
"id": 21,
"format": {
"id": 3,
"name": "_video_"
},
"status": {
"id": 4,
"name": "_approvedStatusCapitalized_en"
},
"confirmationStatus": {
"id": -1,
"name": "_rejectedState_en"
},
"assignee": {
"id": 5,
"name": "email",
"external_id": "_external_id_"
},
"deadline": {
"date": "2011-11-11",
"time": "11:11"
},
"note": "_note_"
},
{
"id": 22,
"format": {
"id": 3,
"name": "_video_"
},
"status": {
"id": 4,
"name": "_approvedStatusCapitalized_en"
},
"confirmationStatus": {
"id": -1,
"name": "_rejectedState_en"
},
"assignee": {
"id": 5,
"name": "email",
"external_id": "external_id"
},
"deadline": {
"date": "2022-02-02"
},
"note": "_NOTE_"
}
],
"modificationDate": "2009-11-10T11:12:00Z",
"externalElement": {
"link": "link",
"id": "rest_element_id"
}
}
Common questions
What if my service 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 3 times more with a 5 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.
How many webhooks can I have?
We allow to establish multiple webhook connections simultaneously, providing the flexibility to accommodate a variety of connectivity needs.
What time zone is used?
All data is sent in GMT (UTC+0).
What publication date will I receive, if a publication has a cross-day time slot?
In cases a selected time slot starts on one day and ends the next day, we send you a publication day as selected day +1.
We scan for new updates each second, however the delivery may take more time, depending on the server load.
Comments
0 comments
Please sign in to leave a comment.