State Clause for the Add Policy Command

This clause defines all information related to a policy state including: who can access a business object, what type of access a user can have, whether new revisions are allowed, and the conditions for changing from one state to another.

This page discusses:

Syntax

state STATE_NAME [STATE_ITEM {,STATE_ITEM}]
  • STATE_NAME is the name of the state you are defining. All states must have a named assigned. This name must be unique within the policy and should have meaning for both you and the user. For more information, see About Administrative Object Names.

For a list of STATE_ITEMs, see Add Policy Syntax

For example, assume you have a process for performing and evaluating lab tests. The first state might involve receiving the initial test request, gathering information on the item or person to be tested, and getting approval for the test. This state could be called “Initial Test Processing” or ‘Test Request.” Once the testing is approved, the test object might enter a second state where the test is actually performed. This state could be called the “Testing,” “Actual Test Processing,” or “Lab Work” state. After the test is completed, the object might then be available for evaluation and review. This final state could be called the “Test Results,” “Test Evaluation,” or “Test Review” state. In each example, the names provide some indication of what is happening to the test object in each state.

When defining a policy, you must have at least one state defined. Within that state, you must define some type of object access. All other information is optional. The sections that follow describe these clauses and the arguments they use.

Action, Check, and Notify Subclauses

The best practice for actions, checks, and notifications is to use triggers instead of these keywords to implement the functionality.

Note: The Action and Check subclauses are no longer supported.

The Action subclause associates a program with the promotion of this state. Once an object is promoted to this state, the program specified by the clause is executed.

Although the Action subclause is optional, it is useful for executing procedures that might notify non-3DEXPERIENCE Platform users, generate reports, or place orders for equipment or services: 

action PROGRAM

  • PROGRAM is the name of a program object, or method, that has been or will be defined by the Business Administrator.

The check subclause associates a verification procedure with the promotion of the object out of the state. The procedure is specified as a program which is executed when a person tries to promote the object. When executed, the procedure returns a true or false value. If the value is true, the object is promoted. If the value is false, the promotion is denied. For more information, see MQL Concepts: Programs.

Use the following syntax to write a Check subclause: 

check PROGRAM
  • PROGRAM is the name of a program object, or method, that has been or will be defined by the Business Administrator.

The notify subclause sends a message to selected users once a business object has entered the state. The message might provide special instructions or notify users that an object is ready for a particular action. The notification message is limited to 255 characters.

Use the following syntax to write a Notify subclause: 

notify USER_NAME {,USER_NAME} message VALUE
Or: 
notify signer message VALUE
  • USER_NAME is the name of a person, group, role, or association to notify.
  • Signer refers to the users who are included in the signature requirements for the next state. This allows one notify message to notify all signers automatically.
  • VALUE is the text of the message to be sent to the user(s).

For example, assume you have a user manual that is being written. In its beginning state, only the author and the author’s manager might access the document. However, once the manual is ready for review, it would most likely be promoted to a state where it is available to other users for comments. When this occurs, users must be notified that the manual is available and that review comments are required. The following subclause notifies two groups that a manual is ready for review: 

notify Engineering, Training
   message "The User Guide is now ready for review. Please have your review comments
    completed in two weeks."

Example of Action, Check, and Notify

Note: The Action and Check subclauses are no longer supported.

Assume that the states of the policy governing a type “Solid Model” are:

Planned —> Started —> Ready for Detail —> Released

Also assume that the states of the policy for Drawing objects are:

Planned —> Submit for Check —> Checked —> Released

When a solid model reaches the “Ready for Detail” state, the drafter begins work on the drawing. An action could be declared at this state to execute a program to create a Drawing business object of the same name as the solid model object. The program also could connect the two objects with the “Solid-Drawing” relationship. When arriving in this state, IconMail is sent (using “notify” in the state definition) to the drafting manager explaining that the solid model is ready for detail and that drawing files are checked into the attached Drawing object.

