Managing Business Objects

The Business Object Manager view provides functionality to manage Business Objects. It allows to:

For details on Business Objects used in Stardust, please refer to chapter Business Objects Business Objects in the Stardust Concepts Documentation - Concepts section.

Opening the Business Object Manager View

To open the Business Object Manager view, select Business Object Management in the Business Object Management section of the Control Center perspectives launch panel.

Select Business Object
Figure: Select Business Object

For details on defining structured data as Business Object, please refer to chapter Specifying Structured Data as Business Object in the Business Process Modeling Handbook.

Selecting Business Objects

In case Business Objects do exist in deployed models, a drop-down list is provided to select a Business Object from.

The Business Object name is preceded by the model name.

Select Business Object
Figure: Select Business Object

In case no model that has a Business Object is deployed, the following infobar is displayed:

No Business Objects
Figure: Message if no Business Objects are available

Business Object Instances Table

Once a Business Object is selected, a table with existing instances of this Business Object is displayed. The displayed instances in this table are filtered based on the user's permissions, which are controlled by Authorization settings on the Structured Data. Please refer to chapters Setting Authorization in Model Element Properties and Specifying Structured Data as Business Object for details.

Table with instances of the selected Business Object
Figure: Table with instances of the selected Business Object

Visibility Restrictions of Business Object Instances depending on Department Grants

The visibility of Business Object instances also depends on department grants. For details please refer to section Visibility Restrictions of Business Object Instances depending on Department Grants of chapter Business Objects Visibility Restrictions of Business Object Instances depending on Department Grants of chapter Business Objects in the Stardust Concepts. Documentation - Concepts.

Examples

Consider two Business Objects, Fund and Fund Group that are related to each other. Both have the option Propagate Access enabled.

Related Business Objects
Figure: Related Business Objects

The visibility of the Business Objects is based on scoped and unscoped roles.

Example - Unscoped participant with permission on Business Object Fund

Assume a user Hans Nase, who is associated with an unscoped role Checker.

Participants
Figure: Participant settings

Participant Checker has permission only on Business Object Fund. He has no permission on Business Object Fund Group.

Fund Permission
Figure: Business Object Fund Permissions

Several instances of Business Object Fund and Business Object instance Fund Group have already been created by other users. A relationship from a Fund instance with FundID 100 was created to FundGroup instances with FundGroupID 123 and FundGroupID 815.

Related Business Object
Figure: Related Business Object

In the Business Object Management view, user Hans Nase selects Business Object Fund. All Business Object Instances of Business Object Fund are displayed in the table.

Visible Funds
Figure: Visible Funds

Selecting Business Object FundGroup, he can see FundGroup instances with FundGroupID 123 and 815. These instances are related to Business Object instance Fund 100.

Related FundGroup Business Object instance
Figure: Visible related FundGroup Business Object instance

The access is propagated from Business Object Fund, where he has permission on to the related Business Object FundGroup.

Note that in case Business Object Fund had the option Propagate Access disabled for the relationship to Business Object Fund Group, the unscoped user would not see any instances of Fund Group.

Example - Scoped participant with permission on Business Object Fund

A scoped organization Fund Accountants is selected for automatic department creation for Business Object Fund.

Automatic department creation
Figure: Automatic department creation

Organization Fund Accountants has permission only on Business Object Fund. It has no permission on Business Object Fund Group.

Fund Permission
Figure: Business Object Fund Permissions

Assume a user Frank Cityman, who is associated with two scoped organizations Fund 100 and Fund 200, which were added via automatic department creation during creation of the Business Object instances Fund 100 and Fund 200.

Association with Fund
Figure: User associated with scoped Fund

In the Business Object Management view, he selects Business Object Fund. Only Business Object instances Fund 100 and Fund 200 are displayed, where scoped user Frank Cityman is associated to via department grant.

Visible Funds
Figure: Visible Funds for scoped user

Selecting Business Object FundGroup, he can see FundGroup instances with FundGroupID 123 and 815, as these are related to Business Object instance Fund 100, where he has permission on.

Related FundGroup Business Object instance
Figure: Visible related FundGroup Business Object instance

Note that in case Business Object Fund had the option Propagate Access disabled for the relationship to Business Object Fund Group, the scoped user would not see any instances of Fund Group.

Once a Business Object is selected in the drop-down list, the view updates with the search options for that Business Object.

Business Object Fields
Figure: Fields populated for selected Business Object

The search fields are the Business Object's top-level, primitive, single cardinality fields that are indexed.

Start a search by typing a value in a field and tabbing out. To search for all, simply tab out of a field. Note that the search is case-insensitive. A search is directly initiated on tab out and the Search Results will populate.

To initiate more specific searches, type values in additional data fields. The search interpretes the fields in AND conditions.

Note
Some XSD types are not supported for a Business Object Search. Please refer to section Known Restriction for using the Business Object Management in the Stardust Troubleshooting chapter for an overview on these types.

Search Toolbar Options

The Business Object Search toolbar provides options to:

Viewing Business Object Search Results

You find the results of the Business Object Search presented in a table underneath the search fields.

Search Results
Figure: Table with search results

Each row in the table is an instance of the Business Object, and may or may not be associated with a Process Instance.

The table provides controls for:

Select a row in the table to initiate a Process Search for the selected Business Object Instance. The latest version of the Data object will be populated in the Data section.

Selected Data Object displayed in Data section
Figure: Selected Data Object displayed in Data section

Viewing Business Object Process Instance Search Results

The search results of a Process Instance Search are presented in a table within the PROCESS INSTANCES USING <BUSINESS OBJECT LABEL> section.

The table supports the following functionality:

Search Results
Figure: Business Object Process Instance Search Result

Selecting a row updates the view to display all fields/values in that version of the Business Object Instance.

Viewing and Updating Business Object Instances

Selecting a Business Object Instance updates the view to display the following:

All fields in the Business Object Instance are displayed, including those not indexed. If you have the permission to read and modify data values of the Business Object, you can modify the fields inline and persist the changes by clicking Save.

Search Results
Figure: Business Object Data in Process Instance Search Result

To update the changes for the Business Object Instance, click the Save button.

Note
Only administrators have the authorization to update existing Business Object Instances.

Note that you can also modify the Primary Key. When you modify a Primary Key, the system checks whether there is another Business Object Instance with the same Primary Key as the new Primary Key value. If it exists, an error message is displayed. Otherwise a new Business Object Instance with the new Primary Key is created and the Business Object Instance with the old Primary Key is deleted.

References to Other Business Objects

References of the selected Business Object instance to Other Business Objects instances appear as links under the RELATED OBJECTS heading.

Search Results
Figure: Related Objects

The number of referenced instances is displayed in parenthesis in each link.

For details on Business Object relationships, please refer to chapter Specifying Structured Data as Business Object in the Business Process Modeling Handbook.

Opening the Related Objects dialog

To view the referenced Business Object Instances, click a reference link. The Related Objects dialog opens, which supports viewing and removing existing references as well as adding new references.

Referenced Business Objects Instances
Figure: Referenced Business Objects Instances

The top table displays Business Object Instances related to the in-scope Business Object instance.

Business Object Instance search results are displayed in a table below. The search results are filtered based on the user's permissions and department grants for the related Business Object as described above for the general Business Object instances table.

Deleting a new referenced Business Object Instance

To remove a referenced Business Object Instance, click a table entry row to select it and click Delete.

Delete referenced Business Object
Figure: Delete referenced Business Object

Click Save to persist the changes and close the dialog. In case you like to discard the changes, close the dialog with Cancel.

Adding a new referenced Business Object Instance

To add a new referenced Business Object Instance:

  1. Enter values in the top fields and tab out to initiate a search. To search all, leave the fields blank.
  2. Select the Business Object Instance that you want to add. In case multiple instances are supported for the instance, you can use Ctrl-Select to select multiple instances to be added. Multiple instances are supported in case the referenced object field has a cardinality of zero or more or one or more.
  3. Click Add. The selected instance(s) will be added to the top table.

    Add a referenced Business Object

  4. Click Save to persist the changes and close the dialog, or Cancel to close the dialog without saving.
  5. If no multiple instances are supported and you try to add an instance to a non-empty table, an error message is displayed and the instance is not added.

Note

Creating Business Object Instances

Business Object Instances may be created as part of processing Process Instances that use Business Objects or added manually in the Business Object Manager View. These instances will not be bound to any Process Instance. Note that you require the permission to read and modify data values for the Business Object data if you like to add a Business Object Instance.

To add a Business Object Instance in the Business Object Manager View:

  1. Select a Business Object from the adjacent drop-down list. The Business Object name is preceded by the model name.

  2. Click the Create icon in the toolbar

  3. The search field collapses and all of the fields in the selected Business Object populate in the area underneath the top select boxes.

    Values can be entered in the fields. To add the configured Business Object Instance, click the Save button.

    Save the Data
    Figure: Save the Data

  4. In case a Business Object with the entered primary key already exists, a warning message is displayed.

    ValidationWarning

    In case you like to change the existing Business Object with this primary key for the new values entered in the other fields, click Save again nevertheless.

  5. In case you have no permission to add an instance of this Business Object data, an error message is displayed accordingly.

    Validation Error

Note
New Instances of the referenced/related Business Objects cannot be added.

Exporting Business Object Instances

Click the Export icon Export CSV in case you like to export a Business Object instance as CSV file.

Export CSV
Figure: Exporting Business Object Data as CSV

The structure of the exported CSV file looks like in the following example:

Exported CSV
Figure: Exported CSV file

Note that only items that are present on the current page are exported. In case you like to export all pages, select the Export icon in the toolbar.

Select Export All Pages | All Fields to export all pages with all fields.

Export CSV option
Figure: Export CSV option

Option Export Current Page | All Fields is equivalent to the general Export option.

Importing Business Object Instances

In case you have the permission to modify data values of the currently selected Business Object, you may import Business Object Instances from a CSV file. Click the Import Import icon in the toolbar to import data from a CSV file.

The CSV import dialog opens, where you can browse to the CSV file.

Note that the CSV file needs to contain the following:

Import CSV
Figure: Importing Business Object Data as CSV

Relationships of imported Business Object Instances will be maintained.

In case the import is successful, a message dialog appears notifying the number of records that were uploaded.

Successful Import Message
Figure: Import Success Message

Example Import

In this example, we import an Excel table for a Business Object of the following data structure:

BO Structure
Figure Business Object Data Structure

In an Excel table we enter records for this Business Object. The first row (header row) contains the IDs of the top level fields, TaxId, FirstName, LastName. The next rows contain values for these top level fields.

Excel file with records
Figure: Excel file with records

After a successful import, the records are added and displayed in the Business Objects table:

Resulting imported table
Figure: Resulting imported table

Merging imported Fields

You can select if you like to merge the imported fields with already existing records. With this option selected, the import functionality performs a merge in the following way:

Simple Business Object merge import example

In this example, we merge a CSV file with Business Object instance values into existing fields of Business Object instances.

We have two Business Object instances with the following entries:

Business Object Instances
Figure: Original Business Object Instances

Our CSV file contains the following fields with the same IDs, but different field values for Name and FundGroup.

CSV entries
Figure: CSV entries

To import the CSV records with merge option, we do the following:

  1. Click the Import Import icon
  2. Browse to the CSV file
  3. Select the merge option
  4. Click Import

Importing the CSV file
Figure: Importing the CSV file

An alert opens to notify us about the successful upload of 2 records. In the table we can see that the existing record fields have been merged and updated with the entries from the CSV file.

Updated records
Figure: Updated records

Example - Importing a Business Object with relationships

In this example, we have two related Business Objects, Vendor and Product.


Figure: Business Objects with relationship

Assume we have two instances of Business Object Vendor:


Figure: Example instances of Business Object Vendor

Business Object Product has two instances with values 815 and 333 for ProductId. Both instances have a relationship to instance of Business Object Vendor with VendorId 4711.

Instances of Business Object Product
Figure: Instances of Business Object Product

Now we import a CSV file for Business Object Vendor containing the existing VendorId fields, but with different VendorName field entries.

CSV File
Figure: CSV File for Vendor Object

Select the merge option in the Import dialog.

Import dialog
Figure: Import dialog

A dialog opens to confirm that 2 records have been successfully imported.

Alert
Figure: Notification for successful import

In the Business Object instances table you can see that the values in the VendorName fields have been replaced with the according fields of the CSV file.

Alert
Figure:

If you select instance with VendorId 4711, you see that its relationships to instances of Business Object Product with Ids 815 and 333 have been kept during the merged import.

Relationships
Figure: Relationships to Product instances

Import Failure

If the import fails an according error message is displayed. There are several reasons for an upload failure:

Partial Import

In some cases, only a part of the records are incorrect, e.g. only one or not all given primary keys do already exist. In these cases a partial import is performed until the incorrect record row is reached. Until that row is reached, all correct records will be uploaded and the following records will be ignored. An according error message is displayed notifying about the partial upload and the number of uploaded records.

Partial Import Message
Figure: Partial Import Message

Deleting Business Object Instances

If you have the permission to modify data values, you can delete a Business Object instance via the Business Object Manager view. To delete a Business Object Instance:

  1. Select a Business Object Instance from the Search Results. Note that currently only one instance can be selected.
  2. Click the Delete button

    Delete Business Object Instance

  3. A confirmation dialog opens to confirm the deletion

    Confirmation Dialog

  4. Click OK to delete the selected Business Object Instance or Cancel to close the dialog without deleting.

Note that deleting business objects is cleaning up all references to the deleted object based on the defined relationships.