Cention
API Documentation
Cention Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Cention Errand Report

  • To access Cention Errand Report, a JSON Web Token (JWT) with ‘Access to errand data’ claim attached is needed.
  • To create JWT go to Cention server → Administration tab → API → Access Tokens.
  • Check (tick) ‘Access to errand data’ from Others.
  • Make sure to fill up the Key field else Save button will not be activated.
  • Screenshot:

The API follows JSONAPI specification: http://jsonapi.org/ . Following is some of the specification that must follow:


Migration from old endpoint

  • Must compliance with JSONAPI negotiation.
  • No cookie. Use token with Authorization header.
  • errand/listWhoHasChangedc3_dirty_errand_list/<id>
  • errand/complete/<id>c3_errand_reports/<id>
  • facebook/ratings/listWhoHasChangedc3_dirty_facebook_ratings
  • facebook/ratings/fetch/<id>c3_facebook_ratings/<id>
  • Old format of returned JSON data of X now encapsulate inside {data: {attributes: X}} because of JSONAPI format requirement.

Errand Reports

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_errand_reports/<id> to GET single errand with database ID id (without angle bracket). If the name of your Cention workspace is “demo” and the cention api domain is api.cention.com and the id is 101 then the endpoint would be: https://api.cention.com/s/demo/capi/json/c3_errand_reports/101
  • Errand fetch by this endpoint will clear its dirty flag and will not appears in the request to c3_dirty_errand_list endpoint.
  • Use sparse fields query param to select only required attribute field. Refer to sparse fields specification. For example: https://api.cention.com/s/demo/capi/json/c3_errand_reports/101?fields%5Bc3_errand_reports%5D=sla can be used to only fetch SLA attribute.
  • Sample HTTP request body data format:
{
  "data": {
    "type": "c3_errand_reports",
    "id": "33",
    "attributes": {
      "actions": [
        {
          "id": 83,
          "note": "Errand 33 was opened by agent System Administrator at 2015-07-16 20:50:17 +0800 MYT.",
          "origin": "System Administrator",
          "time": "2015-07-16 20:50:17 +0800 MYT",
          "timeStamp": 1437051017
        },
        {
          "id": 111,
          "note": "Errand 33 was opened by agent System Administrator at 2015-07-17 17:07:48 +0800 MYT.",
          "origin": "System Administrator",
          "time": "2015-07-17 17:07:48 +0800 MYT",
          "timeStamp": 1437124068
        },
        {
          "id": 112,
          "note": "Errand 33 was answered and closed by agent System Administrator at 2015-07-17 17:08:26 +0800 MYT.",
          "origin": "System Administrator",
          "time": "2015-07-17 17:08:26 +0800 MYT",
          "timeStamp": 1437124106
        }
      ],
      "basic": {
        "acquired": false,
        "data": {
          "id": 33,
          "displayId": "33",
          "status": "<img src=\"\/ng\/img\/icons\/ACTION_ANSWER.png\" style=\"vertical-align:middle;\" title=\"Errand has been answered\" border=\"0\"\/> ",
          "service": 1,
          "serviceName": "Email",
          "organisationId": 3,
          "organisationName": "cention-org",
          "area": 1,
          "areaName": "test-services-area",
          "priority": "",
          "agentId": 2,
          "agent": "System Administrator",
          "from": "Cention \u0108\u0108\u0108, Leader (test.account@cention.se)",
          "fromAddress": "test.account@cention.se",
          "fromName": "Cention \u0108\u0108\u0108, Leader",
          "to": "test.tester@cention.asia",
          "toAddresses": [
            "test.tester@cention.asia"
          ],
          "copy": "",
          "copyAddresses": null,
          "subject": "test",
          "iconicSubject": "<img src=\"\/Cention.app\/Resources\/Images\/unassuming-icon.gif\" title=\"From Cention\" style=\"vertical-align:middle;\" border=\"0\"\/> test",
          "body": "<div dir=\"ltr\">test222<\/div>\r\n",
          "date": "2015\/07\/16 20:47",
          "answeredDate": "2015\/07\/17 17:08",
          "donedate": "No Date",
          "attachments": "0",
          "closed": true,
          "deleted": false,
          "answered": true,
          "wasForwardedToExternal": false,
          "wasClonedAndForwardedExternal": false,
          "feedbackAnswer": "",
          "feedbackLink": "",
          "fbPms": false,
          "fbLikes": "",
          "fbAction": "",
          "sendPm": false,
          "hasAnswer": false,
          "answerDeleted": false,
          "retweet": false,
          "twitterPm": false,
          "secureUserId": ""
        },
        "groupWith": 0,
        "hasChild": false,
        "id": 33,
        "style": {

        },
        "threadId": 32
      },
      "c3_id": 33,
      "changed": true,
      "extended": {
        "answer_body": "test body",
        "answer_subject": "test",
        "errand_tags": [
            {
              "desc": "Test High Tag",
              "id": 32
            }
        ],
        "feedback": {
          "Answer": "",
          "QuestionHTML": "",
          "QuestionText": "",
          "value": 0
        }
      },
      "sla": {
       "done_due": false,
       "expiry": 0,
       "handling_time": 0,
       "response_time": 0,
       "within_sla": false
      }
    }
  }
}

