Add Business Object

Syntax

add businessobject BO_NAME policy POLICY_NAME [ITEM {ITEM}] [SELECT [DUMP] [RECORDSEP] [tcl] [output FILENAME]];

• BO_NAME is the Type Name Revision of the business object. When defining the Name, you cannot use any of these characters:

  Character Name	Character
  Backslash	\
  Star (asterisk)	*
  Dollar sign	$
  Question mark	?
  Double quote	"
  Single quote	'
  Comma	,
  Semicolon	;
  Linefeed	\n
  Carriage return	\r

  If the business object is a role, the period is also a forbidden character.

• ITEM is an Add Businessobject clause:

  description VALUE

  image FILENAME

  vault VAULT_NAME

  name NAME [revision REVISION]

  owner USER_NAME

  organization USER_NAME

  project USER_NAME

  policy POLICY_NAME

  state STATE_NAME | schedule DATE | | actual DATE | | start DATE | | end DATE | | duration N |

  originated DATE

  modified DATE

  current STATE_NAME

  ATTRIBUTE_NAME VALUE

  physicalid UUID

  logicalid UUID

  versionid UUID majorid UUID

  majororder VALUE

  minororder VALUE

  interface INTERFACE_NAME

  access ACCESSID_ID [as MASK]

  ownership OWNERSHIP_ID [as MASK]

  composer BO_NAME

  relcomposer CONNECTION

  composition RELTYPE

Adding Legacy Data

If you are adding legacy data from external systems into the database, three clauses are provided to migrate and synchronize the data.

The Current clause of the Add Businessobject is used to create business objects that are already beyond the first state of their policies. The Originated clause of the Add Businessobject command is used to maintain origination dates from the legacy system. Lastly, the Modified clause of the Add Businessobject command is used to maintain modification dates from the legacy system.

If you are migrating legacy data without these clauses, see Modifying Legacy Data.

Policy Clause

This clause assigns a policy to the business object. A policy controls a business object. It specifies the rules that govern access, approvals, lifecycle, versioning and revisioning capabilities, and more. If there is any question as to what you can do with a business object, it is most likely answered by looking at the object’s policy. Specifically, a policy defines the following information:

• The types of objects the policy will govern.
• The types of formats that are allowed for file checkin and the default format.
• Where and how checked-in files are managed.
• How revisions will be labeled.
• The number and order of each object state.
• The restrictions, if any, associated with each object state.

Since this information is required for a business object to be usable, a Policy clause must be included in the business object definition. If you are unsure about the policy, you should examine the policy definition with the Print Policy command (for more information, see MQL Concepts: Policies).

The policy specified must be defined to govern the type of business object being created.

If the policy name you give in this clause is not found, an error message results. If that occurs, use the List Policy command to check for the existence and spelling of the policy name.

For example, the following object definition assigns the “Software Development” policy to a business object titled “Graphics Display Routine:”

add businessobject Routine “Graphics Display Routine” 1
   policy “Software Development”;
   description “Routine for displaying information on a color monitor”

After this command is processed, the business object will be created and the “Software Development” policy will control who can access the object and the object’s lifecycle states.

Image Clause

This clause associates a special image, called an ImageIcon, with a business object. While it is optional, it can assist a user in locating a desired object. For example, you could have several different components, blueprints, or designs within a vault. By having an ImageIcon of each item associated with its object name, a user can easily locate the object s/he desires by using the associated ImageIcon as a guide.

While ImageIcons are very similar to icons, they require more display time and probably should be displayed only at specific times. Also, while an icon is associated with items such as policies, types, and formats, ImageIcons are associated only with objects and persons. An object might or might not have an ImageIcon associated with it. Excluding an ImageIcon from this object will not affect other objects that are created with the same type, policy, state, and owner. You can even have two revisions of an object with different ImageIcons since each revision represents a different object.

The GIF file needs to be accessible only during definition using the Add or Modify Businessobject command. Once an accessible file in the correct image type is used in the Businessobject command, 3DSpace will read the image and store it with the object definition in the database. Therefore, the physical icon files do not have to be accessible for every session. (If the file is not accessible during definition, 3DSpace will be unable to display the image.)

To write an Image clause, you need the full directory path to the ImageIcon you are assigning. For example, the following command assigns an ImageIcon of the actual vehicle to the business object:

add businessobject “Energy Efficient Vehicle” “Solar Vehicle X29” A
   policy “Solar Vehicle”
   description “Uses traditional batteries”
   image $MATRIXHOME/demo/vehicleX29.gif;

Specifying redundant icons adds redundant information in the database that requires more work to display. When the default icon is desired, do not specify it.