Before the drawing is released, a check should be performed to be sure the solid model was released. The check would be declared in the transition arrow before the “Released” state of the Drawing policy. The check would execute a program that would expand the object connected by the “Solid-Drawing” relationship and check their current state. If the current state is “Released,” promotion of the Drawing to the “Released” state would be allowed; otherwise, promotion would fail.

Route Subclause

The Route subclause automatically reassigns ownership when an object enters a business state. Since ownership implies greater access privileges and responsibility, changing ownership can be an effective means of controlling an object. The Route subclause is also used to notify the new owner of the reassignments. The route message is limited to 255 characters.

For example, assume you have a manual that was just completed by a writer. The manual is promoted into a state called “Formatting and Editing” in which an editor takes charge of the manual. The editor prepares the document for review and oversees any changes required to prepare it for publication. Since the writer is no longer involved, you might want to assign the manual’s ownership to the editor. While the editor might be among the users notified that the manual is finished, the editor should receive special notification that the manual now “belongs” to him/her. After the manual is published, you might again change the ownership to that of the company librarian. When changes in ownership occur, the new owner should be notified.

The optional Route subclause is similar to the Notify subclause (for more information, see Action, Check, and Notify Subclauses. 

route USER_NAME {,USER_NAME} message VALUE
  • USER_NAME is the name of a person, group, or role who will receive ownership of the business object.
  • VALUE is the text of the message to be sent to the new owners.

For example, the following subclause notifies the editor that ownership of a manual was transferred to that person: 

route Editor message "Ownership of this manual has been transferred to you."

Block and Unblock Subclauses

This subclause hides a state from the user interface so that it cannot be used, but the state still exists. Before executing this clause, any existing objects in the state to be hidden should be promoted or demoted out of that state.

Use this syntax to hide a state: 

state STATE_NAME1 block STATE_NAME2;
state STATE_NAME2 block STATE_NAME3;
  • STATE_NAME1 is the state prior to the state being hidden
  • STATE_NAME2 is the state being hidden
  • STATE_NAME3 is the state after the state being hidden

For example, this command hides the Frozen state by blocking the access to it and from it: 

state Created block Frozen;
state Frozen block Release;

Hidden states do not show in the user interface for searches, and are not available to promote or demote to.

You can unhide a state that was previously blocked. To do so, use this syntax: 

state STATE_NAME1 unblock STATE_NAME2;
state STATE_NAME2 unblock STATE_NAME3;

ACCESS_USER Subclauses

Use the following syntax to define access rules. 

ACCESS_USER ACCESS_ITEM {,ACCESS_ITEM} [{USER_ITEM}]

  • ACCESS_USER is: 
    | [revoke] [login] public [key STRING]         |
| [revoke] [login] owner [key STRING]          |
| [revoke] [login] user USER_NAME [key STRING] |
    • Use the public, owner, and user keywords to specify that this rule applies to everyone (public), the object owner (owner), or to a named role (user USERNAME).
    • With revoke, all accesses specified as ACCESS_ITEMs are rescinded. If all conditions are true, then accesses are rescinded for the current user. Revoke supersedes all other rules. If a rule revokes access for a user, no other rule can grant access to that user.
    • Login specifies that the rule only applies if the role it specifies matches a role associated with the user’s current login context. This is more restrictive than the default, where the system looks at all user assignments to see if a rule applies to any of them.

    The key STRING is a label that differentiates multiple rules defined for the same user. For example, if you have two rules defined for public or for user Designer, you can use the key STRING to need to differentiate them.

    You can use the signature keyword in place of key for rules that represent signatures. If you use the signature keyword, you can only use the approve, reject, or ignore accesses, or the branch or filter keywords.

  • ACCESS_ITEM specifies the kinds of access this rule governs, either granting or revoking access. The ACCESS_ITEMs are described in Access Privilege Definitions. With each ACCESS_ITEM, other than all and none, you can either grant the access or explicitly deny the access. You deny an access by entering not (or !) in front of the ACCESS_ITEM in the command. For example, !todisconnect or notchangeowner.
  • USER_ITEM is: 
    [any | single | ancestor | descendant] organization
    		 
    [any | single | ancestor | descendant] project
    		 
    [any | context] owner
    		 
    [any | no | context | inclusive] reserve
    		 
    [any | public | protected | private | notprivate | ppp] maturity
    		 
    [filter | localfilter] EXPR
    		 
    [branch STATE_NAME]
  • USER_ITEM specifies a variety of ways to define matching options between the current context’s membership in various organization and policy against the project or organization ownership of the object being checked.
    Flag Description
    any|single|ancestor|descendant]organization Specifies that the object’s organization owner must be checked against the context’s member organization.
    any|single|ancestor|descendant] project Specifies that the object’s organization owner must be checked against the context’s member project.
    any owner No check is performed on owner (default).
    context owner Checks that object is owned by context user.
    any reserve No check is performed on whether the object is reserved (default).
    no reserve Checks that the object is not reserved by anyone.
    context reserve Checks that the object is reserved by the current context user.
    inclusive reserve Checks that the object is either reserved by the current context user or by no one.
    any maturity No check is performed on the maturity of the project owning the object (default).
    public maturity Checks that maturity on the collaborative space of the credentials is public.
    protected maturity Checks that maturity on collaborative space of the credentials is protected.
    private maturity Checks that maturity on collaborative space of the credentials is private.
    notprivate maturity Checks that maturity on collaborative space of the credentials is either protected or public.
    ppp maturity Checks that maturity on collaborative space of the credentials is either private, protected, or public.
    [filter | localfilter] EXPR A filter expression defined for the user access. Use localfilter instead of filter in policies and access rules to return only results to which the current user definitely has access. When you use localfilter, the expression is not evaluated by full-text search.

    Expression access filters can be any expression that is valid in the system. Expressions are supported in various modules of the system, for example, query where clauses, expand, filters defined on workspace objects such as cues, tips and filters, and so on. For more information, see Expression Access Filters.

    branch STATE_NAME Indicates the state to move to when the signature is provided. You can include a filter with this keyword. For example: 
    branch FROZEN filter TRUE
    Only one branch is allowed for different access rules per signature, although you can have different filters for different user accesses for a signature.

    If any combination of access definitions match multiple users with different filters, all filters are evaluated. The signature requirement is considered met if ALL applicable filters evaluate to TRUE.

    If a rule is not considered a signature, any branch is ignored.

