Modify Business Object

Syntax

This command lets you add or remove defining clauses or change some of their values.

modify businessobject OBJECTID [MOD_ITEM {MOD_ITEM}] [SELECT 
[DUMP] [RECORDSEP] [tcl] [output FILENAME]];

• OBJECTID is the OID or Type Name Revision of the business object you want to modify.
• MOD_ITEM is the type of modification you want to make. Each is specified in a Modify Businessobject clause, as listed in the following table. You only need to specify the fields to be modified.

  Modify Businessobject Clause	Specifies
  description VALUE	The current description, if any, is changed to the value entered.
  image FILENAME	An image to associate with the business object.
  vault vault_NAME [update set]	The business object is moved from the current vault to the new vault specified here. For more information, see Changing a Business Object’s Vault .
  name NAME [revision REVISION]	The name, and optionally the revision, of the business object are changed to the name and revision specified here. The revision should be specified as the full revision string (major-minor) as specified in the governing policy. For more information, see MQL Concepts: About Major and Minor Revisions. For the list of characters that cannot be used for the Name, see Add Business Object.
  owner USER_NAME	The owner of the business object is changed to the owner specified here.
  add ownership | ORGANIZATION PROJECT [for COMMENT] [as ACCESS]| | businessobject BO_NAME [for COMMENT] | | relationship OBJECTID [for COMMENT] |	Adds an ownership to the business object. For more information, see MQL Concepts: Multiple Ownerships and Adding or Removing Business Object Ownerships.
  remove ownership | ORGANIZATION PROJECT [for COMMENT] [as ACCESS]| | businessobject BO_NAME [for COMMENT] | | relationship OBJECTID [for COMMENT] |	Removes an ownership from the business object. For more information, see MQL Concepts: Multiple Ownerships and Adding or Removing Business Object Ownerships.
  add ownership bus|rel OWNERSHIP_ID	Adds an ownership that is inherited from another object or relationship. For more information, see MQL Concepts: Ownership Inheritance and Adding or Removing Business Object Ownerships.
  grant USER access ACCESS{,ACCESS} {grant USER access ACCESS{,ACCESS} [key KEY]	The specified access to the object is granted to the user(s) specified. For more information, see Granting Business Object Access.
  revoke all|grantee|grantor [USER]] {grantee|grantor [USER]} [key KEY]	Access that has previously been granted to another user is revoked. For more information, see Revoking Business Object Access.
  policy POLICY_NAME	The policy of the business object is changed to the policy specified here. The current state of the business object is retained if that state is a state of the new policy. If you change an object's policy you might inadvertently change the store used by the object. In this case, newly checked in files will be kept in the new policy's store. If the object contained it's own files before the policy was changed, they will stay in the old store, until/unless they are replaced during a subsequent checkin. However, the old store will still be used in the case where another object contains a reference to files in the object that now uses a different store. When the time comes for the reference to become an actual file (as when the file list changes between the 2 objects) the file copy is made in the same store the original file is located in.
  move [format FORMATNAME] from BO_NAME FILES_TO_COPY;	The specified FILES_TO_COPY are removed from the from BO_NAME to the business object being modified. For more information, see Moving Files.
  [!|not]published	Marks the business object as being published or not being published. For more information see MQL Concepts: Published States.
  state STATE_NAME | schedule | DATE | actual |	The date associated with the beginning of a state is changed as specified here.
  current NEW_STATE_NAME	Sets the current state of the businessobject to the specified STATE_NAME.
  rename [format FORMATNAME] [[!|not]propagaterename] file FILENAME TOFILENAME	The specified FILENAME is changed to TOFILENAME. For more information, see Renaming Files.
  reserve [user USER] [comment COMMENT];	To attach reservation data to an object: username, date, optional comment. The user clause can be included only by system administrators to reserve a connection on behalf of someone else. The Reserve access mask controls the changing of the reserve status of an object or connection. For more information, see Modify Connection.
  unreserve	To attach reservation data to an object: username, date, optional comment. The user clause can be included only by system administrators to unreserve a connection on behalf of someone else. The unreserve access mask controls the changing of the reserve status of an object or connection. For more information, see Modify Connection.
  !reserve	To attach reservation data to an object: username, date, optional comment. The user clause can be included only by system administrators to reserve a connection on behalf of someone else. The reserve access mask controls the changing of the reserve status of an object or connection. For more information, see Modify Connection.
  type TYPE_NAME	The type associated with the business object is changed as specified here. Attributes of the business object which are part of the new type definition are retained. Attributes which are not part of the new type definition are deleted. Any new attributes are added with their default value.
  ATTRIBUTE_NAME VALUE	The attribute value associated with the business object is changed as specified here. If the attribute has a dimension defined, include the units for the value. If you do not provide the units, MQL uses the default unit of measurement for the dimension, which might not be what you intend. When changing the value to a different value with the same units as the original, you still need to include the units or the default units will be used.
  add interface INTERFACE_NAME	Adds the specified interface to the business object. For more information, see interface Command.
  remove interface INTERFACE_NAME	Removes the specified interface from the business object.
  add access ACCESS_ID [as MASK]	Add the specified access to the business object, optionally as a mask. For more information, see Access Privilege Definitions.
  remove access ACCESS_ID	Removes the specified access.
  add history VALUE [comment VALUE]	A history Tag and a Comment can be specified with this clause. The Tag is the VALUE you enter after add history as a name for the custom history entry. A user/time/date/current stamp is automatically applied when this command executes. The comment is the VALUE (or text) you enter to describe the history item you are adding.
  delete history [ITEM {ITEM}]	System administrators only can purge the history records of a business object. For more information, see Delete History.
  originated DATE	Business Administrators only can modify the originated basic property of a business object. DATE must be in the format specified in the environment. For more information, see the Installation Guide. There currently is no history or trigger event associated with this event.
  modified DATE	Business Administrators only can modify the modified basic property of a business object. DATE must be in the format specified in the environment. For more information, see the Installation Guide. There currently is no history or trigger event associated with this event.
  updatestamp STAMP	The stamp value is a DCE UUID 16 byte ID used by applications to mark significant changes to the businessobject.
  vcconnection [index NUMBER] VC_MOD_ITEM{,VC_MOD_ITEM}	Add a DesignSync File Access connection using the optional index NUMBER (identifier number unique among all connections).

  Where VC_MOD_ITEM is:

  VC_MOD_ITEM Clause
  incomplete
  complete
  store NAME
  format NAME
  path STRING
  description STRING
  versionid STRING
  versiontag STRING
  branchid STRING
  branchtag STRING
  selector STRING
  qualifier STRING
  config STRING
  lock
  unlock
  copyfromstore NAME path STRING [VERSION]
  copyfromstore NAME path STRING [config STRING]
  add versiontag STRING
  remove versiontag STRING
  add branchtag STRING
  remove branchtag STRING

  Where VERISON:

  VERSION Clause
  versionid STRING
  versiontag STRING
  branchid STRING [qualifier STRING]
  branchtag STIRNG [qualifier STRING]
  selector STRING