The Image clause of the Add Businessobject command is optional unless there is a need to distinguish between objects of the same type. If you do not specify an image, the default icon of the type is used.

If you associate an image with a business object using the Image clause, you can retrieve the image as a GIF file using the Image command. The GIF file is placed in the ENOVIA_INSTALL directory, unless overridden by the optional clause, directory.

• OBJECTID is the OID or Type Name Revision of the business object instance from which you want to get the image.
• DIRNAME is the full pathname where you want to save the image file. If no pathname is specified, the file is saved in the $MATRIXHOME directory.
• FILENAME is the name to be given to the image .gif file. If the file name is not specified, the file is given the name of the object with a .gif extension.
• verbose prints the file name on the screen.

For example:

This command retrieves the image of object Assembly 12345 0 and saves it to the $MATRIXHOME directory with the name 12345.gif.

Vault Clause

This clause specifies the name of the vault where the object will reside. If you include a Vault clause in your definition, it must be placed after the Policy clause and before any other Add Businessobject clauses.

3DSpace must know which vault is associated with the business object. This element is optional because if not explicitly stated. The current vault (as set in the current context) is a default value. If the object you are creating should not be in the current vault, you must include the vault’s name in the object’s definition.

For example, assume you are in a vault named “Car Loans.” You decide to create an object with the specification “Car Loan” “Alan Broder.” You could do this by entering the following command:

add businessobject “Car Loan” “Alan Broder” A
   policy “Bank Loans”;

Since a vault is not specified, the current vault, “Car Loans,” is used to store the business object named “Alan Broder.” But what if Mr. Broder also had a mortgage with the same company and you were in the “Mortgages” vault instead of the “Car Loans” vault? You would have to include a Vault clause:

add businessobject “Car Loan” “Alan Broder” A
   policy “Bank Loans”
   vault “Car Loans”;

In many ways, vaults resemble and operate like directories on computers. Your context is similar to your default directory. If the object (like a file) is not in the default directory, you must include the directory as part of the object name.

Owner, Organization, and Project Clauses

In addition to the primary owner, you can define up to two additional owners for a business object or connection: organization and/or project. This ownership might be important for applications that use access models based on projects and organizations. You must have ChangeOwner privileges to set these owners. In 3DEXPERIENCE, a collaborative space is a project.

Unlike the primary owner for whom special privileges can be set in a policy (using “owner”), no privileges are set for the additional owners, except by virtue of their user name (that is, policies do not support the notion of generic ORGANIZATION or PROJECT access on every object governed by the policy).

If you do not specify credentials, the following credentials are set for you:

• For create and clone, project and organization are set from the log in credentials.
• For revise, project and organization are set from the previous revision.

You can also use altowner1 and altowner2 to assign alternate owners. An alternate owner can be a person, group, role, or an association. In the following example, the business object is created and altowner1 is set as a role.

State Clause

The lifecycle of a business object is assigned as part of the policy and consists of a series of object states. A state identifies a stage in the lifecycle of an object. Depending on the type of object involved, the lifecycle might contain only one state or many states. The states control the actual object instances and specify what can be done with an object after it is created. Each state defines who will have access to the object in that state, what type of access is allowed, whether or not the object can be revised, whether or not files within the object can be revised, and the conditions required for changing state.

This clause is optional and can be used to specify the scheduled target date for this object in a particular state . It is not necessary to assign a date for any particular state. There might be situations where the change from one state to another might occur at any time. For example, if automobile insurance is contained within an object, the object might change when an accident occurs. Since accidents are not usually planned, no schedule date can be assigned. If, however, you have a state for policy renewal, the date can be scheduled since you know when the policy renewal is due.

This is a target date only. The object will not automatically enter that state on the given date. The object can only be promoted after all required conditions are met—this date will not influence those conditions. The date is intended for informational purposes only.

Actual dates are saved for each state in an object’s its lifecycle — and are the dates the object is promoted to that state. These dates are generally system-generated, but can be adjusted with this command for data migration purposes, for cases where the data being imported is from an external source that supports the concept of states with associated actual dates. Since the command is 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 with Schedule access to the object, or if the date is not specified in the required formats.

When specifying the name of the state to which you want to assign a date, you must make sure it is a valid name. If the state name given in the State clause is not found in the policy you are assigning to the object, an error message will result. If that occurs, use the Print Policy command to check for the existence and spelling of the state name.

When specifying the date within a State clause, you must use the date/time formats defined in your initialization file. If nothing is set there, the defaults are used. See Collaboration and Approvals Administration Guide: About Date Formats.

For example, the following object definition will schedule the object to be in the “Re-evaluation and Renewal” state on June 30, 2002.

