Reference of all API calls available. Consult also the concepts documentation and the Swagger documentation available for the interactive version of the API.

Notifications are callbacks to the customer’s system that keep customers informed of certain events related to a specific task. Notifications for the following events can be configured:

  • TASK_COMPLETED: This event is triggered when all work related to the task, including the customer’s review, has been completed.
  • TASK_TIMEDOUT: This event is triggered when the maximum duration or due date for the task has elapsed and the task has not been completed.
  • CUSTOMER_INPUT_REQUIRED: This event is triggered when additional input is required from the customer, such as approval of an article.

A notification can be registered during task creation.

Attributes

Name Type Access Description
id Integer r/- The notification id
href URI r/- The Notification unique resource identifier
event String r/w The symbolic event name. The following codes are defined: TASK_COMPLETED, TASK_TIMEDOUT,CUSTOMER_INPUT_REQUIRED
callback_url URL r/w The callback URL
callback_method String r/w The HTTP method, one of GET or POST
payload_format String r/w Payload format indicator, either XML or JSON. Only supported if method is set to POST. The actual paylot will be a copy of the selected Task entity in the requested format.

Representation

  • XML Representation
<notification>
  <link
href=”[context]/customer/tasks/${task_id}/notifications/${id}”
rel=”self” type=”application/xml” />
  <event>${event}</event>
  <callback_url>${callback_url}</callback_url>
  <callback_method>${callback_method}</callback_method>
  <payload_format>${payload_format}</payload_format>
</notification>
  • JSON Representation
notification: {
  link: [{
    href: ”[context]/customer/tasks/${task_id}/notifications/${id}”,
    rel: “self”,
    type: “application/json”
  }],
  event: “${event}”,
  callback_url: “${callback_url}”,
  callback_method: “${callback_method}”,
  payload_format: “${payload_format}”
}

Notification Payload

The Notification sent to the given “callback url” will contain the following information:

  1. The event code, as described above
  2. The URI of the task that triggered the event

If ${callback_method} was set to POST, the Notification payload will be the only element in the body of the request. If the method was set to GET, the notification will be a URL-compliant serialization of the data and become the value of a query string parameter named “payload”.

Please note that because of URL length restrictions, the use of the POST method is highly recommended!

  • XML Example
<notification>
  <link href=”/api/marketplace/v2/customer/notifications/1234” rel=”self” type=”application/xml” />
  <event>CUSTOMER_INPUT_REQUIRED</event>
  <task>
    <link href=”/api/marketplace/v2/customer/tasks/1234”
    rel=”task”
    type=”application/xml” />
  </task>
</notification>
  • JSON Example
notification: {
  link: [{
    href: ”/api/marketplace/v2/customer/notifications/1234”,
    rel: “self”,
    type: “application/json”
  }],
  event: “CUSTOMER_INPUT_REQUIRED”,
  task: {
    link: [{
      href: “/api/marketplace/v2/customer/tasks/1234”,
      rel: “task”,
      type: “application/json”
    }]
  }
}

Operations

List Registered Notifications

There are two ways to index Notifications associated with the customer:

  1. View all Notification instances that are associated with the customer
  2. View only Notifications that are associated with a specific task

Request

Request line:

GET [context]/customer/tasks/${id}/notifications/

or

GET [context]/customer/notifications/

Request parameter:

Name Type Synopsis Mandatory
id Integer The auto-generated Task id, as returned by the Create Task operation Yes

Request body: (empty)

Response

Response status:

  • 200, if the request could be handled successfully (even if there are no notifications)

  • 404, if the addressed Task does not exist Response body:

  • XML Example
<notifications_response>
  <request_status>...</request_status> 
  <notifications>
    <link href=“/api/marketplace/v2/customer/tasks/1234/notifications/ 1 ”
    rel=”self” type=”application/xml” />
    <event>TASK_COMPLETED</event>
    <callback_url>http://notification.example.com/</callback_url>
    <callback_method>POST</callback_method>
    <payload_format>XML</payload_format>
    <author_id>111</author_id>
    <task_id>1234</task_id>
  </notifications>
</notifications_response>
  • JSON Example
notification_response: {
  request_status: ... ,
  notifications: [{
    link: [{
      href: “/api/marketplace/v2/customer/tasks/1234/notifications/ 1 ”,
      rel: “self”,
      type: “application/json”
    }],
    event: “TASK_COMPLETED”,
    callback_url: “http://notification.example.com/”,
    callback_method: “POST”,
    payload_format: “JSON”,
    author_id: “ 111 ”,
    task_id: “ 1234 ”
  }]
}
Tags: