Manage Business Object Data During Development

VB Studio provides tools such as the Data Manager to help you manage the data stored in business objects while developing your visual applications.

In VB Studio, your visual application's code is managed separately from the data stored in the application's business objects. So deploying your application to the Visual Builder instance will deploy your application code, but not the data stored in the business objects. Some exceptions are:
  • When you enable a business object to contain application setup data. In this case, the business object's data is considered required for the application to function properly, so the data is always included when you export or publish the application.
  • When you share an application and choose to include development data from your workspace.

In most other cases, you'll need to manage your visual application's data separately.

For visual applications that are yet to be deployed to the Visual Builder instance, you can use the Data Manager to import business object data from a file into your visual application, export all data from your visual application to a file, or create a new business object in your visual application by importing a file. To access the Data Manager, open your visual application workspace, click the Options menu in the Navigator's Business Objects pane, and select Data Manager.

Open Data Manager Screen

For visual applications that are deployed to the Visual Builder instance, you can use the Deployments tab in the Environments page to import or export business object data. You can also automate this task by configuring build jobs to import or export the data. If the Visual Builder instance that hosts your deployed visual application is in a different identity domain, you can import or export the business object data only by configuring build jobs.

Note also that the Oracle Deployment step in your visual application’s deployment job includes a Data Management option to determine whether your visual application is deployed with the data from your environment, or whether it uses a clean database. See Configure the Deployment Job in Administering Visual Builder Studio.

Import Data From a File Using the Data Manager

You can replace the data in one or more of your business objects by importing CSV files and Excel spreadsheets. Use the Import from File tool in the Data Manager to simultaneously update the data for one or more business objects, for example, to import data for testing the application or in preparation for publishing the application.

To import data from a CSV file, you will need one CSV file for each of the business objects that you want to update, and the name of the CSV file must be the same as the business object. You can upload CSV files individually or upload a zip archive that contains multiple CSV files.

When importing an Excel spreadsheet (.xls or .xlsx), the spreadsheet can contain one or more sheets. The title of each sheet must be the same as the name of the business object that you want to update. If the data in a cell is calculated using a formula, only the data is imported. The formula is not imported.

When you use the import tool to replace the data in a business object, all the data for that business object is deleted from the database. If a field is defined in the schema for the object but no data for the field is contained in the file, the field is set to the default value, if there is one.
Description of bo-datamgr-csv.png follows
Description of the illustration bo-datamgr-csv.png

Each business object has five default fields: id, creationDate, lastUpdateDate, createdBy, and lastUpdatedBy.

Note:

The correct format for a Date field is yyyy-mm-dd (for example, 2006–06–17). If you edit a .csv file in Excel, Excel converts it to an incorrect format, as shown in the preceding image. To resolve this problem, you can use Format Cells in Excel to change the date format for the column; you need to specify a locale that supports yyyy-mm-dd, such as English (United Kingdom). Alternatively, edit the file in a text editor. You can't import a column that contains dates formatted dd/MM/yy HH:mm.

The import tool will not create or remove fields for business objects. You can use the Business Objects tabs to create or remove fields, to edit data, and to append data to a business object by importing a file.

To import data into a database:
  1. Click the Options menu in the Navigator's Business Objects pane and select Data Manager.
  2. Click Import from File.
  3. Drag the file into the Import Data dialog box.
    Description of bo-datamgr-import.png follows
    Description of the illustration bo-datamgr-import.png
    Alternatively, click and locate the file on your local system.
  4. Click Import.
When you import the file, you will see a success message if the import is successful. If there are any problems importing the data, you will see a message that describes the problem. For example, the message might list fields that were not imported because the fields were not defined in the schema. You can try to resolve the problem by comparing the fields in the schema to the columns in the CSV or spreadsheet file and either modifying the schema in the Fields tab or modifying the data in the file. Import the file again to correct the data.

Export the Data to a File from the Data Manager

You can export all the data contained in your database as CSV files. The export tool creates one CSV file for each of the business objects in your database and packages the files as a ZIP archive.

To export the database data as a CSV file:
  1. Click the Options menu in the Navigator's Business Objects pane and select Data Manager.
  2. Click the Export All Data tile to download a ZIP archive that contains CSV files with the data.
Alternatively, you can export the data contained in an individual business object from the object's Data tab.

Resolve Problems When Importing Data

When you import data from a file, if you see a warning message that the data was not imported or only partially imported, you might need to make changes to the file and import the file again.

To resolve problems during import, you might want to compare the data in your file to the data in the database. You can see the actual data in the database in the Data tab of your business object. You can also export the current data as a CSV file and compare the data using a tool on your local system.

When you import a CSV file with a Date field, dates must be in the standard ISO format, for example, 2017-09-31. For files with string type fields, the data in each string field must not exceed 4000 bytes.

When you see a warning message:

  1. Confirm that the name of the file or Excel workbook is the same as the name of the business object.
  2. Compare the columns in the files to the fields in the business objects.
    Importing a file will not create fields in the database schema. Columns in the file are ignored if a field with that name does not exist in the business object. The import tool expects the data in the first row of the CSV file or Excel workbook to be the name of the field.
  3. Confirm that the format and type of the data in the file are the same as those specified in the schema.

Create Business Objects From a File

You can create new business objects by importing spreadsheet files and .csv files using the Import New Business Objects wizard.

The files that you upload are analyzed to determine the business objects that can be created. You may upload comma-separated value text files (.csv) or Excel spreadsheets (.xls, .xlsx). When using .csv files to create business objects, one business object is created for each file, and the name of the business object is based on the file name. When using .xls or .xlsx files to create business objects, one business object is created for each worksheet in the file, and the name of the business object is based on the worksheet name. If the worksheet contains one or more tables, a business object is created for each table based on the table name, and the worksheet name is ignored. The first row of .csv files, worksheets, and tables must be a header row, and the column headers are used to determine the names of the fields. The data in each column is parsed to help determine the data type for the field, but you should confirm the suggested data type is correct in the Fields step of the wizard.

