Revise Business Object

Syntax

revise businessobject OBJECTID [to REVISION] [!file] [SELECT [DUMP] [RECORDSEP] [tcl] [output FILENAME]] [major|minor];

• OBJECTID is the OID or Type Name Revision of the object you want to revise.
• REVISION is the revision designator to be assigned. If a revision is desired, it 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 more information, see Using Select and Related Clauses.

To maintain revision history, the new object should be created with the revised business object command even though it is possible to create what looks like a new revision by manually assigning a revision designator with the Add or Copy Businessobject command. (However, you can add existing objects to a revision chain, if necessary. For more information, see MQL Concepts: About Revision Sequences.)

Not all business objects can be revised. If revisions are allowed, the Policy definition can specify the scheme for labeling revisions. This scheme can include letters, numbers, or enumerated values. Therefore you can have revisions with labels such as AA, 31, or “1st Rev.”

If the REVISION is omitted, a designator is automatically assigned based on the next value in the sequence specified in the object’s policy. If there is no sequence defined, an error message results.

If there is no defined revision sequence or if you decide to skip one or more of a sequence’s designators, you can manually specify the desired designator as the REVISION .

For example, assume you entered the following command:

revise businessobject “Shipping Form” “Lyon’s Order” 5;

Since no revision designator is given, the new business object can be called the following (assuming the revision scheme of 1, 2, 3 ...):

“Shipping Form” “Lyon’s Order” 6

If you want to skip over the next revision number and assign a different number, you can do so as:

revise businessobject “Shipping Form” “Lyon’s Order” 5 to 10;

This command will produce a new business object labeled:

“Shipping Form” “Lyon’s Order” 10

Now the revised business object has a revision designator equal to ten.

You cannot use a designator that has already been used. If you do, an error message will result.

Handling Files

If you want to revise an object without including the original files in the new object, use the following syntax. For more information, see Handling Files (in Copy Business Object).

To add an object to an existing revision sequence, use the Revise Businessobject command:

revise businessobject OBJECTID bus NEWOBJECTID [file]; 

• OBJECTID is the OID or Type Name Revision of the last object in a revision chain.
• NEWOBJECTID is the OID or Type Name Revision of an existing object that is not already part of any revision sequence.
• The optional file keyword applies only if the new object has no files checked in, in which case it specifies whether files should or should not be inherited from the revision sequence to which it is being added. The default is !file, so no files are inherited. This flag is ignored if NEWOBJECTID contains files.

Creating Major and Minor Revisions

Using the major or minor keyword with the Revise command specifies whether to create a new major revision or a new minor revision, respectively. A major revision is a family of minor revisions that share the same majorid value. Creating a new major revision also starts a new minor revision family.

revise bus T N R [major|minor] ... ;

If neither the major nor minor keyword is specified, a new minor revision is created and existing revisions become minor revisions. Revise Major/Minor commands affect several basic business object properties, as shown in the following table.

If an object policy does not have a minor revision sequence defined, then Revise Minor produces an error. If an object policy does not have a major revision sequence defined, then Revise Major produces an error. If an object policy has both major and minor revision sequences defined, the majorrevision and minorrevision strings are calculated as in the table above, and the two strings are joined with the delimiter defined in the policy and stored in the existing revision field. For more information, see Majorsequence and Minorsequence Clauses for the Add Policy Command.

Storage of major/minor in the existing revision field allows the Type-Name-Revision combination to continue to be the default uniqueness criteria without requiring an update to the out-of-the-box table that governs TNR uniqueness. It also allows all commands that reference objects by TNR criteria to continue to work as before. For objects that have both major and minor revision strings, the revision field is of the form major-minor, where the dash represents the delimiter specified in the policy.

Changing policy on a business object is allowed as long as the new policy does not change a delimiter or add/remove either a major or minor sequence to/from the existing policy. Legacy policies with no sequences defined are considered to have a minorsequence, which is empty, and no majorsequence.