Each modification clause is related to the clauses and arguments that define the business object. When you modify a business object, you first name the object to be changed (by type, name, and revision) and then list the modification using the appropriate clauses.

Reserving a Business Object

To mark the business object or connection as reserved:

The businessobject “Thomas” of type “Box Design” and revision “A” is reserved.

When a reservation is made, the following information is sent for storage in the database:

• Person reserving the object.
• Time when the object is reserved.
• Comments entered when the reservation is made.

The comment string is optional and has a 254 character limit. Comments longer than 254 characters are truncated and only the first 254 characters are stored in the database.

You can use reservation data to control concurrent modification in two ways:

• Code controlling the display of an editing page can check the reserved status beforehand, and reject the editing request if the object is reserved.
• Define access rules to control any access. For more information, see ACCESS_USER Subclauses.

The data is written to the database only upon transaction commit. The reserved status of a business object or connection is true only if a user has reserved it and has committed the transaction containing the modify reserve command.

System administrators can include the user clause to reserve an object on behalf of another user:

The businessobject “Thomas” of type “Box Design” and revision “A” is reserved for Sue by the super user (a user that must be defined as a system administrator).

The privilege to reserve or unreserve an object can be specific in access rules using the reserve and unreserved access mask. For more information, see ACCESS_USER Subclauses. Unreserving a business object or connection by providing the wrong OID or Type Name Revision will result in an error message. Unreserving a business object or connection that is not reserved will result in a warning.