Data.attributes.actions

Field Type Description
id Integer Database unique ID of the action object.
note String Human readable note of the action detail.
origin String Agent name that trigger the action.
time String Humann readable time format.
timeStamp Integer Timestamp.

Data.attributes.basic

Field Type Description
id Integer Database unique ID the errand object.
acquired Boolean Whether errand had been acquired by an agent.
groupWith Integer Whether errand within threaded errands.
hasChild Boolean Whether this errand is parent of another errand (reply to this errand).

Data.attributes.extended

Field Type Description
answer_body String Answer text for this errand (agent’s reply).
answer_subject String Subject of this errand’s reply.
errand_tags Array Non-system tags.
feedback Object Feedback data.
report Object Report SLA data.

Data.attributes.sla

Field Type Description
done_due Boolean If the errand done date due. NOTE: this is just compare done date with current date.
expiry Integer Expiry state: 0: no expiry. 1: warning. 2: expired.
handling_time Integer Total handling time in seconds.
response_time Integer Total response time in seconds.
within_sla Boolean If the errand handling within SLA.
  • NOTE: attribute sla return null if the report is processing the data which occur every minute. Expiration may has roughly 5 minutes update delay.

Dirty Errand List

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_dirty_errand_list to get all the errands ID that have changed its content.
  • Use HTTP POST with sam endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_dirty_errand_list to force list of errand marks as changed.
  • Sample HTTP GET request body data format:
{
  "data": {
    "type": "c3_dirty_errand_list",
    "id": "0",
    "attributes": {
      "errands": [
        34,
        3203,
        3204,
        3216,
        3217
      ]
    }
  }
}
  • Sample HTTP POST request body data format (request):
{
  "data": {
    "type": "c3_dirty_errand_list",
    "attributes": {
      "errands": [
        35
      ]
    }
  }
}
  • Sample HTTP POST request body data format (response):
{
  "data": {
    "type": "c3_dirty_errand_list",
    "id": "0"
  }
}

Dirty Facebook Rating List

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_dirty_facebook_ratings to get all the database Facebook rating ID that have changed its content.
  • Sample HTTP GET request body data format:
{
  "data": [
    {
      "type": "c3_dirty_facebook_ratings",
      "id": "3"
    },
    {
      "type": "c3_dirty_facebook_ratings",
      "id": "4"
    }
  ]
}

Facebook Rating

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_facebook_ratings/<id> to get the database for Facebook rating with database ID id (without angle bracket).
  • Facebook rating fetch by this endpoint will clear its dirty flag and will not appears in the next request to c3_dirty_facebook_ratings endpoint.
  • Sample HTTP GET request body data format:
{
  "data": {
    "type": "c3_facebook_ratings",
    "id": "3",
    "attributes": {
      "c3_id": 3,
      "data": {
        "isChanged": false,
        "message": "Hi its a really great page. It helps to find more people:)",
        "rating": 5,
        "ratingId": 3,
        "reviewerId": 2117249628,
        "reviewerName": "Jessica Elizabeth",
        "timestampCreated": 1489569020
      }
    }
  }
}

References:

  1. JSONAPI specification.