Major and minor revisioning has these effects on selectables:

• Existing selectables (revision, revisions, first, last, next, and previous) continue to work for existing revision sequences as before, until the policy is modified to define major and minor revision sequences.
• Parallel minor-revision-related selectables (minorrevision, minorrevisions, firstminor, lastminor, nextminor, previousminor) continue to support existing functionality even in the presence of mixed major/minor revisions.
• Parallel major-revision-related selectables (majorrevision, majorrevisions, firstmajor, lastmajor, nextmajor, previousmajor) were added to support major revisions. The lastmajor (and several other selectables) are subselects of either 'majorid' or 'majorids'.
  • majorid provides the subselect values for only the major revision the object is part of.
  • majorids provides the subselect values for all of the related major revisions.
• Additional business object selectables (ispublished, lastpublished, isbestsofar, bestsofar) report the published and best-so-far (BSF) status of business objects.

The majorid and majorids selectables support these subselects that can be applied to each minor revision family:

For example, you can create these objects:

1. Create a policy and business object:

   add policy minmaj minorsequence 1,2,3,... majorsequence A,B,C,... delimiter . type t2 state one published;
   add bus t2 mm1 A.1 policy minmaj vault unit1;

2. Create revision B.1:

   revise bus t2 mm1 A.1 major;

3. Create revision A.2:

   revise bus t2 mm1 A.1 minor;

Now, you can use these subselect commands to get the shown results:

MQL<131>print bus t2 mm1 A.1 select majorid.*;
business object  t2 mm1 A.1
    majorid.id = 42DBCF62000052A857F502D6000001B5
    majorid.lastpublished = t2 mm1 A.2
    majorid.bestsofar = t2 mm1 A.2
    majorid.majorrevision = A
    majorid.majororder = 0
    majorid.minorrevisions = A.1
    majorid.minorrevisions = A.2
    majorid.previousmajorid =
    majorid.nextmajorid = 42DBCF62000052A857F502FB000001C2
    majorid.firstmajorid = 42DBCF62000052A857F502D6000001B5
    majorid.lastmajorid = 42DBCF62000052A857F502FB000001C2
    majorid.modified = Wed Oct 5, 2016 9:41:20 AM EDT

MQL<133>print bus t2 mm1 A.1 select majorids.*;
business object  t2 mm1 A.1
    majorids[42DBCF62000052A857F502D6000001B5].id = 42DBCF62000052A857F502D6000001B5
    majorids[42DBCF62000052A857F502FB000001C2].id = 42DBCF62000052A857F502FB000001C2
    majorids[42DBCF62000052A857F502D6000001B5].lastpublished = t2 mm1 A.2
    majorids[42DBCF62000052A857F502FB000001C2].lastpublished = t2 mm1 B.1
    majorids[42DBCF62000052A857F502D6000001B5].bestsofar = t2 mm1 A.2
    majorids[42DBCF62000052A857F502FB000001C2].bestsofar = t2 mm1 B.1
    majorids[42DBCF62000052A857F502D6000001B5].majorrevision = A
    majorids[42DBCF62000052A857F502FB000001C2].majorrevision = B
    majorids[42DBCF62000052A857F502D6000001B5].majororder = 0
    majorids[42DBCF62000052A857F502FB000001C2].majororder = 1
    majorids[42DBCF62000052A857F502D6000001B5].minorrevisions = A.1
    majorids[42DBCF62000052A857F502D6000001B5].minorrevisions = A.2
    majorids[42DBCF62000052A857F502FB000001C2].minorrevisions = B.1
    majorids[42DBCF62000052A857F502D6000001B5].previousmajorid =
    majorids[42DBCF62000052A857F502FB000001C2].previousmajorid = 42DBCF62000052A857F502D6000001B5
    majorids[42DBCF62000052A857F502D6000001B5].nextmajorid = 42DBCF62000052A857F502FB000001C2
    majorids[42DBCF62000052A857F502FB000001C2].nextmajorid =
    majorids[42DBCF62000052A857F502D6000001B5].firstmajorid = 42DBCF62000052A857F502D6000001B5
    majorids[42DBCF62000052A857F502FB000001C2].firstmajorid = 42DBCF62000052A857F502D6000001B5
    majorids[42DBCF62000052A857F502D6000001B5].lastmajorid = 42DBCF62000052A857F502FB000001C2
    majorids[42DBCF62000052A857F502FB000001C2].lastmajorid = 42DBCF62000052A857F502FB000001C2
    majorids[42DBCF62000052A857F502D6000001B5].modified = Wed Oct 5, 2016 9:41:20 AM EDT
    majorids[42DBCF62000052A857F502FB000001C2].modified = Wed Oct 5, 2016 9:41:15 AM EDT