Changing a Business Object’s Vault

When an object’s vault is changed, by default the following occurs behind the scenes:

• The original business object is cloned in the new vault with all business object data except the related set data.
• The original business object is deleted from the old vault.

When a business object is deleted, it also gets removed from any sets to which it belongs. This includes both user-defined sets and sets defined internally. IconMail messages and the objects they contain are organized as members of an internal set. So when the object’s vault is changed, it is not only removed from its sets, but it is also removed from all IconMail messages that include it. In many cases the messages alone, without the objects, are meaningless. To address this issue, you can fix sets at the time the change vault is performed (in MQL only). For example:

modify bus Assembly R123 A vault Engineering update set; 

The additional functionality could affect the performance of the change vault operation if the object belongs to many sets and/or IconMails, which is why you must explicitly ask the system to do this.

Business administrators can execute the following MQL command to enable/disable this functionality as the default behavior for system-wide use:

set system changevault update set | on | off |; 

A business object can appear to have two id's if it moves from one vault to another. However, there is only one real id (in the current vault). The record in the old vault is kept to redirect to the record in the new vault to avoid the following errors for programs that might continue to operate on the object with the old id to complete their task:

'business object stale' and 'business object id not found' 

Querying for the object using Type Name Rev Vault will not return these errors. The old records are cleaned during the original vault cleanup.

Granting Business Object Access

Any person can grant accesses on an object to any other user as long as the person has grant access. The grantor is allowed to delegate all or a subset of his/her accesses on the current state.

The MQL command and Studio Customization Toolkit methods for granting business objects allow users to:

• Grant an object to multiple users
• Have more than one grantor for an object
• Grant to any user (person/group/role/association)
• Use a key to revoke access without specific grantor/grantee information

Users cannot grant the grant access itself. The intent is to provide just 1 level of delegation. Although including grant in the list of accesses will not fail, the grantee of the grant access will not be able to grant, unless s/he already has grant access.

For more information, see Controlling Access.

Granting Access to Multiple Users

You can use one modify bus command to grant an object to multiple grantees with the same or different accesses.

To grant an object to multiple grantees, each with different accesses use:

modify bus OBJECTID grant USER access ACCESS{,ACCESS} {grant USER access ACCESS{,ACCESS} ;

• OBJECTID is the OID or Type Name Revision of the object you want to modify.
• USER is any person, group, role or association;
• ACCESS is any of the different accesses that need to be provided to the grantee. For more information, see Access Privilege Definitions.) At least one ACCESS must be specified, or none are given. The ! can be used with any access with the keyword all to provide all privileges the delegator has, except those specified.

  For example:

  modify bus Assembly SA-4356 A grant Engineering access all, !checkin;

  This command will provide Engineering with all accesses except checkin. However, the Engineering group will only be able to perform operations for which the grantor has access (with the exception of checkin). “All” is evaluated just like other access items, and exceptions to “all” must delimited with a comma.

To grant an object to more than one grantee with the same accesses use:

mod bus TYPE NAME REVISION grant USER{,USER} access ACCESS{,ACCESS} ;

For example:

modify bus Part Sprocket 3 grant Jo,Jackie,Jules access read,modify ;

Subsequent modify bus commands with the grant clause will overwrite, (not add to) the granted accesses and users only if the grantor and grantee match an existing grantor/grantee pair on the business object. If either the grantor or grantee of the pair does not match an existing pair, an additional set of accesses will be granted for the object.

