Creating an Enrichment Service

An enrichment service is a standard web service that accepts HTTP POST requests from CUE, and responds with a specific subset of HTTP responses understood by CUE. You can create an enrichment service using any web technology or platform you like so long as it conforms to CUE's enrichment service protocol requirements.

When an enrichment service is triggered, CUE sends an HTTP POST request to the enrichment service URL, with an Atom entry in the body of the request. The Atom entry will contain the content item currently being edited in CUE, packaged as a VDF payload document. This is the same packaging that is used to send content items to the Content Engine web service - for details, see the Content Engine Integration Guide.

The enrichment service can then examine the supplied content item, apply tests to it, modify it, modify other content in the Content Engine (via the Content Engine's web service), make use of external web services such as spelling or grammar checkers, publish the content item in external channels and so on. It must, however, finally send one of the following HTTP responses back to CUE:

400 (Bad Request)

The enrichment service can give this response to indicate that the POSTed content item has failed some test or other, and the response can contain an explanatory message that is displayed by CUE. A service that checks for unpublished relations, for example, could send a 400 response if it found any unpublished relations. CUE would then cancel the trigger operation (publish, presumably) and display an error dialog containing the response message – "Cannot publish. There are unpublished related articles."

204 (No Content)

The enrichment service can give this response to indicate that CUE should just carry on as normal. A service that checks for unpublished relations, for example, could send a 204 response if it did not find any unpublished relations: CUE would then simply complete the publish operation that triggered the enrichment service call, and take no further action.

200 (OK)

The enrichment service can give this response in a number of different circumstances. Exactly what it means, and how it is used by CUE depends on the content returned in the body of the response. This can be one of the following types:

text/plain

This response is functionally the same as a 204 (No Content) response from CUE's point of view: the only difference is that CUE displays the text content of the response in an information dialog. An enrichment service that automatically adds the content item to an automatically selected list might, for example, return information about which list the content item has been added to: "Item added to list 'urgent'".

text/html

This response is similar to a 200 response with text/plain content except that the information dialog displayed by CUE will contain formatted HTML.

application/atom+xml

The Atom entry is expected to contain a content item. How the content item is handled depends on the entry's <link rel="self"/> element:

  • If the link element contains the same self URL as the Atom entry originally POSTed by CUE, then it is assumed to be a modified version of the POSTed content item (returned, for example, from a grammar correction service). If the Atom entry contains all the fields originally POSTed by CUE, CUE overwrites the current content item with the returned version and then continues with the operation that triggered the enrichment service call (saving or publishing, for example). If, on the other hand, the Atom entry only contains some of the fields originally POSTed by CUE, then CUE only updates these fields before continuing with the operation that triggered the enrichment service call.

  • If the link element contains a different self URL from the original Atom entry, then CUE opens the referenced content item in a new editor and completes the operation that triggered the enrichment service call (saving or publishing the original content item, for example).

application/vnd.vizrt.payload+xml

This response is a VDF payload document (described in Content Engine Integration Guide). It is expected to contain a sequence of field definitions. CUE constructs and displays a dialog box containing the fields specified in the VDF document, plus an OK and Cancel button. The expectation is that the user will fill in the form and click OK, or else click Cancel.

If the user clicks OK, then the content of the filled form is submitted to the enrichment service URL. The enrichment service can then process the content of the form and respond again in any of the ways listed above. It could, for example, return a 204 (No Content) response, or it could get CUE to display another dialog by returning another 200 (OK) response with a different application/vnd.vizrt.payload+xml. In this way the enrichment service can, if necessary, force CUE to display a long sequence of dialogs before finally performing some operation and terminating the operation that initially triggered the enrichment service.

If the user clicks Cancel, then the operation that triggered the enrichment service is cancelled.