Another example for revision A.1:

MQL<134>print bus t2 mm1 A.1 select majorid previous next previousminor nextminor majorid.previousmajorid majorid.nextmajorid;
business object  t2 mm1 A.1
    majorid = 42DBCF6200005CBC57FB8F420000000B
    previous =  
    next = A.2  
    previousminor =  
    nextminor = A.2  
    majorid.previousmajorid =  
    majorid.nextmajorid = 42DBCF6200005CBC57FB8F4E00000021

In these results:

• The majorid.id is the majorid value for family A, meaning that all minor revisions share this value for majorid.
• No values shows for previous or previousminor because this is the first minor revision, so there is no previous revision.
• No value shows for majorid.previousmajorid because this is the first major revision.
• The value for majorid.nextmajorid is the majorid for family B, the next major revision.

The same command issued for revision A.2 shows these results:

business object  t2 mm1 A.2
    majorid = 42DBCF6200005CBC57FB8F420000000B
    previous = A.1  
    next =  
    previousminor = A.1  
    nextminor =  
    majorid.previousmajorid =  
    majorid.nextmajorid = 42DBCF6200005CBC57FB8F4E00000021

In these results:

• The majorid.id shows the same majorid as revision A.1
• No values shows for next or nextminor because this is the last minor revision, so there is no next revision.
• majorid.previousmajorid and majorid.nextmajorid are the same as A.1 because the revisions belong to the same major family.

The same command issued for revision B1 shows these results:

business object  t2 mm1 B.1
    majorid = 42DBCF6200005CBC57FB8F4E00000021
    previous = A.1 
    next =
    previousminor = 
    nextminor = 
    majorid.previousmajorid = 42DBCF6200005CBC57FB8F420000000B 
    majorid.nextmajorid =

In these results:

• The majorid.id is for family B, a different value than the one for family A.
• The previous value indicates that this revision was created from the shown revision (A.1).
• No values shows for next or nextminor because this is the last minor revision in family B.
• No value shows for majorid.previousmajorid because this is the first major revision.
• The value for majorid.previousmajorid is the majorid for family A, the previous major revision.
• No value shows for majorid.nextmajorid because this is the last major revision.

The previous/next functionality in use before major/minor revisions were introduced is preserved for revision sequences that are ONLY minor (default) or ONLY major (migrated VPLM), since the sequences are strictly linear in both cases. For revision sequences that use major/minor, the previous pointer for any object created by revise major OR revise minor points to the object from which it was created. The set next pointer is set for the revise minor command, and NOT for the revise major command.

In summary, for families built with BOTH major/minor revisions:

• The previous pointer is equivalent to ‘revised from’. Within a minor sequence this is still linear, but the first minor object could have a previous pointer to a revision in an earlier family to indicate the ‘created from’ revision.
• Next pointers are only updated by revise minor commands, so there will be only one that points to the next object in the same minor revision family (or NULL).
• When deleting an object (such as B), if it has a previous object A, the next pointer of object A is reset to the next pointer of B. If B has a next object C, C’s previous pointer is reset to the previous of B. This maintains the meaning of previous/next.