add businessobject “Homeowner’s Insurance” “Hebron Family” B
   policy “Primary Homeowners”
   description “Homeowner’s Insurance for Hebron’s Primary Residence”
   state “Re-evaluation and Renewal” schedule “June 30, 2002”;

In this example, you want to remind the agent of when the homeowner’s insurance policy should be renewed. By inserting this date, an agent might promote the object to the “Re-evaluation and Renewal” state even if the date is June 26 (since it is close enough to the target date of June 30th.)

Originated Clause

When migrating legacy data, you likely want to maintain the originated date from the legacy system. This clause allows you to assign an originated date. Without this clause, the originated date for objects is the date read from the system.

For example:

add businessobject “Document” “Manual” 0 originated 2/2/02;

You must specify the date using the date/time formats specified in your initialization file. If nothing is set there, the defaults are used. See the Collaboration and Approvals Administration Guide: About Date Formats.

The actual creation date and time are logged in the create history record of the object. It is also returned with the originated selectable.

The originated date can only be changed with the Modify Businessobject Originated command.

Modified Clause

When migrating legacy data, you likely want to maintain the modified date from the legacy system. This clause allows you to assign a modification date. Without this clause, the modified date is the same as the creation date.

For example:

add businessobject “Document” “Manual” 0 modified 3/2/02;

You must specify the date using the date/time formats specified in your initialization file. If nothing is set there, the defaults are used. See the Collaboration and Approvals Administration Guide: About Date Formats.

The modification date specified is returned with the modified selectable.

Unlike the date specified with the originated clause, the modified date will change as normal if modifications are made after object creation.

Current Clause

When migrating legacy data, you are likely to want to create business objects that are already beyond the first state of their policies. For example, you might want to add Parts that are already released. The Current clause of the Add Businessobject command allows you to create an object in any state of its governing policy. Without this clause, users create business objects in the first state of their governing policies.

Since the Current clause identifies the state of the policy for the business object, it must be specified after the Policy clause.

For example:

add businessobject “Document” “Book” A policy
 “Documentation” current “Approved”;

If the state “Approved” is not specified in the policy “Documentation”, an error message results.

Promote triggers associated with the state specified do not fire since the object is created in and not promoted to the current state. The create trigger fires as usual.

Attribute Clause

This clause allows you to assign a specific value to one of the object’s attributes. As stated earlier, you must assign a type to any object being created. An object’s type might or might not have attributes associated with it. If it does, you can assign a specific value to the attribute using the Attribute clause.

If you are unsure of either of the ATTRIBUTE_NAME or the VALUE to be assigned, you can use the Print Type and Print Attribute commands, respectively.

For example, assume you are defining an object of type “Shipping Form” using the following Add Businessobject command:

Only the attributes associated with an object’s type can be assigned values for the instance.

If you were to examine the definition for the type “Shipping Form,” you might find it has three attributes associated with it called “Label Type,” “Date Shipped,” and “Destination Type.” When this type is assigned to the object called “Lyon’s Order,” these attributes are automatically associated with the object. It is up to you as the user to assign values to the attributes.

If you do not assign values, they remain blank or the default is used if there is one. To assign values, you can insert an Attribute clause into the object definition.

When you are specifying an attribute value, be sure the value is in agreement with the attribute definition. In other words, only integer values are assigned to integer attributes, character string values are assigned to character string attributes, and so on. Also, if the attribute has a range of valid values, the value you give must be within that range.

You can use the Print Attribute command to examine an attribute’s definition. For example, assume you are unsure of the definition of “Label Type.” If you examine the attribute definition, you might see that it is a character string value with no predefined range. With this knowledge, you can insert an Attribute clause to define a value similar to the following:

String attributes (as well as description fields) have a limit of 4,194,304 (4*1024*1024). If you expect to handle more data in an attribute, consider re-designing the schema to store the data in a checked-in file instead or use a binary attribute.

If you want to assign values to each of the three attributes, you can write the object definition as:

add businessobject “Shipping Form” “Lyon’s Order” A
   policy “Shipping”
   description “Shipping Form for the Lyon’s Order”
   “Label Type” “Overnight Express”
   “Date Shipped” 12/22/1999
   “Destination Type” “Continental U.S.”;

With this definition, each attribute associated with the type “Shipping Form” will have a specific value and those values can be viewed whenever the “Lyon’s Order” object is accessed.

Physical ID and Logical ID Clauses

Physical and logical IDs are required for Product Structure Design app. A physical ID is a global identifier that is unique to each business object or relationship. A logical ID is a global identifier shared by all members of a minor revision family.

These clauses are available only if your database has been upgraded to use physical and logical IDs. For details on upgrading to use these IDs, see the Installation Guide: Upgrade Command.