Create and Edit Business Objects

You use custom business objects to store data that is not provided by an external service. As you develop your applications, you can create business objects and edit the business object fields to meet your needs.

Create a Business Object

You use custom business objects to store data that is not provided by an external service. The data in your custom business objects is stored in the database that was provisioned for your service instance.

When you create custom business objects, you specify each of the fields that your application needs. As you develop your application, you can modify your business objects to add and modify fields as needed. Your custom business object will be exposed as a a set of endpoints that provide REST APIs for operations that you can call from page components.

To create a business object:

  1. Open the Business Objects tab.
    The Business Objects pane opens. By default, the Objects tab is selected.
  2. Click the + sign (Business Object).
  3. In the New Business Object dialog box, enter the Label for the business object and click Create.

When you click Create, an artifact window for the new business object opens in the main window and displays the Overview tab. The window contains additional tabs for viewing and editing the various attributes of the business object: Fields, Security, Business Rules, Endpoints, and Data.

You can see the endpoints for the business object that are created by default in the Endpoints tab.

You can also create business objects using the Diagrammer.

To delete a business object, right-click the business object and select Delete.

View, Create, and Edit Business Object Relationships

The Relationships area of the Overview tab for a business object displays the relationships between that business object and other business objects in your application.

When you create a reference to another business object, the relationship between the current business object and the one being referenced is, by default, many-to-one. For example, when you create a reference from an Employee business object to a Department business object, an Employee can belong to only one Department, but a Department normally has many employees. When you first create such a relationship, it is first shown as a dotted line for the object that represents the one side. When you click the line, the details from the many business object are loaded and the relationship is shown.

Description of bo-relships.png follows
Description of the illustration bo-relships.png

The referenced business object, Department, also appears in the Endpoints tab for the Employee business object.

You can delete a relationship, but only if its associated business objects are not used anywhere in your application.

To create a new relationship:

  1. In the Business Objects tab, select the business object that you want to view.
    The contents of the Overview tab are displayed.
  2. Click the New Relationship icon next to Relationships.
  3. In the dialog box, select the business object you want to create a relationship with.
  4. Select the cardinality for each object (Many or One).
    You can click the Reverse Relationship button to switch between one-to-many and many-to-one. You can specify cardinalities of one-to-one and many-to-many between business objects, in addition to many-to-one and one-to-many. If you specify many-to-many, an intersection business object with two reference fields is automatically created. Its name is a concatenation of the two business objects. For an intersection business object, you can't deselect the Required check box in either of the reference fields, and the default delete rule is Cascade.
    The Enable Accessor check box is selected by default for the Many side of the relationship. Keep the check box selected unless you want to be unable to access the other business object.
  5. Edit the properties of the relationship field (the Field Name, the Display Label, the Required check box, the Delete Rule, the Display Field). For the Delete Rule, the available choices are Cascade, Restrict, and Set To Null. Whether you can edit a property and what values are available depends on the nature of the relationship and the objects.
    Description of bo-relships-mtom.png follows
    Description of the illustration bo-relships-mtom.png
  6. Click Create Relationship.
  7. Click Save to save the new relationship.
The new relationship is displayed in the Relationships list. If you specified many-to-many as the cardinality, the new intersection business object is also displayed.

To edit a relationship, click the Edit icon next to the relationship name and make the desired changes. Some fields cannot be edited and are disabled. You can specify the Display Label and select the Display Field. You may be able to select the Required check box for the field, and you can specify a Delete Rule. The following Delete Rules are available:

  • Restrict: you aren't allowed to delete a parent that has children (the default rule for a one-to-many relationship)
  • Cascade: when you delete a parent, the children of that parent are automatically deleted (the default rule for an intersection object)
  • Set To Null: when you delete a parent, the parent relationship field in the children is set to null

Add Fields to Business Objects

You can use the Fields tab of the artifact window to create fields for your business objects.

