Rich text fields in the Adobe Workfront API
Some objects in Adobe Workfront allow for the storage of text with rich-text formatting. In the Workfront API rich text is stored as JSON using the open source framework Draft.js.
Overview Example
A custom field with rich-text formatting is called Field with rich text and can have the following values associated with it:
Example: A basic GET request to retrieve the value of the custom form field Field with rich text:
GET /attask/api-internal//?fields=parameterValues#
OR
GET /attask/api/v12.0//?fields=parameterValues
Example: This request will return the value of Field with rich text in JSON stored in the parameterValue DE:Field with rich text
{
data: {
ID: "5e85e3f10000b99e8cef10af4e5c6c7b",
name: "Zoom Integration Test",
objCode: "PROJ",
parameterValues: {
"DE:Field with rich text": "{"blocks":[{"key":"dpfce","text":"This is a regular text","type":"unstyled","depth":0,"inlineStyleRanges":[],"entityRanges":[],"data":{}},{"key":"a9ic6","text":"Bold text and regular text","type":"unstyled","depth":0,"inlineStyleRanges":[{"offset":0,"length":9,"style":"BOLD"}],"entityRanges":[],"data":{}},{"key":"1b2a4","text":"Italic text and regular text","type":"unstyled","depth":0,"inlineStyleRanges":[{"offset":0,"length":11,"style":"ITALIC"}],"entityRanges":[],"data":{}},{"key":"4dle1","text":"Underline text and regular text","type":"unstyled","depth":0,"inlineStyleRanges":[{"offset":0,"length":14,"style":"UNDERLINE"}],"entityRanges":[],"data":{}},{"key":"10mip","text":"With all formating and regular text","type":"unstyled","depth":0,"inlineStyleRanges":[{"offset":0,"length":18,"style":"BOLD"},{"offset":0,"length":18,"style":"ITALIC"},{"offset":0,"length":18,"style":"UNDERLINE"}],"entityRanges":[],"data":{}}],"entityMap":{}}",
"DE:Other Type of Field": "Value",
}
}
}
Example: This is a formatted version of the response featured in the figure directly above
{
"blocks":[
{
"key":"dpfce",
"text":"This is a regular text",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
],
"entityRanges":[
],
"data":{
}
},
{
"key":"a9ic6",
"text":"Bold text and regular text",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
{
"offset":0,
"length":9,
"style":"BOLD"
}
],
"entityRanges":[
],
"data":{
}
},
{
"key":"1b2a4",
"text":"Italic text and regular text",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
{
"offset":0,
"length":11,
"style":"ITALIC"
}
],
"entityRanges":[
],
"data":{
}
},
{
"key":"4dle1",
"text":"Underline text and regular text",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
{
"offset":0,
"length":14,
"style":"UNDERLINE"
}
],
"entityRanges":[
],
"data":{
}
},
{
"key":"10mip",
"text":"With all formating and regular text",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
{
"offset":0,
"length":18,
"style":"BOLD"
},
{
"offset":0,
"length":18,
"style":"ITALIC"
},
{
"offset":0,
"length":18,
"style":"UNDERLINE"
}
],
"entityRanges":[
],
"data":{
}
}
],
"entityMap":{
}
}
Blocks
The JSON objects that store the rich-text content are composed of two main parts: blocks and entityMaps.
A block is a JSON object that represents a single-line of formatted text. Since a single custom field can have more than one line of text, each line of text has its own block, and each block is represented as an element in a parent array called blocks.
Example: Here, each line of text from a custom field maps to a block element in the array blocks
Since each block element is also a JSON object, each block is composed of the elements: key, text, type, depth, inlineStyleRanges, entityRanges, and data. Each of these elements functions as the following:
- Key is the unique identifier for that block. The key is used to map a line of text via entityMaps. Details about entityMaps can be found in the entityMaps section of this document.
- Text is the line of text content that is being stored from the custom field.
- Type describes the type of text that is being represented. For example, a line of text being stored in a block could be a part of a list. If that line of text was a part of an unordered list, then its type would be defined as: unordered-list-item.
- Lists are currently not supported, but should be available soon.
- Depth This parameter defines the depth of the line when the line is a nested part of an ordered or unordered list.
- inlineStyleRanges Is an array that describes the type(s) of formatting that were applied to the line of text represented by the current block.
Example: Here is an inlineStyleRanges array that describes each style at the character level. In this case: 9 characters (length: 9) starting from the index 0 (offset: 0) had the style Bold applied:
In the case where multiple types of formatting have been applied to a single line, styles will be mapped to additional elements in the** inlineStyleRanges** array.
Example: Here is what a block would look like when storing a line of text that contains the mixed formatting: Bold text and Italics
{
"key":"a9ic6",
"text":"Bold text and Italics",
"type":"unstyled",
"depth":0,
"inlineStyleRanges":[
{
"offset":0,
"length":21,
"style":"BOLD"
},
{
"offset":14,
"length":7,
"style":"ITALIC"
}
],
...
},
entityMaps and entityRanges
A block of data can potentially contain entities like hyperlinks or other types of stylized formatting that are connected to data sources located outside of the custom text field.
Examples
Retrieving plain text from JSON
When a custom field with rich-text formatting is submitted, all of the text is stored in the array blocks. However, each line of the full text is stored in the text parameter within each of the separate block elements that make up the parent array blocks. So in order to retrieve the full text, each separate line of text needs to be extracted and parced back together. This can be achieved by looping over all of the elements in blocks and concatenating each text parameter together, with a line delimiter (\n).
Example: Here is what your JS might look like:
const parameterValue = JSON.parse('{"blocks":[{"key":"dpfce","text":"This is a regular text","type":"unstyled","depth":0,"inlineStyleRanges":[],"entityRanges":[],"data":{}},{"key":"a9ic6","text":"Bold text and regular text","type":"unstyled","depth":0,"inlineStyleRanges":[{"offset":0,"length":9,"style":"BOLD"}],"entityRanges":[],"data":{}},{"key":"1b2a4","text":"Italic text and regular text","type":"unstyled","depth":0,"inlineStyleRanges":[{"offset":0,"length":11,"style":"ITALIC"}],"entityRanges":[],"data":{}},{"key":"4dle1","text":"Underline text and regular text","type":"unstyled","depth":0,"inlineStyleRanges":[{"offset":0,"length":14,"style":"UNDERLINE"}],"entityRanges":[],"data":{}},{"key":"10mip","text":"With all formating and regular text","type":"unstyled","depth":0,"inlineStyleRanges":[{"offset":0,"length":18,"style":"BOLD"},{"offset":0,"length":18,"style":"ITALIC"},{"offset":0,"length":18,"style":"UNDERLINE"}],"entityRanges":[],"data":{}}],"entityMap":{}}');
let plainText = "";
parameterValue.blocks.forEach((block) => {
plainText = plainText.concat(block.text, "\n");
})
console.log(plainText)
Saving a rich text field value using the Workfront API
To save the following values of a rich-text field using the Workfront API:
Hello World!!!
This is my first Rich Text
-
Construct JSON that represents the value of the rich-text field you are trying to capture by organizing each line of text into a block element, in the array blocks
code language-none { "blocks":[ { "key":"0", "text":"Hello World!!!", }, { "key":"1", "text":"This is my first Rich Text", } ] } -
Capture the rich-text formatting using the inlineStyleRanges parameter
code language-none { "blocks":[ { "key":"0", "text":"Hello World!!!", "inlineStyleRanges": [ { "offset":6, "length":11, "style":"BOLD" } ] }, { "key":"1", "text":"This is my first Rich Text", } ] } -
To capture the second line, the text “Rich Text” must be formatted in both bold and italics.
code language-none { "blocks":[ { "key":"0", "text":"Hello World!!!", "inlineStyleRanges": [ { "offset":6, "length":11, "style":"BOLD" } ] }, { "key":"1", "text":"This is my first Rich Text", "inlineStyleRanges": [ { "offset":17, "length":26, "style":"BOLD" }, { "offset":17, "length":26, "style":"ITALIC" } ] } ], "entityMap":{ } }note note NOTE While entityMap functionality isn’t supported during the initial release, it is still a required field to pass this JSON in a request -
Use the stringify method on the JSON outlined above to make a PUT request and send updates
code language-none PUT /attask/api-internal//?updates={"DE:Field with rich text"="{\n \"blocks\":[\n {\n \"key\":\"0\",\n \"text\":\"Hello World!!!\",\n\t\t\t\t \"inlineStyleRanges\": [\n\t\t\t\t\t\t{\n\"offset\":6,\n\"length\":11,\n\"style\":\"BOLD\"\n }\n ] \n },\n {\n \"key\":\"1\",\n \"text\":\"My first Rich Text\",\n\t\t\t\t \"inlineStyleRanges\": [\n\t\t\t\t\t\t{\n\"offset\":9,\n\"length\":18,\n\"style\":\"BOLD\"\n},\n\t\t\t\t\t\t{\n\"offset\":9,\n\"length\":18,\n\"style\":\"ITALIC\"\n}\n]\n}\n],\n\"entityMap\":{\n}\n}"}