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.
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
- Producer (status, assignee, deadline date or time, note, task content)
- Publication (status, platform and category, publishing date or time, type)
Requests sent by 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.
Note that "element" refers to a story and/or event in Kordiam.
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
- 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), assignee (ID, name), task note, deadline (date and time)) - Publication (i.e. assigned platforms with publishing date etc.)
(ID, status ID, category (ID, name), type (ID, name), scheduled publishing date and time, actual publishing date and time) - 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 try to send the data 3 times more with a 5 sec interval. After that the data is lost.
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.
Comments
0 comments
Please sign in to leave a comment.