Rule Subclause

Use the following syntax to define a rule for the state: 

rule RULENAME [all | MAPPED_ACCESS_USER {MAPPED_ACCESS_USER}]
  • all means that all rule items in that rule are added to the state as-is, using the same usernames and the same keys. The owner and public rules with no key are not referenced.
  • MAPPED_ACCESS_USER means that a specific username or username+key is added to the state. If you do not specify a key, then only rule items that match that username 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. MAPPED_ACCESS_USER is: 
    | ruleuser public [ all | rulekey STRING [ statekey STRING]                      |
| ruleuser owner rulekey STRING [statekey STRING ]                               |
| ruleuser USER_NAME [ all | rulekey STRING ] [stateuser NAME] [statekey STRING ]|
    • rulekey STRING is the key defined in the rule
    • statekey STRING is the key to name this access rule for this state
    • stateuser NAME is the username for this access rule for this state

For more information about defining rules, see rule Command.

Every state in a policy includes a built-in owner and public rule. You cannot remove these rules, but you can disable them by setting the access to none. These rules cannot be referenced. If you use all when specifying a rule for the state, all rule items in that rule EXCEPT the public and owner rules that do not have keys are referenced.

You can reference rule items from multiple rules for a single state. However, each referenced rule included in the state must have a unique key.

To include all items in the specified rule to a policy state, use this syntax: 

add policy POLICY_NAME state STATE_NAME rule RULE_NAME all;

For example: 

add policy Parts state Review rule ReviewRule all;

To add a rule to a state that defines specific rule items, use this syntax: 

add policy POLICY_NAME state STATE_NAME rule RULE_NAME ruleuser USERNAME rulekey 
STRING stateuser NAME statekey STRING;

For example: 

add policy Parts state Review rule ReviewRule ruleuser "Design Manager" 
rulekey ManagerAccess stateuser "Manager" statekey ApproveAccess;

This command gives the person Design Manager, which could be a role, the access defined by the key ManagerAccess in the ReviewRule. In the policy, this access shows as user Manager with the key ApproveAccess. The ApproveAccess definition for the state maps to the ManagerAccess rule item defined in the ReviewRule.

This example syntax shows adding a rule with three rule items, and referencing that rule from a policy: 

add rule RULENAME 
    public key KEY1 read,show,checkin 
    owner key KEY2 create,show,read
    user U1 key ExtendedCreateAccessForU1 create

add policy POLICYNAME state STATENAME
    owner rulekey KEY2 key OWNERKEY
    ruleuser U1 rulekey ExtendedCreateAccessForU1 user Designer key ExtendedCreateAccessForDesigner

Signature Subclause

This clause is deprecated. Use signature keyword in place of a key as described in ACCESS_USER Subclauses.

This subclause specifies who can control the promotion or rejection of a business object. When an object is promoted, it moves to the next defined state and is subject to the access rules associated with that state. When an object is rejected, it remains in the current state until it meets the criteria for promotion.

The Signature subclause has the syntax: 

signature SIGN_NAME [SIGNATURE_ITEM {,SIGNATURE_ITEM}
  • SIGN_NAME identifies the type of signature. Try to use a name that identifies what the signature represents. For example, the signature might represent initial acceptance, completion, or final sign-off. Each of these terms could be used for a SIGN_NAME. For more information, see About Administrative Object Names.
  • SIGNATURE_ITEM identifies the type of state change that will occur when a group, role, or person signs off on an object. Use any of the following:
    State Change Description
    approve USER_NAME {,USER_NAME} Specifies that the object can be promoted to the next state. This clause is deprecated. Use the Approve access right for a user.
    reject USER_NAME {,USER_NAME} Specifies that the object must remain in the current state until it meets with the approval of the user. This clause is deprecated. Use the Reject access right for a user.
    ignore USER_NAME {,USER_NAME} Enables you to override the approval or rejection of the object. When ignore is specified, the named user can sign in the place of others. This might be useful to allow a senior manager the ability to sign off for a lower manager. This clause is deprecated. Use the Ignore access right for a user.
    branch STATE_NAME Specifies what the next state will be after a signature is applied.
    filter EXPRESSION Enables filtering to ensure that the promotion of an object meets certain criteria.
    • STATE_NAME is any previously-defined name of a state included in the current policy. By specifying a branch, you can decide which signatures are required to transition to a given state during a promote operation. When promotion is initiated, the system will choose the state for which all signatures are satisfied. If more than one branch is enabled, an error is generated.
    • EXPRESSION is a command that evaluates to either true or false. If a signature requirement 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. The default rule is: 
      current.signature[NAME].satisfied

      which is a select field that means the signature has been approved, ignored, or overridden. When you specify a filter, this default rule is replaced. For help formatting the expressions that can be entered into the Filter area, see the Appendix: Selectables.

      Approval can become dependent on any selectable field of the business object. This includes attributes as well as states and other signatures. The real power of filters comes from the use of combinatorial logic using and’s and or’s between state information and business object information.

    • USER_NAME is any previously defined name of an association, group, role, or person. If the name you give is not defined, an error message will result. If you are unsure of a user name, remember that you can obtain a complete listing of all of the user names by entering the MQL List User command.

For example, assume you have a state where objects are started and worked on prior to general review. While the object is in this state, you might want two types of signatures: one to indicate that the project is complete and another to indicate acceptance. This state definition might appear as: 

state started
   revision false
   public all, notenable, notdisable, notoverride
   owner all, notenable, notdisable, notoverride
   user Manager override
   signature Complete
     approve Writer
     reject Writer
     ignore Manager
   signature Accepted
     approve Manager
     reject Manager
     ignore "Senior Manager"

When including an Ignore Signature item in a state definition, you should not confuse this with the override privilege. The Override privilege allows you to promote an object without any signatures at all. The Ignore Signature item assumes that a signature is required for object promotion. It simply allows the specified person to provide that required signature.

When a signature has been approved, it can subsequently be rejected. But when a signature has been rejected, ignore cannot subsequently be used to satisfy the signature.

Stateproperty Subclause

Integrators can assign ad hoc attributes, called Properties, to a state as well as to the policy as a whole. Properties allow associations to exist between administrative definitions that are not already associated, and can be helpful to programmers implementing additional functionality. The property information can include a name, an arbitrary string value, and a reference to another administration object. The property name is always required. The value string and object reference are both optional. The property name can be reused for different object references, that is, only the name joined with the object reference must be unique for any object that has properties. 

add policy NAME
   state NAME stateproperty NAME [to ADMINTYPE NAME] [value STRING];

To use the Stateproperty clause you must be a business administrator with admin property access. For additional information on properties, see MQL Concepts: Administrative Properties and Property Clause.

Trigger Subclause

Event Triggers allow the execution of a Program object to be associated with the occurrence of an event. The following lifecycle events support Triggers:

approve demote disable
enable ignore override
promote reject schedule
unsign

For example, when a state was scheduled, each successive state could be scheduled automatically by a specified offset value. These transactions are written into program objects which are then called by the trigger.

State Triggers use the following syntax: 

trigger EVENT_TYPE TRIGGER_TYPE PROG_NAME [input ARG_STRING];
  • EVENT_TYPE is any of the valid events for Policies: approve, demote, disable, enable, ignore, override, promote, reject, schedule, or unsign.
  • TRIGGER_TYPE is Check, Override, or Action.
  • PROG_NAME is the name of the Program object that will execute when the event occurs.
  • ARG_STRING is a string of arguments to be passed into the program. When you pass arguments into the program they are referenced by variables within the program. Variables 0, 1, 2… and so on. are reserved by the system for passing in arguments.
  • Environment variable “0” always holds the program name and is set automatically by the system.
  • Arguments following the program name are set in environment variables “1”, “2”,… and so on.

For example: 

state started
   revision false
   public all, notenable, notdisable, notoverride
   owner all, notenable, notdisable, notoverride
   user Manager override
   signature Complete
     approve Writer
     reject Writer
     ignore Manager
   signature Accepted
     approve Manager
     reject Manager
     ignore "Senior Manager"
   trigger schedule action "Schedule Offsets";

Minorrevision Subclause

This subclause specifies whether or not revisions of the object are allowed while the object is in this state.

This subclause uses two arguments: true and false. 

minorrevision [true|false]

  • When the revision argument is set to true, revisions of the object are allowed.
  • If the revision argument is set to false, no revisions are allowed.

For example, the following minorrevision subclause prohibits the creation of a new revision while the object is in this state: 

state "Tax Return Completed"
   minorrevision false
   public none, read
   owner none, read, demote
   user Manager none, read, promote

In this example, you have a state for completed tax forms. In this state, you do not want anyone to revise the objects containing the finished tax returns. If further modification is required, a change in state must occur. The owner can demote the object to its former state to make changes and the manager can promote the object into the audit state.

The Minorrevision subclause is optional. 3DSpace assumes that revisions are allowed if no subclause or argument is used. Use the false keyword to turn off the ability to create revisions.

Version Subclause

This subclause indicates whether or not any file can be checked in while the object is in the state.

Like the Minorrevision subclause described above, this subclause uses two arguments: true and false. 

version [true|false]

  • When the version argument is set to true, files can be checked in.
  • If the argument is set to false, no new files are allowed.

In the following state definition, the Customer or the builder/owner can check in files (that might contain room layouts, exterior views, or electrical plans, for example). 

state “House Design Phase"
   revision false
   version true
   public none, read
   owner all
   user Customer none, read, checkin, modify

The Version subclause is optional. 3DSpace assumes that files can be checked into the object while the object is in the state if no subclause or argument is used. Use the false keyword to turn off the ability to check in files.

Promote Subclause

This subclause specifies whether or not 3DSpace tests the business object for promotion when a signature is modified, and promotes it automatically if all requirements are met.

This subclause uses two arguments: true and false. 

promote [true|false]

  • If the keyword true is used, when a signature is approved or ignored, 3DSpace tries to promote the business object. If all signature and check requirements are satisfied, the business object are promoted automatically. If there are no signatures or check requirements on a state, this setting has no meaning.
  • Use the false keyword to turn auto-promotion off.

If there are no requirements on a State, the promote subclause has no meaning.

Checkouthistory Subclause

The generation of history information on the checkout event is optional. The need to disable checkout history stems from the implementation of distributed databases and the advanced search partial index process. In distributed databases, creating history records requires that a distributed transaction be run across multiple servers. If any server is unavailable, the transaction will fail. This means that all servers must be available to checkout/view files. If checkout history is disabled, only the local server needs to be accessible for the transaction to run to completion.

During a partial index process, business objects are indexed according to their modification date. If checkout history enabled, the history record and the modification date of the business object is updated whenever a file is checked out. Since the modification date is changed, during a partial index process, the business object and its associated files will be indexed again even if the business object has not changed except for the file check out. Disabling checkout can beneficial in preventing a lot of unnecessary indexing, especially if large files are often checked out. This subclause uses two arguments: true and false. 

checkouthistory [true|false]

Splitchangetypeinterfaceaccess Clause

The value of this clause determines which of these methods is used for adding and removing interfaces:

  • If set to true, the addinterface and removeinterface accesses control access for interfaces.
  • If set to false, the changetype access controls access for interfaces.

For example, a user wants to add an interface to an object and access is controlled by a policy state. The system checks the value of the splitchangetypeinterfaceaccess clause to determine if the user has the required access:

  • If splitchangetypeinterfaceaccess is true, the system checks the value of the addinterface access control.
  • If splitchangetypeinterfaceaccess is false, the system checks the value of the changetype access control.

Revoking access using removeinterface works the same way as granting access with addinterface.

When access is inherited by a child business object using mod bus TYPE NAME REVISION add access bus, the value of splitchangetypeinterfaceaccess on the state rule for the business object that the add interface or remove interface action is being attempted on is used. If a user attempts to add an interface to the child business object, splitchangetypeinterfaceaccess on the child business object’s state rule is checked. If the user attempts to add an interface to the parent business object, splitchangetypeinterfaceaccess on the parent business object’s state rule is checked.

Defining ownership inheritance using mod bus TYPE NAME REVISION add ownership bus does not affect the access for the child or the parent business object. If a user attempts to add or remove an interface on a business object that has ownership inheritance, the value of splitchangetypeinterfaceaccess on the state rule for the business object that the add or remove interface action is being attempted on is used.

When adding or removing an interface from a path, MQL checks for modify access to the path (not addinterface, removeinterface, or changetype access).

If splitchangetypeinterfaceaccess is false, printing the business object's state access list does not include the addinterface and removeinterface controls, even if those controls are included in the policy state definition. In addition, the value of this flag is not copied when the policy is copied.

If splitchangetypeinterfaceaccess is set on a policy's allstate, that value is not preserved when exporting and importing the policy. However, MQL only checks the value of the flag for specific states, not for allstate.