Determining Policy States

This topic describes how to define a policy state. For more information, see MQL Command Reference: policy Command.

When creating a policy, defining the policy states is most often the most difficult part. How many states does the policy need? Who should have access to the object at each state and what access should each person have at each state? Which access takes precedence over the other? Should you allow revisions at this state? Should you allow files to be edited? What signatures are required to move the object from one state to another? Can someone override another's signature? As described below, all of these questions should be answered to write the state definition section of a policy.

This page discusses:

How Many States are Required?

A policy can have one or many states. For example, you might have a policy that governs photographic images. These images could be of several types and formats, but they do not change their state. In general, they do not undergo dramatic changes or have stages where some people should access them and some should not. In this situation, you might have only one state where access is defined.

Let's examine a situation where you might have several states. Assume you have a policy to govern objects during construction of a house. These objects could have several states such as:

State Description
Initial Preparation The building site is evaluated and prepared by the site excavator and builder. After the site is reviewed and all preparations are completed, the excavator and builder sign off on it and the site enters the second state, Framing.
Framing Carpenters complete the framing of the house and it is evaluated by the builder, architect, and customer. In this state, you may want to prohibit object editing so that only viewing is allowed. If the framing is complete to the satisfaction of the builder, architect, and customer, it is promoted to the third state, Wiring.
Wiring The electrician wires the house. However, the electrician may sign off on the job as completed only to have the builder reject it. When approval is rejected, promotion to the next state is prevented from taking place.

As the house progresses through the building states, different persons would be involved in deciding whether or not the object is ready for the next state.

When determining how many states an object should have, you must know:

  • What are the states in an object's life.
  • Who requires access to the object.
  • What type of access they need.

Once a policy is defined, you can alter it even after business object instances are created that are governed by it.

Who Will Have Object Access?

There are three general categories used to define who will have access to the object in each state:

User Category Description
Public Everyone in the database. When the public has access in a state, any define user can work with the business object when it is in that state.
Owner The specific person who is the current owner of the object instance. When an object is initially created in the database, the person who created it is identified as the owner of the object. This person remains the owner unless ownership is transferred to someone else.
User A specific person, group, role, or association who will have access to the object. You can include or exclude selected groupings or individuals when defining who will have access.

For additional information on access privileges, including which access takes precedence over the other, see Controlling Access.

Rules to Determine Access

You can specify the rules for a policy or state to define specific accesses. A rule can contain one or many rule items that define accesses for a user name, or a user name+key. The policy or state can reference all rule items or specific rule items.

If you reference all the rule items (implies no mapping), all the rule items in that rule are added to the policy or state as-is, using the same user names and the same keys. The owner and public rules with no key are not referenced.

If you reference specific rule items (allows full mapping), the policy or state definition identifies which rule items to use based on the user name and key. If you do not specify a key, then only rule items that match that user name and have no defined key are referenced. Owner and public rule items that have a key can be referenced, but the built-in owner and public rules (no key) cannot be referenced.

An error occurs if any rule items use a user name/key already defined for the policy or state, including any owner and public rules.

For more information about the syntax for defining policies and states, see MQL Command Reference: State Clause for the Add Policy Command. For more information about rules, see Rules.

Revisionable Objects

In each state definition are the terms Versionable and Revisionable. The term Revisionable indicates whether a new Revision of the object can be made. Versionable is not used, and setting it has no affect on policy behavior.

You can decide when in the object's lifecycle revisions are allowed by setting the switch ON or OFF in each state definition. This setting is independent of who (which person, role or group) has access to perform the operations.

Published States

Every state has a published flag. In policies where this flag is turned on, a best-so-far (BSF) flag is automatically propagated to business objects that enter such states. By default, the published flag is turned off. You can use the Transition Published-Flags command to incorporate the published flag and to update all business objects governed by policies that have the flag turned on to set the published flag correctly. For more information, see MQL Command Reference: Transition Published-Flags.

The definition of a policy accepts that each of its states can be marked as published. You can set this flag on the state administrative object by invoking the following MQL command: 

mod policy NAME state STATE published TRUE|FALSE;

To determine whether the published flag has been set on an object, you can use: 

print policy NAME select state.published;

To retrieve the Boolean value of the published flag as it is propagated to business objects, use: 

print bus T N R select.current.published;

Major and Minor Revisions

Policies allow definition of two revision sequences, major and minor. You can define a revision sequence for a policy as follows: 

add policy NAME majorsequence A,B,C,... minorsequence 1,2,3	delimiter '-';

If both major and minor sequences are defined, then a delimiter is required. The delimiter is used to concatenate major and minor revision strings for storage in the database, so it must be an ASCII non-alphanumeric character that could never be part of a major/minor revision string calculated from the two sequences.

The Modify Policy command allows you to edit either sequence, but not to change the delimiter or add/remove either sequence, as this would make major/minor revision strings impossible to parse. You can use the Transition Revisions command to add a second sequence to a policy that only one. For more information, see MQL Command Reference: Transition Revisions.