To add a new field:

  1. Open the Fields tab of the business object that you want to edit.
  2. Click the + New Field button.
  3. In the Label field, enter the name of the field.
    The Field Name value is filled in automatically based on the field label.
  4. Select the Type of the field.
    Available types are String, Number, Boolean, Datetime, Date, Time, Reference, Email, Percentage, Phone, and Uri. For a Reference type, you’ll need to specify the Referenced Business Object and the Display Field.
  5. Click Create.

Edit Business Objects Fields

You can use the Fields tab of the artifact window to modify the fields of your custom business objects.

You can edit the fields of business objects when your application is in Development status. You can edit fields to specify constraints and create validation rules for fields.

To edit the properties of a field:

  1. Open the Fields tab of the business object that you want to edit.
    The Fields tab displays a table that lists all the fields that are defined in the schema for the business object.
  2. Select the row of the field that you want to edit.

    When you select a row in the table, the editor displays the properties that you can edit.

    Description of bo-editfield.png follows
    Description of the illustration bo-editfield.png
  3. Edit the properties of the field.
    The properties that are available will depend upon the data type of the field. For example, you might be able to specify an initial value for the field using a static value, an expression, or a formula. You can also specify field constraints.
    Description of bo-editfield-props.png follows
    Description of the illustration bo-editfield-props.png

Add a Field for Aggregating Data

Use aggregation fields in your custom business objects to aggregate the data of related business objects, for example, to calculate and store the total number of items in an order.

You can use an aggregation field to calculate and store the values of simple operations such as calculating an average or sum, or counting the number of related business objects. In the Fields tab of the Business Objects page, you can edit the properties of a field to specify the fields of the related object that you want to aggregate.

To add an aggregation field:
  1. Open the Business Objects page and click the Fields tab of your business object.
    Your business object must have a related object with fields that can be aggregated using one of the available aggregation functions.
  2. Click New Field and create a field of type Number.
  3. Select the new field in the list and, if necessary, click Edit to open the properties editor.
  4. Select the Aggregate from related object data option to open the Create Aggregation dialog box.
  5. Select the object to aggregate, the aggregation function, and, usually, the field to aggregate, then click Save Aggregation.
    Description of bo-newagg.png follows
    Description of the illustration bo-newagg.png
    You can choose from the following aggregation functions: Average, Count, Maximum, Minimum and Total. You can also select the Filter Related Object Records check box to create a filter to limit the fields that are aggregated.
After you click Save Aggregation, the aggregation value is saved in the field. You can edit the aggregation by clicking the Edit icon next to the aggregation formula. When the fields are populated, you can see the value in the Data tab.

Add a Formula to a Field

You can edit fields of business objects to add formulas for calculating the value stored in the field.

You can create a formula to calculate a numerical value, such as a percentage, or you can create a Groovy expression that uses available fields to generate a value. For example, you can concatenate strings stored in local fields (firstName + ‘ ‘ + lastName) or determine a value based on a comparison or logical expression (qualityLevel != 5).

To add a formula for calculating a value:

  1. On the Business Objects page, click the Fields tab of the business object you want to modify.
  2. Select the row of the field that you want to edit.
  3. If necessary, click the Edit icon above the table to open a dialog for editing the field.
  4. Select the Calculate value with a formula option to open the Field Formula expression builder.
  5. Enter the formula in the text area.
    Description of bo-edit-formula-dialog.png follows
    Description of the illustration bo-edit-formula-dialog.png
    The formula that you enter must be a valid expression. You can specify operands by typing in the text area or by selecting the Insert arrow for a field in the list of Available Fields. You can click an operator in the toolbar to add it to the formula.
  6. Click OK to save the formula and close the dialog.
    The formula is displayed in the property inspector.

How to Format a Date Field

You can format date fields of business objects to match the format you need.

When first added to a business object, date fields use their default formatting. To format a date field:
  1. Drag an inputDate component from the component palette and drop it on top of the date field.
  2. Set that field's converter property to match the format you need.