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.

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, Oracle Visual Builder Add-in for Excel reads the metadata path for each business object and issues a request that returns the business object details from the service metadata document.

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.

Caution:

A 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), consider whether it's worth redoing those changes; it might be simpler to manually add that new field or custom action. Before refreshing a catalog, back up the workbook in case you want to revert your changes.

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 Refresh Business Object Catalog icon ().
4. 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.

5. 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 not 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. No existing items are removed.
• When an existing item is refreshed, the item's new properties replace the older properties. 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.
• 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.

If you want a new field in your layout, use the Table Column Manager to add the field after refreshing the catalog:

1. In the Layout Designer, click Columns.
2. Click Manage Columns () and select the new field. Click Done.