The Print Policy command also allows the corresponding selectables, such as: 

print policy NAME select majorsequence minorsequence delimiter;

Policy and state access definitions have the following access flags:

  • minorrevise controls the Revise Minor command for adding a new minor revision.
  • majorrevise controls the Revise Major command for adding a new major revision.

The following events support defining triggers on types:

  • minorrevision
  • majorrevision

Minorrevision and majorrevision are values derived from the revision field using the policy delimiter. Object uniqueness that incorporates revision information must include both minor and major revision fields. The revision keyword should be used to define such a uniquekey. Therefore, minorrevision and majorrevision are not supported as fields for unique keys.

These capabilities in policy definition have corresponding pieces of data and selectables for business objects.

You can mark any state in a policy to indicate whether it is allowed to create a major/minor revision of an object in that state as follows: 

mod policy NAME state STATE minorrevision TRUE|FALSE	majorrevision TRUE|FALSE;

The terms "minorrevise" and "revise" are synonymous when defining access rules in policy and in the print bus select current.access[minorrevise] command. However, as output from the Print Policy command (for example, print policy select state and print bus select current.access), the earlier "revise" keyword continues to be used for forward compatibility. Likewise, the keyword "revisioned" continues to be used to mark minorrevise events in history.

In the following cases, "revise" and "revision" have the same meaning as long as the object's policy supports ONLY minor revisioning. If, however, the governing policy supports both major and minor revisions, there is a difference:

  • print bus T N R select revision prints the full revision string of the object. If the policy supports both minor and major revisions, this will be major-minor.
  • print bus T N R select revisions prints the full revision string for all objects in the object's minor revision sequence.
  • copy/mod bus T N R name NEWNAME revision NEWREV: NEWREV uses the full revision string (major-minor) as specified in the governing policy.

In an access rule filter:

  • A filter-including expression of the form current.access[ACCESS_TYPE] == TRUE accepts either minorrevise or revise as the ACCESS_TYPE.
  • A filter-including expression of the form current.access ~~ *ACCESS_TYPE* is risky since revise is now be a substring of both minorrevise and majorrevise.

In various places, the kernel outputs the keywords revise/revision or populates macros with such a string. Changing such output could break any application code that depends on the current revise/revision keyword. Although it would be cleaner and more consistent to migrate these outputs to minorrevise/minorrevision, the current output has been retained to satisfy forward compatibility.

  • print bus T N R select current.access maintains revise as the keyword describing minor revise access (for example., current.access == read,modify,revise,show ).
  • The $ACCESS macro can be used in an access rule filter and is populated with the current access being checked whenever the filter is evaluated (for example, the following rule allows a different condition for modify versus revise access): ($ACCESS == modify && <modify-condition>) || ($ACCESS == revise && <revise-condition>)

This continues to be populated as 'revise'.

  • The EVENT macro continues to be populated as 'Revision' to pass to revision triggers.
  • History records still say history = revisioned - user: creator ….

Changing From One State to the Next

Most often a change in state is controlled by one or more persons, perhaps in a particular role or group. For example, during the construction of a house, the customer and the builder might control the change in state. If you break the building stage down into smaller states, you might have the object's transition controlled by the site excavator, foundation expert, electrician, or plumber. As the house progresses through the building states, different persons would be involved in deciding whether the object is ready for the next state. You certainly would not want the carpenters to begin working before the foundation is done.

Signatures are a way to control the change of an object's state. Signatures can be associated with a role, group, person, or association. Most often, they are role-related. When a signature is required, a person must approve the object for the object to move on to the next state. If that person does not approve it, the object remains in the current state until the person does approve or until someone with higher authority provides approval.

More than one signature can be associated with the transition of an object. Lifecycles can be set up such that the signature that is approved determines which state is the next in the object's life. A signature can be approved or rejected. For example, an electrician could say a job is done only to have the builder reject it. When approval is rejected, promotion to the next state is prevented from taking place.

Filters can be defined on a signature requirement to determine if it is fulfilled. If the filter evaluates to true, then the signature requirement is fulfilled. This is useful for adding required signatures that are conditional, dependent on some characteristic of a business object.

Blocking States and Signatures

After a policy has been defined, you might find that you want to remove a state or a signature. After doing so, you can add it back in later if necessary. For example, a policy has these states and signature (in this case, ToCreate is considered a signature because it exits from the normal promotion sequence):

To remove the Frozen state, you need to block the transition from Create to Frozen and from Frozen to Released, and remove the signature ToCreate. You would use these commands to accomplish this: 

modify policy POLICYNAME state Create block Frozen;
modify policy POLICYNAME state Frozen block Released;
modify policy POLICYNAME state Create remove signature ToCreate;

The result would look like this:

To add a state back in that was previously removed, you would use these commands: 

modify policy POLICYNAME state Create unblock Frozen;
modify policy POLICYNAME state Frozen unblock Released;
To add the signature back in, you need to define the signature requirements for that transition. For more information, see MQL Command Reference: Modifying Signature Requirements.