Yellow Data

Use Yellow Data to add custom information to documents without lock and state changes.

Table of Contents

What is Yellow Data?

Yellow Data can be used to save information in Sophora documents without locking or changing their state.

Imagine a published document that should automatically be enriched with additional background information while a user has opened it in the Sophora DeskClient: Without using Yellow Data the Sophora Importer would need to lock, modify, save, and then unlock the document. The document's state would result in the "in progress" state, and the user that has opened the document before that process would have lost their document lock. The user would need to reopen the document, and they would also have to publish it again, if the Importer did not do that. In the end, the user is likely to be annoyed, and each republish results in a new document version. By using Yellow Data the document is still published after adding the information without locking the document in the first place.

Note that Yellow Data will be versioned just like any other data in a document.

Yellow Data Types

Sophora has some built-in Yellow Data types: Sticky Notes, Merge Info and social media publications. See below on how to implement custom types.

Sticky Notes

See the user documentation on Sticky Notes for further information. Technically, Sticky Notes are Yellow Data of the type sophora-nt:stickyNote. To import Sticky Notes via Sophora XML please see the section "Sticky Notes of a Document" in the Importer documentation.

Merge Info

See the user documentation about merging of document content for further information. Technically, Merge Info are Yellow Data of the type sophora-nt:mergeInfo. To import Merge Info via Sophora XML please see the section "Mergeable Properties and Child Nodes" in the Importer documentation.

Social Media Publications

The Yellow Data for social media publications is set by the Social Media Connector automatically each time a document is published via the Social Media Connector, for example to Facebook or Twitter. Technically, social media publications are Yellow Data of the type sophora-nt:socialMediaPublication.

Custom Yellow Data Types

To create a custom Yellow Data type you need to create a custom node type with properties to hold your data, for example:

<'sophora-content'='http://www.subshell.com/sophora-content/1.0'>
<'sophora-content-nt'='http://www.subshell.com/sophora-content-nt/1.0'>
['sophora-content-nt:customYellowData']
  orderable
  - 'sophora-content:info' (string)

You may use single value properties of type boolean, date, double, long, and string. Multi value properties are not supported.

Finally your node type must have the mixin sophora-mix:yellowData. That's it. Now you can read/write the data via API, Importer or Delivery.

Reading/Writing Yellow Data

Reading/Writing Using the DeskClient

With the exception of Sticky Notes users cannot directly edit Yellow Data in the document editor of the DeskClient. For custom Yellow Data types you may create a Client Script and use the ISophoraClient to modify the data (see next section).

Reading/Writing Using the Client API

The ISophoraClient interface provides the following methods to read/write Yellow Data:

YellowData saveYellowData(UUID documentUuid, YellowData data)
void deleteYellowData(UUID documentUuid, String dataId)
List<YellowData> getYellowData(UUID documentUuid)
List<YellowData> getYellowData(UUID documentUuid, String type)

Each YellowData object has a type, an identifier, a last modifier, a modification date, and a set of property values. The identifier can be any string, or it is a generated UUID if no identifier is specified. YellowData objects can be created using the following constructors:

YellowData(String nodeTypeName)
YellowData(String nodeTypeName, String id)
YellowData(String nodeTypeName, String id, String lastModifier, Calendar modificationDate, Set<IProperty> properties)

Example 1: Add/Overwrite Yellow Data on a Document

public static void main(String[] args) {
	SophoraClientFactory factory = new SophoraClientFactory("localhost:1199", "admin", "admin");
	ISophoraClient client = factory.createSophoraClient();
	try {
		client.login();
		UUID documentUuid = UUID.fromString("e6907385-410d-4611-a73b-736928fffe17");
		YellowData yellowData = new YellowData("sophora-content-nt:customYellowData", "custom-id-123");
		yellowData.setString("sophora-content:info", "My custom info");
		client.saveYellowData(documentUuid, yellowData);
	} finally {
		client.logout();
	}
}

Example 2: Read Yellow Data from a Document

public static void main(String[] args) {
	SophoraClientFactory factory = new SophoraClientFactory("localhost:1199", "admin", "admin");
	ISophoraClient client = factory.createSophoraClient();
	try {
		client.login();
		UUID documentUuid = UUID.fromString("e6907385-410d-4611-a73b-736928fffe17");
		List<YellowData> yellowData = client.getYellowData(documentUuid, "sophora-content-nt:customYellowData");
		for (YellowData data : yellowData) {
			System.out.println(data.getString("sophora-content:info"));
		}
	} finally {
		client.logout();
	}
}

Importing Custom Yellow Data

Custom Yellow Data can be imported via Sophora XML like any other child node. Note that all Yellow Data of a document are stored in the same child node sophora:yellowData of the type sophora-nt:yellowData.

Example Sophora XML

<?xml version="1.0" encoding="UTF-8"?>
<documents xmlns="http://www.sophoracms.com/import/3.4">
  <document nodeType="sophora-content-nt:story" externalID="e6907385-410d-4611-a73b-736928fffe17">
    <properties />
    <childNodes>
	  <childNode nodeType="sophora-nt:yellowData" name="sophora:yellowData">
        <properties />
        <childNodes>
          <childNode nodeType="sophora-content-nt:customYellowData" name="sophora:yellowDataEntry">
            <properties>
              <property name="sophora:dataId">
                <value>custom-id-123</value>
              </property>
              <property name="sophora-content:info">
                <value>My custom info</value>
              </property>
            </properties>
            <childNodes />
            <resourceList />
          </childNode>
        </childNodes>
        <resourceList />
      </childNode>
    </childNodes>
    <resourceList />
    <fields>
      [...]
    </fields>
    <instructions>
      [...]	  
    </instructions>
  </document>
</documents>

Reading Yellow Data in Delivery

All Yellow Data are replicated automatically to the staging slaves if the containing document is in the "published" state. Affected HTML cache entries are invalidated in this case as if the document had been changed (see the section "Details about Cache Update" of the Delivery Caching documentation.)

The Yellow Data of a document can be accessed by the node function ${documentMap.yellowData['typeName']} or by using the IContentMapContext method List<YellowData> getYellowData(UUID documentUuid, String type) when you create your own models. Please see the sections "Default function of the Sophora Content Map" and "Implementing Custom Functions" in the Template Development documentation.