Granting Access Using Keys

Profile management tasks in apps typically perform all grants from the same grantor, which makes identifying/modifying individual grants very difficult for the programmer. When granting business objects via MQL (or MQLCommand), it is possible to specify an identifier, or key, for each individual grant. Grants can then be revoked by referencing this key with or without the grantor/grantee information. To specify a for a grant, use the following:

For example:

modify bus Assembly 123 0 grant stacy access all key Buyer;

Revoking Business Object Access

You can use several approaches to revoke granted access to a business object:

• If you have Revoke access, you can remove all granted access on a business object with:

  mod bus TYPE NAME REVISION revoke all;

  For example:

  mod bus Part Sprocket 3 revoke all;

• You can revoke all accesses granted by a specific grantor with this command:

  mod bus TYPE NAME REVISION revoke grantor USER;

  For example:

  mod bus Part Sprocket 3 revoke grantor Jo;

  The above command removes all grants made by grantor Jo . This command completes successfully if the context user is Jo , or if the context user has Revoke access; otherwise, an error is generated.

• You can revoke all accesses granted to a specific grantee with:

  mod bus TYPE NAME REVISION revoke grantee USER;

  For example:

  mod bus Part Sprocket 3 revoke grantee Jackie;

  This will revoke all grants where Jackie is the grantee. This command executes successfully if the current context is Jackie or if the current context has Revoke access; otherwise, an error is generated.

• You can specify both grantee and grantor to revoke the grant made between them with:

  mod bus TYPE NAME REVISION revoke grantor USER grantee USER;

  For example:

  mod bus Part Sprocket 3 revoke grantor Jo grantee Jackie;

  This will revoke the grant between grantor Jo and grantee Jackie . If the context user is Jo , or if the context user has Revoke access, this command will succeed; otherwise, an error will be generated.

• To revoke the grant without specific grantor/grantee information, you can specify an identifier, or key, defined when the grant was made:

  mod bus TYPE NAME REVISION revoke key KEY;

  In addition, the key is selectable as follows:

  print bus|set TYPE NAME REV select grantkey; 
  expand bus|set TYPE NAME REV select grantkey;

The following example demonstrates the use of keys to grant and revoke access, and includes MQL print bus output on the object:

MQL< >mod bus Assembly 123 0 grant bill access read,checkin,show key Supplier;
MQL< >mod bus Assembly 123 0 grant bill access read,checkin,checkout,show key SupplierEngineer;
MQL< >mod bus Assembly 123 0 grant stacy access all key Buyer;
MQL< >print bus Assembly 123 0 select grant.*;
business object  Assembly 123 0
    grant[creator,bill].grantor = creator
    grant[creator,bill].grantor = creator
    grant[creator,stacy].grantor = creator
    grant[creator,bill].grantee = bill
    grant[creator,bill].grantee = bill
    grant[creator,stacy].grantee = stacy
    grant[creator,bill].granteeaccess = read,checkin,show
    grant[creator,bill].granteeaccess = read,checkin,checkout,show
    grant[creator,stacy].granteeaccess = all
    grant[creator,bill].grantkey = Supplier
    grant[creator,bill].grantkey = SupplierEngineer
    grant[creator,stacy].grantkey = Buyer

Because a unique name (key) has been provided for each grant, the grants can be revoked using this key, rather than relying on the grantor, grantee pair, which might not be -- and in this example is not -- unique. For example:

MQL< >mod bus Assembly 123 0 revoke grant key SupplierEngineer;

This command removes the access granted to Bill as a SupplierEngineer, but it will leave the access granted to Bill as a Supplier. The print command output confirms this:

MQL< >print bus Assembly 123 0 select grant.*;
business object  Assembly 123 0
  grant[creator,bill].grantor = creator
  grant[creator,stacy].grantor = creator
  grant[creator,bill].grantee = bill
  grant[creator,stacy].grantee = stacy
  grant[creator,bill].granteeaccess = read,checkin,show
  grant[creator,stacy].granteeaccess = all
  grant[creator,bill].grantkey = Supplier
  grant[creator,stacy].grantkey = Buyer

