Understanding the *_status configuration files

All of the configuration files named *_status.xml function the same way. This topic explains their structure and how to work with them.

There are *_status configuration files for all the object types in the CCMS, because each of those object types has a workflow.

<cycle>

Each *_status file is divided into multiple <cycle> elements. The specific cycles defined vary depending on the object type the file refers to.

These cycles correspond to the cycles available when searching within the CCMS and also appear in object statuses, such as Authoring:work.

The following defines the Authoring cycle for maps, topics, images, resources, and ditavals:

<cycle collection="/content/authoring/" description="" initial="true" lastworkcycle="true" level="0" name="Authoring" type="work">
	</cycle>

To understand what each part of the <cycle> element means:

  • collection="/content/authoring/": The location of the cycle within the content repository
  • description="": Not used
  • initial="true": "true" indicates that content can be created within the cycle. Typically only the Authoring cycle is "true". The CCMS automatically creates content in the other cycles via specific processes such as localization or deletion.
  • lastworkcycle="true"
  • level="0": Not used for cycles. Value is always 0.
  • name="Authoring": The name of the cycle as it appears in the CCMS.
  • type="work": Corresponds to the function of the cycle. Available types are work, published, localization, translation, deleted, formatted, catchall.

There is generally no reason you should ever have to add a new cycle or change the definition of a cycle. In the rare event this is required for an upgrade, you can find detailed instructions in the Installation and Upgrade Guide for that release.

<state>

Each <cycle> element contains one <states> element, which in turn contains multiple <state> elements.

Each <state> element defines a specific workflow state within the cycle. For example, the Authoring cycle for topics includes the following states: contribute, work, review, approval, done. Therefore, in the topic_status.xml file, the Authoring cycle includes the same five states.

Here is an example of the default contribute state as defined in topic_status.xml file:

<state level="2" name="contribute" type="contribute" color="0;17;43">
     <lockable>
          <objtypes>
               <type>all</type>
          </objtypes>
     </lockable>
     <nextStates>
          <next>work</next>
     </nextStates>
</state>

To understand what each part of the <state> element means:

  • level: The level of this state as it relates to other states. The number itself is not important, only its relative value to other states in the cycle.
  • name: The name of the state as it appears in the CCMS.
  • type: Corresponds to the function of the state. Available types are contribute, start, work, review, end, cancelled, approval, maintenance, delivery, external. These are described below.
  • drop: Indicates that this status should be used to resolve ambiguity when there are two statuses with the same @level value to which an object could move in the case of a workflow status change cascade.
  • onlySubstantial: Not used
  • color: An RGB definition for the color used in the Show statistics pie chart in the DITA Map view (CCMS Desktop only) to represent objects at this state.
  • <lockable> > <objtypes> > <type>: Values are "all" to indicate objects at this state can be locked or checked out and "none" to indicate objects at this state cannot be locked.
  • <nextStates> > <next>: Indicates the states that an object can move to from this state. You can add as many <next> elements as appropriate. Each target state is defined with a <next> element regardless of whether the move is forward or backward in the workflow.

<state> types

contribute: Applies only to topics. It is virtually identical to the work type but generally designates that a topic is being worked on by a SME rather than a Writer.

start: Applies only to states for objects which are generated by the CCMS—Approvals, Collaborative Reviews, and Translation Manifests. The workflows for these objects include states named new and creating, both of which are of the start type.

work: Applies to most objects and indicates that the state is one in which the object can be locked and edited. Most writing and editing are done in work-type states.

review: Applies to content objects as well as to Build Manifests, Collaborative Reviews, and Snapshots. In the default configuration, objects at a review state cannot be edited.

end: Applies to most objects and indicates that the state is the final, or "finished" state for the object. Objects at an end state cannot be edited.

cancelled: Applies only to states for objects which can be cancelled—Approvals, Collaborative Reviews, and Translation Manifests. The workflows for these objects include states named cancelled and rejected, both of which are of the cancelled type. Objects at a cancelled state cannot be edited.

approval: Applies only to states for objects which can be approved—Approvals, maps, and topics. The workflows for these objects include states named approved, approval, and complete, all of which are of the approval type. In the default configuration, objects at an approval state cannot be edited.

maintenance: This type is used for DRM versions only and designates a maintenance branch, which has very specific characteristics within the CCMS.

delivery : This type is used for DRM versions only and designates a delivery branch, which has very specific characteristics within the CCMS.

external: Objects imported using the Import as external option are imported to the state defined using this type. These objects are read-only and cannot be moved to any other state. This state type is used only within the Authoring cycle and should be unique within that cycle.

<state> levels and workflow dependencies

The CCMS enforces a logical relationship between the statuses of parents and children.

For example, say you have a map with a number of topics. You would expect that after each topic has reached its end-type status (Authoring:done in the default configuration), you could then move the map to its end-type status (also Authoring:done in the default configuration).

It would be illogical if you could move the map to done before all its topics were at done. After all, a map can't be done if some of its topics are still being actively authored or reviewed.

Likewise, if a map is at done, but some of its topics have to go back for additional work, the map should no longer logically stay at done.

The CCMS enforces this logic, called workflow dependencies, by forcing a status change when necessary. In the first example above, the CCMS does not allow you to move the map to done when some of its topics are still at other statuses. CCMS Web conveniently enables you to move those topics and then move the map all at once, but you still must move the topics in order to move the map.

In the second example, if you move one of the map's topics back to work, the map must move back to work as well.

You can say that done is a higher state than work. What makes it higher? The level associated with the state. In the default configuration, the topic work state is level 3 and the done state is level 10. The map work state is level 2 and the done state is level 10.

Workflow dependencies dictate that "a parent cannot be at a higher state than its child." Therefore, a map at level 10 (done) cannot have a child that is at level 2 (work). If a map it at level 10 and you move one of its children from level 10 back to level 3 (work), the map must move to a level that is equal to or lower than 3—in the default configuration, the only option is level 2 (work).

Workflow dependencies do not apply in the opposite direction. That is, a child can be at a higher state than its parent. It's quite common for a map at work to have some topics at work, some at review, some at complete, and some at done.

For a list of the parent-child relationships that are affected by workflow dependencies, see Workflow dependencies.