Refresh a Business Object Catalog

If a service owner makes significant changes to the service metadata—especially its business object definition—after the workbook is integrated with the service, you can refresh the workbook's business object catalog to take advantage of the latest changes.

Refreshing a catalog is useful when changes to the service metadata are extensive—for example, when new fields, custom actions, or row finders are added to the service—and updating the business objects to incorporate these changes would take considerable time and effort. You can also refresh the catalog when a new version of Oracle Visual Builder Add-in for Excel improves the metadata harvesting.

You have two options when you refresh a catalog. You can choose to refresh all property values in the catalog with the latest values from the service metadata. Or you can choose to preserve the existing property values and only add new values from the service.

If you decide to give priority to the new metadata property values, here's what happens. If the add-in finds an existing matching field, it replaces the old title with the new title from the service metadata. If the new title is blank, it does not clear the old title. Be aware this refresh overwrites most of the changes made locally to the business object catalog. If you've spent a lot of time customizing the business object (especially field titles), choose the other option.

If you decide to give priority to existing metadata property values, the add-in does not replace your old values with the new values from the service metadata. However, it does apply a new value if the old value is blank.

Your catalog might be based on a single service metadata document that defines one or more business objects. But a catalog can also include business objects that you have imported separately and that have their own service metadata documents. When you refresh a catalog, the add-in reads the metadata path for each business object and issues a request to fetch the service metadata for that business object.

You can only refresh a catalog with URL-based service metadata documents. Catalogs with file-based service metadata documents cannot be refreshed from a file.

Note:

It is recommended that you create a backup copy of the workbook before refreshing a catalog.

To refresh a business object catalog:

1. Click Manage Catalogs in the Oracle Visual Builder tab.
2. Select the catalog to refresh in the Manage Business Object Catalogs window.
3. Click the menu icon (, then Select the Refresh Business Object Catalog.
4. From the Refresh Business Object Catalog dialog, choose an option for the refresh:
   • Give priority to the new metadata property values: Use this option to overwrite existing values in the catalog with new values from the service metadata.
   • Give priority to the existing catalog property values: Use this option to preserve existing values in the catalog and only add new values from the service metadata.
5. Click OK, then Yes when prompted to confirm the overwrite.

   If a service host is missing or you have not logged in, you'll be prompted to provide the required details. If you cancel either of these prompts, the catalog refresh ends without completing.

   If, once the catalog refresh is complete, you see this warning, then the add-in was unable to refresh one or more business objects in the catalog.
   
   To troubleshoot the error, open the log console and repeat the process to discover the cause. See Log Console.

   If the catalog refresh ends successfully, the add-in displays a message that all business objects were successfully refreshed.

6. When the refresh is complete, click OK to close the message, then Done to close the Manage Business Object Catalogs window.

   During the catalog refresh:

   • Existing business objects are refreshed based on the response from the metadata path. New business objects are added to the catalog. No business objects are removed.
   • For existing business objects, new fields, finders, custom actions, and so on are added and existing items are refreshed according to the refresh option you choose. No existing items are removed.
     • If you choose to refresh all property values, new values replace the older ones. For example, a field's title, required, and editable properties are copied from the newer version to the older version, except when a new property is empty. If a field's newer version has a list of values configured, the newer list of values replaces the older list of values. If the newer version doesn't have a list of values, the previous list of values is left unchanged.
     • If you choose to preserve your existing values, new property values are added. Only existing properties with null values are updated during the refresh.
   • A refresh does not change any field formats or clear help text since these values are always set manually and do not come from the service metadata.
7. Following the refresh, check your workbook to make sure you are satisfied with the results.

   Here are some things to be aware of:

   • The add-in's metadata harvesting improves over time. You may see changes from a refresh even if the remote metadata hasn't changed.
   • If the ID of an item has changed, it will be treated as a new item.
   • If you delete an item such as a row finder variable, it may reappear on refresh.
   • If you delete a property value, it may be given a new value on refresh.

If you want to add a new field to your layout, see Manage Fields in a Form or Table.