Be aware that Revoke access is a very powerful access. By giving a user Revoke access, you are saying that this user can revoke anyone’s grants.

Moving Files

You can move files from one object to another using the modify bus command, provided you have checkout access to the from object and checkin access to the to object. You can also move files to update the file format (moving from one format to another within the same business object). Moving files is equivalent to doing a checkout, deleting the file, and then checking it into a new format or object. However, the files are not actually moved at all (the files stays in the same store - same physical machine location). The command simply changes the metadata so that the files no longer appear to belong to the original object but now belong to the new object or format.

modify businessobject BO_NAME move [format FORMATNAME] from BO_NAME FILE_TO_COPY;

• FILE_TO_COPY is one of:

  format FORMATNAME [format FORMATNAME] file FILENAME{,FILENAME} all

Files are copied (appended) from the object specified in the from clause (the “from object”) to the object being modified (the “to object”). If a format is specified just after the keyword move , the files will be moved to that format. Otherwise, each file will keep its existing format as long as that format is available in the to object. If not, it will use the default format of the to object.

If only a format is given for the from object (part of FILES_TO_COPY), all files of that format are moved. If no format is specified, then the default format is assumed. If any of the specified files is not found with the specified or assumed format, an error is issued and no action is taken.

No triggers are fired when files are moved in this manner. Files in DesignSync stores cannot be manipulated in this manner. The modify bus command with the move keyword will fail when attempted on a Business Object governed by a policy that uses a DesignSync store.

Renaming Files

You can rename a file that is checked into a business object without doing a file checkout and checkin replace. The renaming is done by changing the 'user visible' filename in the metadata. The actual physical file remains hashed in some store and is not touched. Renaming a file in this manner results in significant performance gain.

File renaming does not involve a file copy or file transfer operation. This feature is provided only for MQL. It cannot be used from the thick client or the Studio Customization Toolkit.

The syntax is:

modify bus TYPE NAME REVISION rename [format FORMATNAME][!|not]propagaterename] file FILENAME TOFILENAME 

Renaming Files Inherited in a Revision Sequence

During file rename, the modifier propagaterename controls renaming of files as follows:

• If the propagaterename modifier is used, subsequent revisions inheriting from this file will have the renamed file name.
• If the not propagaterename modifier is used, file rename is effective for the current revision only. Subsequent revisions inheriting from this file will have the old file name.

During file rename, history is added to the business object where the file is checked in:

history = rename file - user: <name>  time: <date-time>  state: <state name> 
format: <format> file: <filename> to file : <filename>

The history indicates file renaming and that metadata operation has been done on a business object. In addition, the history record is a selectable as follows:

print bus T N R select history.newname;
modify bus TNR delete history event newname

File renaming is a simple operation governed by these rules:

• TOFILENAME cannot be empty.
• TOFILENAME cannot be a name that already exists in a business object.
• TOFILENAME cannot contain these special characters: / \ : * ? " < > | @

Modifying Legacy Data

After migrating legacy data from an external or legacy database to Collaboration and Approvals, Business Administrators can modify the following properties of the object to reflect the same data as the external system:

• Current state
• Originated date
• Modified date
• Start, end, and actual dates of all states in the policy.
• Duration values of all states in the policy

For example, a Purchase Order that has been completed in a legacy system should not be set to the initial state of a Purchase Order in Collaboration and Approvals. The imported Purchase Order should immediately be modified to a valid state of the policy to accurately reflect the complete status.

You must be a Business Administrator to make these types of modifications to business objects. These changes can also be made at the time of object creation with the add bus command.

These types of modifications are generally performed by a program, so that other events occurring due to the migration are not reflected in the dates or state set. Since these commands are intended for use within a program object, it is up to the program to handle any errors. An error will result if the context user is not a business administrator, or if the date is not specified in the required formats.