To upload multiple files, you need to create a ZIP archive containing the files you want to import.

To create business objects in the Import New Business Objects wizard:

  1. Click the Options menu in the Navigator's Business Objects pane and select Data Manager.
  2. On the Data Manager page, click Import Business Objects to open the Import New Business Objects wizard.
  3. In the Upload File step of the wizard, drag the file from your local system into the wizard, or click in the upload box and locate the file on your local system.

    Note:

    It is recommended that you keep the size of the file you upload small, representative of your entire data set and only what's required to create your business object model. Once your business object model is created, you can always import all your data, even large datasets, as described in Import Data From a File Using the Data Manager.

    The default character encoding format for an imported file is UTF-8. If a value isn't specified in the Character Encoding field or if the specified value is invalid, the default is used. See https://www.iana.org/assignments/character-sets/character-sets.xhtml for a list of encoding formats you can use.

    Click Upload. After the upload is complete, the wizard displays a list of the business objects and records found in the upload.


    Description of bo-datamgr-import-new.png follows
    Description of the illustration bo-datamgr-import-new.png

    Click Next.

  4. In the Business Objects step of the wizard, select the business objects that you want to create.

    The wizard displays a list of the business objects that can be created and the files in your upload that they are based on. You can select which business objects you want to create, and edit the display labels and names of the new business objects.
    Description of bo-datamgr-import-new-bo.png follows
    Description of the illustration bo-datamgr-import-new-bo.png

    Click Next.

  5. In the Fields step of the wizard, click the business object name to edit the names and types for each of the fields in the business object.

    The wizard displays tabs for each new business object. Each tab displays the fields that will be created in the business object, and a sample of the values stored in the field. You can edit each field name, display label, its data type, and specify whether it is required.
    Description of bo-datamgr-import-new-fields.png follows
    Description of the illustration bo-datamgr-import-new-fields.png

    To change the data type, click the Type icon for each field to open a pop-up box where you can modify the type. For Reference fields, you can select the related business object from an existing business object or from those that you are importing, and select the field in the related object to display.
    Description of bo-datamgr-import-new-type.png follows
    Description of the illustration bo-datamgr-import-new-type.png

    If your business object's definition contains a field to uniquely identify each record (the primary key field), you can use that field as the key instead of the system-generated id field. To change the primary key field, select the Key icon for the field you want to use. This option is enabled only for non-blank data containing numeric fields. Once you switch, the default id field will no longer be selected; you can then safely delete this field after the business object is created.
    Description of bo-datamgr-import-new-key.png follows
    Description of the illustration bo-datamgr-import-new-key.png

    Click Finish.

    The wizard displays a list of the new business objects that were successfully imported.
    Description of bo-datamgr-import-new-done.png follows
    Description of the illustration bo-datamgr-import-new-done.png

Import Data into a Deployed Visual Application

You can import data to your deployed visual application using the import tool that you access from the Deployments tab of your environment.

To import data into your environment:
  1. In the left navigator, click Environments Environments.
  2. Select the environment the visual application is deployed to.
  3. Click Deployments, then Visual Applications.
  4. For the visual application you want to import data, click Actions Actions and select Import Data to open the Import Data dialog where you upload a zip archive that contains the data you want to import.
  5. Click Import in the Import Data dialog.
    All the data in your environment is deleted and replaced when you import data. When the task is complete, a dialog opens that confirms that the data was successfully imported or warns you that there was a problem.

Export Data from Deployed Visual Applications

You can export data from your deployed visual applications using the tool that you access from the Deployments tab of your environment.

To export data from your deployed visual applications:
  1. In the left navigator, click Environments Environments.
  2. Select the environment the visual application is deployed to.
  3. Click Deployments, then Visual Applications.
  4. For the visual application where you want to export data, click Actions Actions and select Export Data to open the Export Data dialog where a message appears requesting confirmation that you want to download all data for the visual application to a zip archive.
  5. Click Export.

Configure a Build Job to Import or Export Data from a Visual Application

To import or export data from a visual application through a build job, you’ll need to add the visual application Import Data or Export Data steps to a build job, along with appropriate steps to copy or archive the artifact that contains the business object data. You’ll also need the credentials of a user who can access the Visual Builder instance where the visual application is deployed.
  1. In the left navigator, click Builds Builds.
  2. In the Jobs tab, click + Create Job.
  3. In the New Job dialog box, in Name, enter a unique name.
  4. In Description, enter the job's description.
  5. In Template, select the System Default OL7 for Visual Builder template.
  6. Click Create.
  7. Click Configure the Tools icon.
  8. Click the Steps tab.
  9. From Add Step, select Visual Application, and then select Export Data or Import Data.
  10. In Instance, select the Visual Builder instance where you want to import or export business object data.
  11. In Username and Password, enter the user's credentials who can connect to the Visual Builder instance.
  12. In Application URL Root and Application Version, enter the visual application's root URL and its version.
    You can find the application's root URL and its version from the Deployments tab of the environment where the visual application is deployed.

    Example:

  13. In Artifact, enter the name of a ZIP file that will contain the business object data to import or export. For example, enter bodata.zip.
  14. Add other steps to the build job to complete the import or export of the business object data.
    For example, to complete the export of data you’ll need to add an after build action that archives the artifact (bodata.zip, in our example) while you’ll typically need to copy an artifact from another job to import business object data. See Archive Artifacts and Copy Artifacts from Another Job in Using Visual Builder Studio for more detail.
  15. Click Save.
  16. To run a build, click Build Now.