How to connect a custom service

In this guide you will be connecting a custom service to Fonto Content Quality to analyze the contents of your documents. The service that you are developing is going to implement the HttpApiAnnotator API and is responsible for returning Fonto Content Quality results where applicable.

What you need

You already have Fonto Content Quality set up. If not, see the Getting started guide.

You are going to create a solution that detects sentiment and suggests the author to rewrite content that has a negative sentiment.

1

Send the content to your service

Configure the analysis file to send the text to analyze to a custom service by using the HttpApiAnnotator.

Note that the HttpApiAnnotator is only able to send textual fragments to your service. XML is not yet supported.

You'll need to add the HttpApiAnnotator to your Content Quality analysis.xml file.

<editor>/content-quality/Configuration/analysis.xml

XML

<?xml version="1.0" encoding="utf-8"?>
<analysis
	xmlns="http://schemas.fontoxml.com/content-quality/1.0/analysis-configuration.xsd"
	xmlns:tutorial="urn:tutorial">

	<sequential>
		<httpApiAnnotator endpoint="http://host.docker.internal:5000/api/sentiment" />
	</sequential>

</analysis>

Notice that we've used host.docker.internal as the host. This resolves to your local machine when using Docker. Use localhost when you use a self contained package.

2

Accept incoming requests

Create a custom service that accepts requests from the HttpApiAnnotator at the given endpoint from the previous step (in this case http://localhost:5000/api/sentiment).

A POST body request example

JSON

{
	"text": "I am feeling down.",
	"annotations": [
		{
			"metadata": {
				"tag": "en-GB"
			},
			"range": {
				"length": 18,
				"startIndex": 0
			},
			"type": {
				"localName": "language",
				"namespaceURI": "urn:fontoxml:content-quality:language:1.0.0"
			}
		}
	]
}

An example request made by the HttpApiAnnotator. Please look at the HttpApiAnnotator documentation page for the detailed API specification.

3

Implement the sentiment logic

Parse the incoming JSON request body and extract the text property.

Check its value for the presence of possible negative words like bad, don't, down, evil and horrible.

As an alternative to this basic implementation of analysis you can forward the extracted text to a 3rd party service for proper sentiment analysis, like Microsoft Azure Text Analytics or Google Natural Language AI.

4

Respond back to Fonto Content Quality

Respond to the HttpApiAnnotator request based on the presence of negative sentiment.

Non-negative sentiment

If you aren't dealing with negative sentiment, reply to Fonto Content Quality with an empty array of results, indicating that there is nothing to annotate in the given text: {"results": []}.

Negative sentiment

If you are dealing with negative sentiment, an annotation for that particular text needs to be created which the Fonto Editor can visualize to the user.

Create a JSON object that represents the annotation. Make sure to:

  • Set the $.range.startIndex and $.range.length to respectively 0 and the text length that you received from the HttpApiAnnotator.

    The range object can be altered to annotate sub-strings of the text. In this guide we annotate the complete text.

  • Set the $.type.namespaceURI and $.type.localName to respectively urn:tutorial and negative-sentiment.

  • Optionally, you could expose additional information to the Editor using the (required) metadata object. This metadata can be visualized in the annotation card or be used in any of the annotation operations.

An example response

JSON

{
	"results": [
		{
			"metadata": {},
			"range": {
				"length": 18,
				"startIndex": 0
			},
			"type": {
				"localName": "negative-sentiment",
				"namespaceURI": "urn:tutorial"
			}
		}
	]
}
5

Configure the editor

Create a visualization for the negative sentiment annotation.

<editor>/packages/content-quality-configuration/src/ui/NegativeSentimentAnnotationDetails.jsx

JavaScript

import React from 'react';

import { Block, Text } from 'fds/components';
import t from 'fontoxml-localization/src/t.js';

const SynonymAnnotationDetails = ({ annotationId, metadata }) => {
	return (
		<Block applyCss={{ marginTop: '8px', marginRight: '8px', maxWidth: '100%' }} flex="none">
			<Text>{t('This content has a negative sentiment. Try to be more positive :)')}</Text>
		</Block>
	);
};

export default SynonymAnnotationDetails;

Register the annotation in the editor in the install.js file of your configuration package.

<editor>/packages/content-quality-configuration/src/install.js

JavaScript

registerContentQualityAnnotationType({
	namespaceURI: 'urn:tutorial',
	localName: 'negative-sentiment',
	heading: t('Negative sentiment'),
	color: 'red',
	icon: 'fas fa-exclamation-triangle',
	CardContentComponent: NegativeSentimentAnnotationDetails,
	decoration: 'wavy-underline'
});

Make sure to import the ./ui/NegativeSentimentAnnotationDetails.jsx.

6

Start the instance

You are now done configuring sentiment analysis using Fonto Content Quality and ready to do a test run. Start the development server and the Fonto Content Quality instance with the respective commands fdt editor run and fdt content-quality run in their respective directories.

If you already had an instance of Fonto Content Quality running, make sure to restart it after making changes that affect the analysis.

If you followed all of the steps of this guide, you will now have Fonto Content Quality configured with sentiment analysis.

Type a sentence that could be characterized as negative by your implementation, e.g.: I am feeling down.. Verify that Content Quality now suggests to rewrite this particular paragraph.

You have integrated a custom service into Fonto Content Quality.