In some cases, you might want the business objects to act as a placeholder, representing the actual objects in the external system that is constantly changing. You can update the business objects on a regular basis by resetting the current state as well as the start, end and duration values of the states. Modifying a business object this way avoids the need for promoting the object through the lifecycle, which would result in each state reflecting the date of the import/promotion and not the date from the legacy system. Each of these (current state, start date, end date, and duration) can be changed independently, with no effect on each other. If you want to maintain these values to be consistent with each other, you must change them all. There is no impact on the lifecycle of these objects if these values are not kept consistent, except for queries or webreports that depend on these values.

When you modify migrated objects in this manner the following do not occur:

• Triggers do not fire
• History records are not added
• Other information associated with a state, like start date, end date, actual date, and duration are not changed

To modify the current state of a business object, use the modify business object command.

modify businessobject BO_NAME [MOD_ITEM {MOD_ITEM}];

• BO_NAME is the business object whose state you are modifying.
• MOD_ITEM is:

  current NEW_STATE_NAME

  state STATE_NAME STATE_ITEM

  • NEW_STATE_NAME is the name of the state you want to show as the current state of the business object
  • STATE_NAME is the name of the state you want to modify with new STATE_ITEMs.
  • STATE_ITEM is a State subclause which provides additional information about the state. The different STATE_ITEM clauses are as follows:

    schedule SCHEDULE_DATE

    actual ACTUAL_DATE

    start START_DATE

    end END_DATE

    duration N

    • SCHEDULE_DATE is the date the object is scheduled for promotion from (or completed) this state.
    • ACTUAL_DATE is date when the object was last promoted/demoted into this state.
    • START_DATE is the date when the object first reached this state.
    • END_DATE is the date when the object last left this state.
    • duration N is the number of days the object was in this state.

For more information, see Organization and Project-Based Access.

Adding or Removing Business Object Ownerships

Business objects can have multiple owners. To add an ownership to or remove an ownership from a business object:

• ORGANIZATION is a "role" object that represents an organization.
• PROJECT is a "role" object that represents a project.
• COMMENT is a short string that is primarily used for annotation.
• ACCESS is a comma-separated list of security tokens.

Each of these fields can be specified when providing an ownership. The first three (ORGANIZATION, PROJECT, and COMMENT) together provide a unique identifier for the ownership entry. Tokens following "for" constitute the ownership comment; those following "as" constitute the access mask.

For the Project, you can assign a role that is defined as a user group (defined using asaprojectgroup as the kind of role). This type of role allows you to assign the user group as the extended ownership, and then allow the management of the user group to add and remove individuals as required. When a user group is specified for a PROJECT, the ORGANIZATION must be specified as '-'.

The following are some examples of usage:

modify bus OBJECTID add ownership "MyCompany" "MyProject" for "ownership”;
modify bus OBJECTID add ownership "Supplier1" "MyProject" for "Project Applicability";
modify bus OBJECTID add ownership "Supplier2" "MyProject" as show,read,checkout;
modify bus OBJECTID remove ownership "Supplier1" "MyProject" for "Project Applicability";

Adding Ownership Inheritance

Several business objects can inherit ownership from a common parent object. To specify ownership inheritance:

The full OWNERSHIP_ID is defined as:

| ORGANIZATION PROJECT [for COMMENT] [as ACCESS]|
| businessobject NAME [for COMMENT]             |
| relationship OBJECT_ID [for COMMENT]          |

Ownership can be selected off of either business objects or relationships. To specify ownership inheritance from a business object:

modify businessobject OBJECTID add ownership bus NAME [for COMMENT];

To specify ownership inheritance from a relationship:

modify businessobject OBJECTID add ownership rel OBJECT_ID [for COMMENT];

The following are some examples of usage:

modify bus T N R add ownership bus Part 1239291 - for "parent workspace';
modify bus T N R add ownership rel 3423.2366.4544.456;
modify bus T N R add ownership bus 3243.34.5365.564 as read;