Professional Documents
Culture Documents
Using Oracle Visual Builder Add in Excel
Using Oracle Visual Builder Add in Excel
E90912-09
July 2020
Oracle Cloud Using the Oracle Visual Builder Add-in for Excel,
E90912-09
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on
behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software,
any programs embedded, installed or activated on delivered hardware, and modifications of such programs)
and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government
end users are "commercial computer software" or “commercial computer software documentation” pursuant
to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such,
the use, reproduction, duplication, release, display, disclosure, modification, preparation of derivative works,
and/or adaptation of i) Oracle programs (including any operating system, integrated software, any programs
embedded, installed or activated on delivered hardware, and modifications of such programs), ii) Oracle
computer documentation and/or iii) other Oracle data, is subject to the rights and limitations specified in the
license contained in the applicable contract. The terms governing the U.S. Government’s use of Oracle cloud
services are defined by the applicable contract for such services. No other rights are granted to the U.S.
Government.
This software or hardware is developed for general use in a variety of information management applications.
It is not developed or intended for use in any inherently dangerous applications, including applications that
may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you
shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its
safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this
software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of
their respective owners.
Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are
used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc,
and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered
trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content, products,
and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly
disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise
set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not
be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content,
products, or services, except as set forth in an applicable agreement between you and Oracle.
Contents
1 Get Started with the Oracle Visual Builder Add-in for Excel
What is the Oracle Visual Builder Add-in for Excel? 1-1
Key Concepts, Components, and Terms 1-1
How to Begin with the Oracle Visual Builder Add-in for Excel 1-1
iii
6 Use Lists of Values in an Excel Workbook
Configure a List of Values for a Business Object Field 6-2
Configure Filters for a List of Values 6-4
Configure Search for a List of Values 6-4
Configure a Cascading List of Values in a Layout 6-5
Clear Cache for a List of Values 6-7
7 Custom Actions
Use Custom Actions 7-1
Use Custom Actions in a Form Row of a Form-over-Table Layout 7-4
Edit Custom Actions 7-5
Service Description for Custom Actions 7-5
9 Upload Changes
Upload Changes from a Table Layout 9-1
Upload Changes from a Form-Over-Table Layout 9-1
Upload Changes Using Batch Requests 9-2
Upload Changes for Custom Actions 9-3
iv
Understanding Data Validation 13-4
Understanding Read-Only Behavior 13-5
Create New Rows to Upload to the REST Service 13-5
Delete Data from the REST Service 13-7
Upload Changes to the REST Service 13-8
View and Edit Data in a Form-over-Table Layout 13-9
Create a Parent Row in a Form-over-Table Layout 13-9
Perform Custom Actions in a Table or Form-over-Table Layout 13-10
Manage Data for Layouts in a Dependent Hierarchy 13-11
Data Consistency 13-12
15 Internationalization
Change the Add-in's Language 15-1
Refresh All Field Titles 15-2
18 Known Limitations
19 Migration
v
Audience
Preface
Using the Oracle Visual Builder Add-in for Excel describes how to develop Excel
workbooks that can retrieve and modify business data exposed by a REST service
and send modified data back to the service.
Topics:
• Audience
• Related Resources
• Documentation Accessibility
• Conventions
Audience
Using the Oracle Visual Builder Add-in for Excel is intended for Oracle Visual Builder
users who want to create and publish Excel workbooks that integrate with the
enterprise applications that they use. This guide is also helpful to users who need
to work with published Excel workbooks.
Related Resources
For more information, see these Oracle resources:
• Oracle Public Cloud
http://cloud.oracle.com
• About Oracle Visual Builder in Developing Applications with Oracle Visual Builder
• Introduction to Accessing Business Objects in Accessing Business Objects Using
REST APIs
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle
Accessibility Program website at http://www.oracle.com/pls/topic/lookup?
ctx=acc&id=docacc.
Conventions
The following text conventions are used in this document:
6
Conventions
Convention Meaning
boldface Boldface type indicates graphical user interface elements associated
with an action, or terms defined in text or the glossary.
italic Italic type indicates book titles, emphasis, or placeholder variables for
which you supply particular values.
monospace Monospace type indicates commands within a paragraph, URLs, code
in examples, text that appears on the screen, or text that you enter.
7
1
Get Started with the Oracle Visual Builder
Add-in for Excel
Learn how to use Oracle Visual Builder Add-in for Excel, an add-in that lets you
interact with data from REST web services.
Term Description
Integrated workbook An Excel workbook configured to work with one or more business objects.
Business object An entity such as employees. A business object includes a collection path, an item
path, a set of fields, and other properties.
Business object catalog A set of one or more business objects with a common host and base path.
Collection path A service path (endpoint) that can be used to fetch multiple rows of data from the
business object and/or to perform operations on the collection.
Item path A service path (endpoint) that can be used to fetch, or operate on, a single row from
the business object.
How to Begin with the Oracle Visual Builder Add-in for Excel
The Oracle Visual Builder Add-in for Excel lets users easily interact with data from
REST services. You simply download data into an Excel spreadsheet, work with it, and
upload it back to the service.
After you install the add-in, a new ribbon tab (Oracle Visual Builder) appears in
Microsoft Excel. This ribbon tab provides buttons that let you configure a worksheet
to integrate with a service and download data to a data table that you create in the
worksheet. Once the data table has been created and populated with data, you can
review, modify, and create data before uploading changes to the service.
After the Excel worksheet is integrated with the service, you can optionally publish
the Excel workbook that contains the integrated worksheet. Publication prepares the
worksheet for the users who will use it for data entry tasks. Among other changes, the
publication process removes buttons from the Oracle Visual Builder ribbon tab that are
not required by users of the integrated worksheet.
1-1
Chapter 1
How to Begin with the Oracle Visual Builder Add-in for Excel
The following image shows a published worksheet that is integrated with a REST
service that manages employees. The user of this worksheet has updated one row
and created a new row with employee data. These changes have been successfully
uploaded to the service, as indicated by messages in the Status column. The user
has also updated data in another row that has yet to be uploaded, as indicated by the
Update message in the Change column.
The image also shows the Table layout, which is one of the two types of layout that
the add-in can create in an Excel worksheet. The second type is the Form-over-Table
layout which you can configure for REST services where a parent-child relationship
exists between a parent business object and child business objects in the service. You
can create one type of layout per worksheet in your Excel workbook. That is, each
worksheet in the Excel workbook can include a layout.
Subsequent sections in this guide describe how you install, configure, publish, and
use an integrated Excel worksheet. You can integrate Excel workbooks with REST
services that provide a service description in the OpenAPI format. See REST Service
Support.
For Excel specifications and limits, see Microsoft documentation.
1-2
2
Install the Oracle Visual Builder Add-in for
Excel
You can install the Oracle Visual Builder Add-in for Excel using the installer that you
download from the Edit Data in Excel tile in your visual application’s Data Manager.
The Oracle Visual Builder Add-in for Excel is supported on Windows 10 operating
systems that run the 32-bit version of Microsoft Excel 2016 or 365 (see Supported
Platforms for the Visual Builder Add-in for Excel (Doc ID 2474783.1)).
Follow these steps to install the add-in afresh or upgrade an existing installation.
If you're upgrading, make sure you follow the recommended practices (see Best
Practices for an Upgrade).
1. Before you can install the Oracle Visual Builder Add-in for Excel, download the
vbafe-installer.exe installation file from your Visual Builder instance.
a. Open the Business Objects tab for your visual application.
b. Select Data Manager.
c. Click Edit Data in Excel.
2-1
Chapter 2
Tip:
If you want to change this setting after initial installation, you can always
re-run the installer, choose the option to repair your installation, and
change your selection.
The add-in requires the Microsoft .NET Framework and Visual Studio Tools for
Office Runtime to be installed on your computer. If this software is not present,
both are installed.
Note:
While Administrator privileges are not required to install the add-in, you
must have Administrator privileges to successfully install Microsoft .NET
Framework and Visual Studio Tools for Office Runtime. The add-in is
installed for the current Windows user only.
2-2
Chapter 2
Check for Updates
A new Oracle Visual Builder ribbon tab appears, with commands to integrate the
Excel spreadsheet with a REST service. If you disabled the design tools during
installation, you won't see the Design options.
Note:
The add-in is enabled by default after installation. You can disable and
re-enable it using the Oracle Visual Builder Add-in for Excel check
box in the COM Add-ins window (click Excel’s File > Options > Add-
Ins).
8. To verify your installation, you can download and run the Visual Builder Add-in for
Excel - Client Health Check Tool. See How to use Visual Builder Add-in for Excel -
Client Health Check Tool (Doc ID 2477792.1).
2-3
Chapter 2
Best Practices for an Upgrade
Tip:
If you are upgrading from version 1.x, review Migration first.
Table 2-1 Oracle Visual Builder Add-in for Excel Installer Command-Line
Switches
Switch Description
/help Displays a list of supported switches with description.
2-4
Chapter 2
Install from the Command Line
Table 2-1 (Cont.) Oracle Visual Builder Add-in for Excel Installer Command-
Line Switches
Switch Description
/quiet Suppresses the interactive mode of the installer and does not
install any missing prerequisite software. You can combine this
switch with others to customize your silent installation.
/designer 0 | 1 Use this switch as follows:
• 0 to disable the designer tools and install only the data
tools.
• 1 to enable the designer tools. This is the default installation
option, unless a previous installation setting exists.
/log path Runs the installer and directs the log output to the specified
log file. The default log file location is %TEMP%\vbcs\vbcs-
installer-log.txt.
/roaming 0 | 1 Use this switch as follows:
• 0 to install the add-in to the local application data
folder (%localappdata%\Oracle\Oracle Visual
Builder Add-in for Excel). Use /roaming 0 to
install to the local application data folder during an upgrade
from a prior installation that was installed to the roaming
application data folder.
• 1 to install the add-in to the user’s roaming application
data folder (%appdata%\Oracle\Oracle Visual
Builder Add-in for Excel). This is the default
installation location.
2-5
3
Create Layouts in an Excel Workbook
The Oracle Visual Builder Add-in for Excel lets you create different layouts to work with
your data in an Excel worksheet. You can create one type of layout per worksheet in
your Excel workbook. That is, each worksheet in the Excel workbook can include a
layout.
3-1
Chapter 3
Create a Table Layout in an Excel Workbook
Tip:
If you are working with Oracle business object REST API services,
the URL for the service description usually ends with /describe, for
example, https://my-service-host/fscmRestApi/resources/
latest/invoices/describe.
The add-in creates a table layout in the Excel workbook that includes column
headers and a placeholder data row. The Layout Designer opens in the Excel Task
Pane.
5. Click the Columns tab to add or remove columns, or change the order in which
columns appear. Review the list of columns to verify that the add-in only creates
the desired columns. After making changes in the Layout Designer, click Redraw
Layout to see your changes reflected in the worksheet.
3-2
Chapter 3
Work with Service Path Parameters in a Table Layout
Note:
When a table is created, most (but not all) fields are added as columns.
Click the Manage Columns button ( ) to add or remove columns as
needed.
The workbook is now complete and ready to be published. We recommend you test
the table by performing various operations, such as download, update, and upload
before you publish the workbook to distribute it to users. Alternatively, you can
configure the workbook further so that the add-in limits the data that it downloads,
as described in Configure Search Options for Download.
Tip:
When working with Oracle business object REST API services, you should
start with the web address to the parent business object description (and
not the child address). For example, when your parameterized service
path is /ExpenseReports/{ExpenseReports_Id}/child/Expenses/,
provide the address to the ExpenseReports description (not Expenses).
Oracle business object REST API services cannot provide OpenAPI service
descriptions for parameterized service paths.
Complete the layout configuration. When users click Download Data in the Oracle
Visual Builder tab, the add-in displays the Service Path Parameter Editor where users
provide the required path parameter values that enables the download of data to
complete.
3-3
Chapter 3
Create a Form-over-Table Layout in an Excel Workbook
Path parameters of type string or integer are supported; other data types are not
supported. For string-typed path parameters, values that users enter in the Service
Path Parameter Editor are used verbatim when the add-in constructs the request to
the service. For integer-typed values, certain culture-specific formatting is removed (for
example, commas for thousands separators, parentheses for negative). In all cases,
the values used on the URL path are not URL-encoded, so the values entered must be
acceptable by the REST service.
The following is an example of a service path with an embedded parameter:
/ExpenseReports/{ExpenseReports_Id}/child/Expenses/
Using the Service Path Parameter Editor, you provide the proper value for
{ExpenseReports_Id}, for example, 1232456, which results in the add-in using
the following path:
/ExpenseReports/123456/child/Expenses/
Accessing this service path will provide all the expenses for expense report 123456.
The Service Path Parameter Editor does not validate the value(s) that users enter.
The value(s) that users provide must be valid. If the path includes multiple embedded
parameters, the Service Path Parameter Editor prompts the user to provide a value for
each embedded parameter.
The add-in remembers the values provided at download time. These values are used
again at upload time to construct the upload requests. If you upload without having
done a previous download (for example, when exclusively creating new rows), you'll
be prompted for the path parameter values at the beginning of the upload.
2. Click on the cell where you want to locate the form and table.
3. In the Oracle Visual Builder tab, click Designer.
4. When prompted, provide the service description document. Use the Web Address
option (the default) if you access the service description from a URL. Note that you
can't provide a data URL (a URL that returns data) as the starting point to creating
a layout. Use the Select a file option if the service description document is a local
3-4
Chapter 3
Create a Form-over-Table Layout in an Excel Workbook
Tip:
If you are working with Oracle business object REST API services,
the URL for the service description usually ends with /describe, for
example, https://my-service-host/fscmRestApi/resources/
latest/invoices/describe.
3-5
Chapter 3
Create a Form-over-Table Layout in an Excel Workbook
If the parent business object (in this case, invoices) supports a create action, a
Create Form Row option appears in the Form Changes menu, as shown in the
image. Use this option to create a new form row during your next upload (see
Create a Parent Row in a Form-over-Table Layout).
6. Customize the form and table by modifying the automatically populated properties
in the Layout Designer. Click Redraw Layout to see changes you make in the
Layout Designer reflected in the form and table.
If, for example, you do not specify a value for the Search field or Finder property,
as described in Configure Search Options for Download, the add-in downloads the
first parent item it encounters in the REST service to the form, and the child items,
if any, to the table.
The Form tab enables you to add or remove fields to the form. The Table tab
performs a similar function for the table under the form.
Tip:
In the Form or Table tab of the designer, right-click a field or column to
see choices for changing the order.
Configuration is now complete and you can publish the workbook. We recommend you
test the workbook before you publish it to distribute it to users. Alternatively, you can
configure the workbook further so that the add-in limits the data that it downloads, as
described in Configure Search Options for Download.
3-6
Chapter 3
Manage Layout Capabilities
In your workbook, both business objects must be declared in the same service.
Continuing our example, invoicelines must appear as a child of invoices. The
add-in uses the primary ID of the parent row and inserts it into the child's path. The
workbook service must be able to support operations on these paths.
3-7
4
Edit Service Descriptions and Business
Objects
The Oracle Visual Builder Add-in for Excel provides editors where you can modify
a workbook's service description, including its definition for one or more business
objects. A service description that contains multiple business objects is sometimes
known as a Catalog.
Using the Catalog editors, you can change the URL of the host that provides access
to the REST service your workbook uses. You can also add or remove fields that
the business object exposed by the service supports; note that any changes that you
make to a business object must be supported by the service that the workbook uses.
If, for example, you add a field to a business object in the service description that
the workbook uses, and the service does not support this field, errors occur when the
workbook connects to the service.
Other examples of tasks that you can accomplish using these editors include:
• Edit field titles
• Configure the list of values for a field
• Change when a field is editable
• Configure pagination
• Adjust the field data types (Advanced)
While you can provide the service description document when you create a layout,
using the Catalog editors lets you improve the service description in a variety of ways
to enhance the overall user experience.
Note:
When you edit the service description in your workbook, you're only telling
the add-in how the service operates, you are not telling the service what
it should do. Service behavior cannot be changed from the workbook, so
any changes you make to the service description in the workbook must be
compatible with the service.
When you click Manage Catalogs in the main Oracle Visual Builder tab, the Catalog
editors show progressively. That is, you first access the editor to edit the catalog. You
then access subsequent editors for business objects and business object fields that
the catalog provides access to. You can also open the business object and business
object field editors from the Layout Designer. Both options (using Manage Catalogs
and the Layout Designer) are shown here.
4-1
Chapter 4
• To add a business object to an existing catalog (with the understanding that the
new business object will be located at the same host/base path as the other
business objects in that catalog), use the Catalog Editor (see Add a Business
Object to an Existing Catalog). This option is particularly useful when configuring a
list of values.
4-2
Chapter 4
After you import a service description document into the Excel workbook, consider
editing it in the Business Object Catalog Editor, so that the catalog has a descriptive
name. Very often, the title that the add-in displays for the catalog in the Excel
workbook is the name of one of the business objects that the service exposes. For
example, the following image shows a catalog where the default value for the Title
property is Employees. This catalog exposes an Employees business object, so to
avoid confusion, you can change the title that the catalog uses in the Excel workbook
to Human Resources Services.
After making changes in the Business Object Catalog Editor, such as changing the
service host or details of a business object, click Redraw Layout in the Oracle Visual
Builder tab to see your changes reflected in the worksheet.
4-3
Chapter 4
Create a Service Description in Oracle Visual Builder
4-4
Chapter 4
Configure Pagination for a Business Object
2. Use the newly created business object as the Referenced Business Object for
your list of values. See Configure a List of Values for a Business Object Field.
3. Click the General tab in the Business Object Editor, enter the different base path
in Base Path Override to override the base path used by all business objects in
the Catalog, and click Done.
The add-in assumes that no extra authentication is required by business objects with a
base path override.
4-5
Chapter 4
Configure Pagination for a Business Object
The following list describes a number of the properties that the Download tab allows
you configure values for:
• Offset Parameter Name: Controls where to start the next page. When fetching
the first page, the add-in uses a value of zero. When fetching the second page, the
add-in uses a value of 500, assuming the limit value is 499.
• Limit Parameter Name: Controls how many rows to fetch for each page.
• Limit Parameter Value: Controls the page size (number of rows that the add-in
downloads).
For other service types, pagination may or may not be supported. If supported,
the service may use parameter names like offset and limit or it may use other
parameter names for the same purpose.
Consult the service API documentation to determine which parameters to use.
Note:
Certain OpenAPI document properties, such as Description, can contain
formatting hints. The add-in displays the description text as is with no
interpretation of such hints.
4-6
5
Configure Search Options for Download
Configure the search options for a given layout. The configured search options are
used when the user clicks Download in the Oracle Visual Builder tab.
The add-in provides search options that you configure for each layout. The properties
that you can configure depend on the type of service that you integrate your
Excel workbook with. For example, all properties are available to use when your
workbook integrates with an Oracle business object REST API service; when you use
Oracle REST Data Services, you can only configure Search and Search Parameters
properties.
Configure values for the Search property when you want to provide users with the
option to enter search terms to filter the data that they download from the Oracle
business object REST API service or Oracle REST Data Services. Consider, for
example, a data table that downloads data about employees. In this scenario, you
can add the Department name business object field as a search field to the Search
property, so that users can enter search criteria to download the employee records of
those employees who belong to the department that matches the search criteria. You
can enter multiple fields to the Search property so that users can enter multiple terms
in their search.
Configure a value for the REST Finder property if the Oracle business object REST
API service you connect to supports finders. If you select a value for the REST Finder
property, the add-in uses it during download. A Finder that an Oracle business object
REST API service supports may have parameters. If the Finder that you choose for
the REST Finder property specifies parameters, the add-in prompts users to provide
parameter values during download.
Add values for Search Parameters if the service that you download data from supports
the addition of various parameters in the query portion string.
Depending on the service you use, you can configure one or more of these properties.
If you configure values for all properties, the add-in prompts the user to enter the
values supported by the REST Finder property before it prompts the user to enter
values for the Search property. Once the user enters the requested input values, the
add-in downloads data based on the values that the user input.
Tip:
If you are troubleshooting a particular combination of search settings, open
the Network Monitor and download data. Then, inspect request details in
the Network Monitor's window. This information may help you refine search
settings.
5-1
Chapter 5
Use Search to Limit Downloaded Data
To add more fields for complex searches, click Add Field. For example, you might
want to search for employees with a job title of Software Developer, but only those
who earn more than 8000. In this case, first select Job Title, then click Add Field
and select Salary. Finally, define the search parameters as follows:
All searchable fields are available for you to choose from. You can adjust which
fields show by selecting or deselecting Searchable in the Business Object Field
Editor. Make sure that the service supports searching on that field.
4. Click OK.
5-2
Chapter 5
Use REST Finders to Limit Downloaded Data
5-3
Chapter 5
Use Search Parameters to Limit Downloaded Data
In this example:
• "q" is an optional parameter supported by the orderReleaseLines service
• "ID" is the name of a field that supports query
• 1234 is the search value
Each service defines which parameters can be used for search. Likewise, each
service defines the required and supported syntax for the expression that appears
on the right-hand side of the assignment operator (=).
The add-in does not know which parameters are useful for search. Likewise, the
add-in does not know the proper syntax for the parameter values. So, you will need to
consult the API documentation for the service you are using to identify whether to use
"q" for the parameter name and how to formulate the search expression properly.
There is no validation in this editor or at download time. If you enter invalid information,
you may get a bad request error.
When the user clicks the Download Data button, the search parameters are added to
the appropriate URL along with the other search options (if applicable).
The add-in applies URL encoding to the parameter value at download time. So, you
should not enter URL-encoded values. The search parameter name is not encoded.
If the service supports complex searches, you can create complex searches in the
layout, as shown in the following example:
q=((firstName LIKE '*es*') or ((hireDate< "2001-01-13") and (department =
10)))
The Search Parameters property does not support "dynamic" search values. Using the
above example, the value, 1234, is specified in the Layout Designer as a constant.
The Search Parameters property works in combination with the other two properties
(where applicable). They are not mutually exclusive. However, some combinations
may work where others may not. If you choose to configure multiple search options,
you must ensure that the service supports that combination.
To add search parameters to your layout:
1. In the Excel ribbon, click Designer.
2. In the Query tab of the Layout Designer, click the add or edit search parameter
icon next to the Search Parameters property to open the Search Parameter Editor
where you add or edit search parameters.
5-4
Chapter 5
Download Behavior in Layouts that Use Search and REST Finders
Note:
Only Oracle business object REST API services support REST Finders.
If you added search fields to the Search property, the add-in prompts users who
download employee data using the Download Data button to enter values in the
search field, as illustrated in the following image.
5-5
Chapter 5
Download Behavior in Layouts that Use Search and REST Finders
5-6
6
Use Lists of Values in an Excel Workbook
The Oracle Visual Builder Add-in for Excel enables you to associate a list of values
with a business object field.
A list of values is the set of valid values for a business object field and represents a
relationship between the field in one business object and another referenced business
object. Each item in the list of values has a display value (appears in the Excel
workbook) and an identity value that is retrieved and posted to the business object
field. For example, an Employee business object's Job attribute might contain these
display and identity values:
When a business object field has a properly configured list of values, you can expect
the following behavior in Table and Form-over-Table layouts in your Excel workbook:
• On download, the identity values are replaced by the display values
• On upload, the display values are replaced by the identity values
• When a user selects a cell that is not read-only, a search-and-select window
shows a list of available display values; the user can then select one of these
values. Alternatively, the user can enter some text and click the Search icon to
filter and show values based on the user input, for example, to show values that
start with the user-specified text. See Configure Search for a List of Values.
The following image illustrates both these scenarios. For the latter scenario, the
user entered S in the search box to filter values from the list that begin with S
(Sales Manager, Sales Representative, and so on). Users can also enter the full
value in the search box, assuming it's a valid value such as Sales Manager.
6-1
Chapter 6
Configure a List of Values for a Business Object Field
The add-in supports multiple display fields for one list of values. In that case, values
of all display fields are concatenated and the concatenated value is shown in a single
Excel cell.
Note:
The list of values' data is cached in the workbook. For a list of values with
multiple display fields, if you enter a value directly in the cell that is not
yet cached, the value will be considered invalid initially. Use the search-and-
select window instead to select the value. The default search is specific
to the first display field. You can modify the search expression using the
Business Object Field Editor.
6-2
Chapter 6
Configure a List of Values for a Business Object Field
The List of Values tab in the Business Object Field Editor shows the following
properties:
• Enabled: Select to enable list of value functionality for this field; deselect to
disable
• Referenced Business Object: This business object provides the display values
for the corresponding identity values
• Identity Field: The field in the referenced business object used to look up the
display values for the identity values in the current field
• Display Fields: These fields come from the referenced business object and are
shown instead of the identity values where this field is used in a layout
To configure a list of values for a business object field that does not have one yet:
1. Select the Enabled check box in the Business Object Field Editor's List of Values
tab.
2. Select the appropriate business object using the Edit icon next to the Referenced
Business Object field.
Tip:
Pick a business object from the same catalog used to create the layout.
If the catalog is missing the desired business object, you can add a new
business object to an existing catalog (see Add a Business Object to an
Existing Catalog).
If you want to reference a business object with a different base path, you
can create or import a business object into the current catalog and then
override the base path (see Override a Business Object's Base Path).
3. Choose the appropriate identity field from the referenced business object.
4. Choose the desired display field from the referenced business object.
5. Configure Filter and Simple Search as desired (see subsequent sections for
details).
6-3
Chapter 6
Configure Filters for a List of Values
6. Click Done.
The add-in caches the data of list of values in the workbook. After you modify the
configuration of any list of values, click Redraw Layout. Then, click Clear List of
Values Cache from the Advanced menu in the Misc ribbon tab.
For more detail about using the add-in's editors to modify the business objects that
your workbook uses, see Edit Service Descriptions and Business Objects.
If the list of values' default order is unclear, you can add the orderBy parameter if the
service supports it.
6-4
Chapter 6
Configure a Cascading List of Values in a Layout
add-in does not validate the values, so if the user enters invalid information, the add-in
will make invalid requests that return errors.
1. In the Business Object Field Editor's List of Values tab, click the Add Query
Parameter icon in the Simple Search section.
2. Add values for the Name and Value properties based on what the service
supports. Many REST services support a specific query parameter such as q for
search, as in the following example:
GET…/employees?q=LAST_NAME LIKE 'Jones*'
Select the appropriate query parameter in the Name list; in our example, this is
q. In the Value text box, provide a search expression that is appropriate for the
service and include the { $options.simpleSearch } text placeholder where
appropriate. In our example, the Value is:
LAST_NAME LIKE '{ $options.simpleSearch }*'
Now, if the user enters Jo in the search box and clicks the Search icon, the resulting
request to the referenced business object will be:
GET.../employees?q=LAST_NAME LIKE 'Jo*'.
Simple Search parameters are not applied when the add-in retrieves the initial set of
values to show in the search-and-select window next to the cell in the worksheet. They
are applied only when the user clicks the Search icon (after the initial set of values are
already retrieved).
When both Filter and Simple Search parameters are configured, Filter parameters are
first applied, then Simple Search parameters. If multiple values are specified for one
parameter, the last value takes effect.
Note:
Consult the API documentation for your service to determine the appropriate
search syntax to use in the Value column. For example, if you use an Oracle
business object REST API service, you want to consult Understanding
Framework Support for Query Syntax in Accessing Business Objects Using
REST APIs. Remember that the add-in uses REST framework version 6
when making requests to a business object REST API service.
6-5
Chapter 6
Configure a Cascading List of Values in a Layout
For a cascading list of values, the value selected in one list determines the range
of values that users can select from subsequent lists. For example, a table displays
columns with lists of values for Countries, States, and Cities. The value that a user
chooses in the Countries list determines the values that appear in the list for States,
and so on.
When the service meets the following requirements, the add-in detects and wires up
the cascading list of values automatically:
• The cascading list of values resource must be configured using static links with
Finders. For example, for Countries, States, and Cities, the item links for the
parent business object must be configured as follows:
"links": {
"CountryView1": {
"operationRef": "http://servicehost/Countries/describe#/paths/
~1Countries/get",
"x-lov": {...}
},
"StateView1": {
"operationRef": "http://servicehost/States/describe#/paths/
~1States/get",
"x-lov": {...},
"parameters": {
"finder": "ByCountryFinder%3BCurrentCountry%3D{CountryId}"
}
},
"CityView1": {
"operationRef": "http://servicehost/Cities/describe#/paths/
~1Cities/get",
"x-lov": {...},
"parameters": {
"finder": "ByCountryAndStateFinder%3BCurrentCountry%3D{CountryId}
%2CCurrentState%3D{StateId}"
}
}
6-6
Chapter 6
Clear Cache for a List of Values
If the service does not have complete metadata for a list of values but you know it
supports search syntax that makes for a cascading list of values, you can use the
Filter to manually configure a list of values. See Configure a List of Values for a
Business Object Field.
6-7
7
Custom Actions
Workbooks that integrate with Oracle business object REST API services can allow
the user to perform custom actions on rows of data. For example, an invoice business
object might support a custom action called "approve". Users could download many
invoices and approve many of them in a single upload.
Note:
Your REST API must expose custom actions on the item path for
your resource, something like a POST to /contextRoot/v1/myBusObj/
{itemId}/action/doMyAction. Actions defined on the collection path
are not supported. For other limitations, see Limitations, Known Issues, and
Other Notes.
1. Create a layout for the custom action, for example, a Table layout for the "Close"
custom action.
a. In the Oracle Visual Builder tab, click Designer.
b. When prompted, provide the service description document.
c. Choose a business object, for example, purchaseOrders.
7-1
Chapter 7
Use Custom Actions
A table layout that includes column headers and a placeholder data row is created
in the Excel workbook.
2. Create new columns in the layout to pass payload field values that the custom
action needs. In this example, we'll add columns to show the Close Action and the
Close Reason payload fields.
a. In the Layout Designer, click Columns, then click Manage Columns ( ).
e. Click Done.
f. Click Redraw Layout.
The newly added columns show in the worksheet table.
3. Mark rows for the custom action.
7-2
Chapter 7
Use Custom Actions
Tip:
To mark several rows for the custom action, enter values in the
custom action column's cells (for example, Rejected in the Close
Action (Close) column and Over budget in the Close Reason
(Close) column), then copy and paste the values to other rows.
Note:
When marking cells for action, if you enter a value in a custom
action column's cell before making other edits in that row, the row
is automatically marked for that custom action. For example, in the
following image, adding Rejected in cell D2 marks the row for the
Close custom action. Note how fields that don't correspond to a
custom action in that row (PO Header Id and Order Number) can no
longer be edited. Editing fields that don't involve custom actions in
row 3 marks the row as an Update, but now, the custom action cells
in that row (corresponding to the Close Action (Close) and Close
Reason (Close) columns) cannot be updated.
7-3
Chapter 7
Use Custom Actions in a Form Row of a Form-over-Table Layout
c. If you used the Mark for Action option and only one custom action is defined
for the business object, you're prompted to confirm. If more than one custom
action is defined, you're prompted to select from a list of custom actions.
The selected table rows are updated in the Change column, and the Status Viewer
indicates that the rows are pending the selected action. Up to this point, no REST
requests have been made and the custom actions have not been performed. Data
entry validation is performed at this point on custom action field columns for the
current action.
4. Click Upload Changes to send your changes to the REST endpoint and invoke
the custom action on the marked rows. See Upload Changes for Custom Actions.
If multiple custom actions are found, you are prompted to select an action, as
shown here. Otherwise, you are prompted to confirm the action.
3. If payload fields are required, provide a value for each payload field.
7-4
Chapter 7
Edit Custom Actions
"/purchaseOrders/{purchaseOrders_Id}/action/close": {
"parameters": [
{
"$ref": "#/components/parameters/purchaseOrders_Id"
}
],
"post": {
"summary": "close",
"description": "close",
"operationId": "do_close_purchaseOrders",
7-5
Chapter 7
Service Description for Custom Actions
"responses": {
"default": {
"description": "The following table describes the default
response for this task.",
"content": {
"application/vnd.oracle.adf.actionresult+json": {
"schema": {
"type": "object",
"properties": {
"result": {
"type": "string"
}
},
"required": [
"result"
],
"additionalProperties": false
}
}
}
}
},
"requestBody": {
"description": "The following table describes the body
parameters in the request for this task.",
"content": {
"application/vnd.oracle.adf.action+json": {
"schema": {
"type": "object",
"properties": {
"closeAction": {
"type": "string",
"nullable": true
},
"closeReason": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
}
}
}
}
}
7-6
Chapter 7
Service Description for Custom Actions
• In the requestBody schema, there are properties that match the parameters
defined in the custom method signature from the service. In this document, these
properties are referred to as custom action payload fields.
7-7
8
Appearance of an Integrated Excel
Workbook
Oracle Visual Builder Add-in for Excel automatically manages the appearance of an
integrated Excel workbook through built-in styles and data format types.
The add-in automatically formats cells in a workbook by creating a set of named
Excel styles when the workbook is first initialized. The styles created by the add-in
are consistent with Oracle Alta UI standards and Oracle accessibility guidelines. The
format portion of the styles is sensitive to the user's preferences as defined in the
Windows region settings. So a US user will see US dates and a French user will see
French dates.
Once the styles are initialized, the add-in applies those styles to the integrated cells,
according to the field's properties, at key points (such as during a data download).
Typically, the styles are created once for a workbook and are never updated, but you
can take advantage of the following options:
• Reset Workbook Styles
• Choose Field Formats
You are prompted to confirm. After confirmation, each style definition used by the
add-in is updated. The list of styles includes any style that would be created by the
current add-in, including the Normal style.
8-1
Chapter 8
Choose Field Formats
Note:
You can't reset styles in published workbooks.
3. Click Done.
4. Click Redraw Layout or Download Data to process the change.
8-2
9
Upload Changes
When you are done making changes in an Excel workbook, you are ready to upload
the changes to the REST service.
9-1
Chapter 9
Upload Changes Using Batch Requests
1. The add-in checks the form for a pending Update or pending Create operation
and the table for pending changes. If there are no pending form or table changes,
upload is skipped.
2. If a Pre-Upload macro is configured, it is invoked. If the macro throws an exception
or returns any value other than true, the upload process aborts.
3. When the form has a pending Update or pending Create operation:
For a pending Update:
a. A GET request is sent to the parent's item path.
b. Form field values (for example, data type, required, and so on) are validated;
read-only fields are skipped. If validation failures exist, the upload is stopped
and no subsequent REST requests are made.
c. When all form fields are valid, a request (PATCH/PUT) is sent to the parent's
item path. The payload for this request contains the values of all form fields
that have been changed.
For a pending Create:
a. Form field values (for example, data type, required, and so on) are validated
(see Understanding Data Validation); read-only fields are skipped. If validation
failures exist, the upload is stopped and no subsequent REST requests are
made.
b. A POST request is sent to the parent's collection path. The payload for this
request contains a value (possibly empty) for every editable form field in the
form.
The child table is not involved in this step.
4. The results of the form upload are reflected in the status viewer immediately.
5. If the form upload fails, the add-in stops and does not attempt an upload on the
child table.
6. If the form upload succeeds, the add-in proceeds with the child table as follows:
a. Checks the child table for pending changes, creates, deletes, custom actions,
etc.
b. If changes are found, the child table upload proceeds in the same manner as
a table layout upload with one important difference: the child business object's
paths are used for each request.
The add-in ensures that the parameters in the child business object paths are
replaced with the correct values during the table upload operation.
If the form and table both have pending changes, there are a minimum of two
requests: one for the form and one (or more) for the child table.
The form and child table changes are never sent in a single request. In particular,
sending a single request where the payload contains values from the parent form
fields along with an array of values from the child table rows is not supported.
9-2
Chapter 9
Upload Changes for Custom Actions
If a batch request contains one or more errors, no changes are made by the service.
In that case, a second batch request containing only the rows that succeeded during
the first batch request is sent. If the second batch request fails, the add-in falls back to
sending one request per row. For more information, see Making Batch Requests.
{
"closeAction": "Rejected",
"closeReason": "Over budget"
}
– There is no other content in the POST request body (no action name, no
array of argument values).
– If any values from these columns are invalid (missing when required,
incorrect data type, Excel formula error), the row is omitted from the
Upload and marked as failed.
• Prepares the request
– REST-Framework-Version header added (version 6)
– Content-Type header added based on each custom action's Request
Media Type property on the Custom Action Editor (available from the
Business Object Editor > Custom Actions tab)
• Makes the request
– Sends the POST (POST is the only HTTP method supported for invoking
custom actions)
– See the note below about batch requests.
• Processes the response
– For 200 response status, the row is marked as succeeded.
9-3
Chapter 9
Upload Changes for Custom Actions
– For 400 response status, the row is marked as failed, and the response
payload is parsed for Oracle business object REST API service error
content; error details can be seen in the Status Viewer pane.
– A 412 response status indicates that the row was modified by some other
agent or user after it was downloaded to the Excel table; such a status is
treated as a row-level error
Cell values in action rows are not refreshed. If the custom method logic in the
service has altered any values in the row, those changes will not be reflected
in the table row until the next download.
Note:
If a row is marked for a custom action, the entire upload operation is
performed row-by-row (batch requests are not used).
9-4
10
Use Multiple Layouts for Multi-level
Business Objects
When business objects in your REST service have a parent-child relationship of 3
or more levels, you can link layouts in a hierarchy of dependent layouts to perform
coordinated download, upload, and clear operations. Many operations triggered in
a layout that's part of a hierarchy of dependent layouts work on all layouts in the
hierarchy.
In a hierarchy of dependent layouts, the primary layout is always a Form-over-Table,
one that's based on the parent business object (in the form) and a child business
object (in the table). Additional Table layouts, created on separate worksheets, are
based on descendant business objects, relative to the parent business object. In other
words, the first Table layout uses a grandchild business object, the next one uses a
great-grandchild business object, and so on. Each of these dependent layouts is linked
to its direct parent layout. Once the dependencies are established, download, upload,
and clear operations act on all the linked layouts, starting from the parent layout,
followed by the child layout, the grandchild layout, and so on.
In addition to coordinating operations such as download and upload across multiple
layouts, there's another key distinction when using layouts in a dependent hierarchy:
In the grandchild layout, the add-in will fetch all rows for each of the child rows
and display them all together in the grandchild layout. This behavior applies to the
grandchild and lower layouts in the hierarchy (basically, all Table layouts that follow the
primary Form-over-Table layout.
Consider this example hierarchy of business objects, where purchaseOrders is the
parent, lines is the child, schedules is the grandchild, and distributions is the great-
grandchild.
10-1
Chapter 10
Note:
Sibling relationships (two or more layouts with the same parent layout) are
not supported.
Let's use this example to create a hierarchy of dependent layouts that mirrors your
business object hierarchy. Remember, the primary layout in the hierarchy must be a
Form-over-Table; the dependent layouts must be Tables.
1. Create a Form-Over-Table layout for the first two levels in the business object
hierarchy.
a. In the Oracle Visual Builder tab, click Designer.
b. When prompted, provide the service description document.
c. Choose the parent business object. For example, select purchaseOrders to
create a layout for purchaseOrders over lines (the first two levels in our
hierarchy) and click OK.
d. Select Form-over-Table Layout as the new layout and click OK.
A Form-over-Table layout is created in the worksheet, where purchaseOrders is
the form business object and lines is the table business object. This worksheet is
now your primary layout.
2. Create a Table layout for each of the other levels in your business object hierarchy.
Ensure that you select the same business object catalog that is used by your
primary Form-Over-Table layout.
a. Click the New Sheet icon to add a new worksheet.
b. Click Designer.
c. Choose the business object that's third in the hierarchy, for example,
schedules, and click OK.
d. Select Table Layout as the new layout and click OK.
10-2
Chapter 10
e. Repeat steps a to d to create Table layouts for all the remaining levels in your
business object hierarchy. Continuing our example, create a Table layout for
distributions.
A Table layout is created for each level in the business object hierarchy. Notice
the Parent Layout field in the Layout Designer's General tab, shown here for the
schedules layout. This field shows only in layouts where the business object is a
child of another business object in the same business catalog.
3. Starting from the lowest level in the hierarchy, choose the parent for each layout.
a. On the worksheet for the last item in the hierarchy (distributions in our
example), click the Choose Parent Layout icon ( ) in the Layout Designer's
General tab.
b. When prompted, click Yes to confirm the parent layout in the hierarchy, for
example:
c. For layouts that are three levels or deeper in the hierarchy (for example,
schedules and distributions), if you want to support creating new rows and
create is enabled in the Table's capabilities, click the Choose Parent Column
icon ( ) and select a field from the parent layout to uniquely identify the parent
row for a pending create row in the child layout. The field must be exposed
as a column in the parent table, for example, the Line Location Id field which
exists as a column in the schedules table. (If you don't see the field you want
to use, you'll need to add it as a column in the parent table.) Click OK.
10-3
Chapter 10
d. Click Redraw Layout for both the child and parent worksheets.
A column for the corresponding parent field is created in the child layout, for
example, the Line Location Id (schedules) column as shown here:
e. Repeat steps a to d for each Table layout in your business object hierarchy.
Continuing our example, the parent layout for schedules is purchaseOrders-
lines (which is also the primary layout). You don't need to set a parent for the
primary layout.
Once a layout has its Parent Layout defined, you'll notice a Child Layout field
in its parent's Layout Designer. Also, search specifications (defined in the Query
tab) are no longer available for any dependent layout that is not the primary
layout. Here's the Layout Designer for the schedules Table layout, whose parent is
purchaseOrders-lines and child is distributions.
10-4
Chapter 10
Delete a Dependent Layout
Configuration for your dependent layout is complete. You can choose to configure
the workbook further to limit the data that is downloaded to the primary layout (see
Configure Search Options for Download).
Before you publish and distribute your workbook to users, test the workbook to ensure
that download, upload, or clear operations work on all layouts in the hierarchy (see
Manage Data for Layouts in a Dependent Hierarchy).
10-5
Chapter 10
Delete a Dependent Layout
10-6
11
Use Macros in an Integrated Excel
Workbook
You can configure macros that the Oracle Visual Builder Add-in for Excel executes at
specific points in the lifecycle of an integrated Excel workbook.
Use of this functionality requires you to use the Excel macro-enabled workbook type
(.XLSM) and create your macros in a macro module. For more information about
creating macros, see Microsoft documentation; describing how to create macros in
an Excel workbook is outside the scope of this guide.
Some companies block the usage of Excel macros because they do not think macros
are sufficiently secure. Consider your intended user base before you add a macro. You
are also responsible for the security risks involved in using macros. So research the
risks thoroughly before you deliver an integrated workbook to your customers. After
creating a macro, take steps to protect the macro both from malicious and accidental
alterations that might produce unexpected or harmful results. If a macro results in
changes that are incompatible with the add-in or results in undesirable behavior,
change the macro to avoid this behavior.
The Layout Designer’s Advanced tab provides two properties where you can specify
macros: the Post-Download Macro to execute after download completes and the
Pre-Upload Macro to execute before an upload begins. Provide your macro names
as the values of these properties. For example, when you've created a Refresh
macro that you want to run after an upload, enter Refresh as the value of the
Post-Download Macro property.
Tip:
Do not include the parentheses when specifying the name of the macro.
The macro that you specify for the Post-Download Macro property is not used if the
user cancels download, if the table or form is empty, or in the event of an unexpected
11-1
Chapter 11
error. The macro that you specify for the Pre-Upload Macro property is used just
before an upload. If the macro returns any value other than true, the upload operation
aborts and a notification appears in the Status Viewer. If the macro returns true,
upload proceeds normally. To return a true or false value from a macro, define a
Boolean Function. See Microsoft documentation for details.
Here's example logic of an IsUploadReady function for a Pre-Upload Macro:
returnVal = True
IsUploadReady = returnVal
Exit Function
ErrHandler:
Dim failureMessage As String
failureMessage = Err.Description
MsgBox failureMessage
IsUploadReady = False
Exit Function
End Function
When an error occurs during the execution of a macro, Excel displays a Microsoft
Visual Basic window to the user. We recommend that you implement a robust error
handling strategy so that the window displays a useful message to the user who
encounters an error during macro execution. The following is a simplistic example.
The appropriate error handling strategy for a given macro depends on the logic in the
macro.
Sub Refresh()
11-2
Chapter 11
ActiveWorkbook.RefreshAll
Exit Sub
ErrHandler:
Dim failureMessage As String
failureMessage = Err.Description
MsgBox "Unable to refresh. Details: " & failureMessage
Exit Sub
End Sub
Tip:
The add-in creates and maintains named ranges for the data table. Your
macros should never modify these named ranges. However, your macros
can access the named range to locate the data table on a dynamic basis.
Note:
Macro recording is incompatible with add-in features such as download and
upload and is not supported. Do not attempt to record any add-in features. In
some cases, you may see unexpected exceptions.
Do not leave the Excel Visual Basic editor’s break mode on when you use
Download Data or Upload Changes. It is not supported and can result in an
unexpected exception.
11-3
12
Publish an Integrated Excel Workbook
Once you complete configuration of an Excel workbook, you can publish it for users to
do data entry work. Publishing creates a copy of the workbook with the design tools
hidden and worksheet protection turned on for each worksheet with a layout.
The recommended steps to take before you publish an Excel workbook are:
1. Complete configuration of the workbook.
2. Test the configuration thoroughly.
3. Use Excel’s Inspect Workbook feature to review and remove personal information
from the workbook.
4. In the Oracle Visual Builder tab, click Clear for each layout in the workbook.
5. In the Advanced drop-down, click Clear List of Values Cache.
6. Save this source version of the workbook.
Note:
Publishing is optional. All the data editing features of an integrated workbook
are available in both published and unpublished copies of the workbook.
Once you configure and test your workbook, make a backup copy of the unpublished
(source) workbook in case you need to make further configuration changes at a
later date post-publication. Consider adding a file name suffix of –src for the source
workbook. Then, remove the suffix in the published copy. Excel will not allow you to
use the same file name for both workbooks. You click the Clear button before you
publish it. Clearing data works on the current layout; if your workbook has multiple
layouts, you should ideally clear each layout.
Use Excel's Inspect Workbook feature to review and remove your personal information
from the workbook before you distribute it. You access the Inspect Workbook feature
from Excel's File menu. Deselect the check box next to the Hidden Worksheets entry
in the Document Inspector where you choose the content to inspect and potentially
remove. You must not remove hidden worksheets from the Excel workbook that you
distribute. The Oracle Visual Builder Add-in uses hidden worksheets to integrate the
Excel workbook with the REST service.
Once you are ready to distribute the workbook to users, click Publish. In the Publish
Workbook window that appears, select Remove the service host from each service
in the published workbook if you want users to enter the service host when they
open the published workbook, and click OK.
12-1
Chapter 12
Accept the default file name and directory location values for the published workbook
or select alternative values in the subsequent window, then click Save. You can now
distribute the published workbook to users.
When a user performs an action that requires access to the REST service in
a published workbook where you removed the service host value, a Service
Configuration window prompts the user to enter their service host value before
the action can be executed. Actions that require access to the service include the
Download Data and Upload Changes commands.
There are a number of differences with the source workbook:
• The design tools do not appear in the Oracle Visual Builder tab of the Excel ribbon
(Designer, Delete Layout, and Publish buttons), as shown in the following image.
• Excel's sheet protection is on. This mode enables true read-only behavior for cells
that should be read-only. It also prevents the user from performing various other
Excel actions that might disrupt the integration with the service.
12-2
13
View and Edit Data Using an Excel
Workbook
In Microsoft Excel, select the Oracle Visual Builder tab to perform operations and
work with data in a workbook.
Users can perform the following operations in a layout if the REST service business
object associated with the layout supports the operation:
• Edit existing rows
• Create new rows
• Delete existing rows
• Perform custom actions on existing rows
Note:
If the user's action requires access to the REST service and the service host
is missing (because it was removed when the workbook was published), a
Service Configuration window prompts the user to enter their service host
value before the action can be executed. Actions that require access to
the service include the Download Data and Upload Changes commands.
13-1
Chapter 13
Download Data to the Workbook Table
If the business object supports pagination, the add-in retrieves one page of rows, then
prompts the user whether to attempt downloading more rows. You can view if the
business object supports pagination, and change the default download limit of 499, in
the Download tab of the Business Object Editor.
13-2
Chapter 13
Edit Downloaded Data in the Workbook
On successful connection to the service and completion of prompts for input values
to search data (if configured), the add-in updates the table in the worksheet with data
retrieved from the service.
If the workbook includes a list of values, users need to clear the list of values' cache
whenever the cached data is stale compared with the latest results from the service
(see Clear Cache for a List of Values).
For columns that are associated with a field configured to use a list of values, users
can select a value in a search-and-select window that displays available values. A
user can select one of the displayed values. In this case, the Change column displays
Update. Alternatively, the user can enter one or more of the starting characters for
other values and then click the Search icon so that the search box filters the values
it displays based on the user's input. The following composite image displays both of
the just-described scenarios. For the latter scenario, the user typed S in the search box
next to the Search icon to find all the display values that start with S (Sales Manager,
Sales Representative, and so on).
13-3
Chapter 13
Understanding Data Validation
Note:
You can alter the search behavior of the list of values using the Business
Object Field Editor described in Use Lists of Values in an Excel Workbook.
Users can update the form fields in a Form-over-Table layout if the business object
for the form fields supports update. The add-in performs data entry validation before
it attempts to upload a user's updates. Data entry failures need to be addressed by
the user before the add-in uploads changes. For a form field configured to use a
list of values, the behavior is the same as described for the Table layout. That is, a
search-and-select window appears when the user selects the form field. In a published
workbook or when worksheet protection is enabled, read-only form fields as defined in
the business object cannot be edited. You can make a form read-only by deselecting
the Update Enabled check box under Form Capabilities in the Layout Designer's
Advanced tab.
13-4
Chapter 13
Understanding Read-Only Behavior
Validation occurs when you complete data entry in a cell; in other words, as soon as
you enter or edit a value in a cell and move on to another cell or area. Validation also
occurs at other key points:
• When a new row is added to the data table
• When a form create starts
• At the beginning of an upload.
When a row is marked for a custom action, the custom action's payload fields also
receive the same validation. See Custom Actions.
Typically, the add-in determines whether a cell's value is consistent with the data type
specified in the business object field definition. It also checks whether a required cell
is missing a value, and whether the value in a cell associated with a list of values is a
valid value for that list.
Local field properties are used for validation. Validation that is enforced by the REST
service is not triggered at the points mentioned here. REST service validation is
generally triggered by the requests sent during Upload (for details on Upload failure
handling, see Upload Changes to the REST Service).
13-5
Chapter 13
Create New Rows to Upload to the REST Service
The add-in inserts a new row in the table. A Create message appears in the
Change column and an Invalid message will appear in the Status column if the
newly created row requires you to specify valid or required values.
• To insert new rows in the middle of the table, select a cell inside the current table's
boundaries. The following example shows where three new Excel rows have been
inserted inside the current table boundaries. A message (Create) appears on the
left of each new row to indicate this row is new and has not yet been uploaded to
the service. Edit the cells in these new rows with the data changes that you want
to make. An Invalid message appears in the Status column rows until you enter
valid values, as indicated by the red border that surrounds a number of cells in
Rows 4 and 5. Required values and valid values have been entered in the newly
inserted Row 3, so it does not display the Invalid message or the red border cells
(see Understanding Data Validation).
Tip:
If you select some cells from multiple rows in the table and then select
Insert Rows from Table Row Changes, the add-in will create multiple
pending Create rows for you to fill out as needed.
• To create several new rows without downloading data, if the Table has Create
enabled, add values in the empty row that appears below the column headers.
This empty row is known as the placeholder row. The add-in will automatically
recognize the row as a pending Create row. Then, it behaves like any other newly
inserted row.
In the following image, users can enter data (for example) in the row cells
for First Name, Email*, Hire Date, and Department. Once a user enters a
value in a row that accepts data input, a Create message appears in the
Change column. An Invalid message appears in the Status column if the row
contains a cell where the user is required to enter a value and has yet to do
so, or has entered an incorrect value, such as an unexpected data type. A
red border also appears around the cell where a value is required or invalid.
Once the user enters data in the row, the row below the current row becomes a
row where data values can be entered, and so on. This method is not available
in published workbooks due to worksheet protection. Instead, the user can select
a cell in the first row after the table and select Insert Rows from the Table Row
Changes menu.
13-6
Chapter 13
Delete Data from the REST Service
After the new rows are created, click Upload Changes to upload the pending Create
rows to the service.
13-7
Chapter 13
Upload Changes to the REST Service
Tip:
If you change your mind about deleting one or more rows that you
have marked for deletion, select these rows and select Unmark Pending
Changes from the Table Row Changes menu, so that the add-in does
not include these rows in the rows that it sends to the service for deletion.
Use Unmark Pending Changes before you upload changes from the Excel
workbook; the option does not work after the changes are uploaded.
How the add-in uploads modified rows depends on the type of service that your
workbook uses. For workbooks that use Oracle business object REST API services,
the add-in uploads the modified rows in batches. For other types of services, the
add-in uploads modified rows one row at a time.
Tip:
If you change your mind about uploading changes for a particular row to the
service, select these rows, then use the Table Row Changes menu to select
the Unmark Pending Changes option, so that the add-in does not include
these rows in the rows that it sends to the service for update, creation, or
deletion.
13-8
Chapter 13
View and Edit Data in a Form-over-Table Layout
The user can then enter form field values, even create new child table rows. All
changes are marked as a pending create, until the user clicks Upload Changes. The
add-in validates the data before it attempts to upload the user’s updates, and any data
entry failures need to be addressed before the changes can be uploaded.
13-9
Chapter 13
Perform Custom Actions in a Table or Form-over-Table Layout
Take note of rows 2, 3, and 5: except for the cell corresponding to the Adjust Salary
custom action, all other cells are read-only. Conversely, in row 4, the Adjust Salary
custom action cell is read-only. In other words, the first action users perform on a row
determines that row's pending action: if you add or update a value in a custom action
cell, the row is marked for that custom action in the Change column; if you add or
update a value in a cell that doesn't involve a custom action, the row is marked as an
Update in the Change column. You can also use the Status Viewer to see the pending
action for a selected row.
If you're working with a Form-over-Table layout, select Perform Action in the Form
Changes menu, then follow the prompts to perform custom actions on a Form row.
A custom action can be performed only on an existing row (not on a pending Create
row).
13-10
Chapter 13
Manage Data for Layouts in a Dependent Hierarchy
Form row data is not automatically refreshed after a custom action is performed, even
if the action was successful. Click Download Data if you want to refresh data in the
form row.
When you are done making changes in a layout, click Upload Changes.
13-11
Chapter 13
Data Consistency
Users can view details of the operation in the primary Form-over-Table layout's Status
column, which shows results for the primary layout as well as a summary for each
layout in the dependent hierarchy, as shown in this example for a download operation:
Data Consistency
When a workbook uses an Oracle business object REST API service that supports
data consistency verification using an entity tag (Etag) mechanism, the add-in detects
and reacts to the following scenario:
1. User A downloads information from a business object into a table in their
integrated workbook.
2. User B downloads the same information into a table in their integrated workbook,
edits it, and uploads changes.
3. User A then edits the same information (downloaded in Step 1) and uploads the
changes.
4. The add-in provides the service with the necessary information (entity tags) to
prevent User A's changes from overwriting those changes made by User B.
Instead, when the server detects such a change, its response allows the add-in
to display an error message similar to the following for any such rows in the table:
This row has been modified by another user. Please download before editing.
For information about the entity tag (ETag) mechanism, see Data Consistency Tasks in
Accessing Business Objects Using REST APIs.
If your workbook uses other types of REST services, the last writer wins. So, for the
scenario just outlined, User A’s changes in Step 3 will overwrite the changes of User B
in Step 2.
13-12
14
REST Service Support
This chapter provides additional technical details about how the Oracle Visual Builder
Add-in for Excel supports integration with REST services. It also provides information
about technical known issues and limitations.
Service Descriptions
To create a layout in the workbook, the REST services that you use must provide
a service description that complies with the OpenAPI specification. The service
description can be a URL or a local file. For Oracle business object REST
API services, the URL typically includes a describe, as in https://my-service-
host/fscmRestApi/resources/latest/invoices/describe. For an Oracle REST Data
Services (ORDS), the URL may be similar to https://host/ords/great_app/open-
api-catalog/employees/.
You can provide the service description document when you create a layout by clicking
Designer in the Oracle Visual Builder tab (see Create Layouts in an Excel Workbook).
You can also provide the service description document by clicking Manage Catalogs
in the Oracle Visual Builder tab (see Edit Service Descriptions and Business Objects).
Service Types
The add-in provides special support for:
• Oracle business object REST API services
– Uses and requires REST API framework version 6
– Provides search editor capabilities
– Supports the ability to upload in batches
– Supports finders
• Oracle REST Data Services (ORDS)
– Provides search editor capabilities
See Oracle REST Data Services.
The add-in can also be used with other service types as long as the service behaves
as the add-in expects.
14-1
Chapter 14
• object
• number
• string
In addition, the add-in recognizes the optional modifier property "format", when it
is applied to values of type string. The two formats recognized are "date-time" and
"date". There is no support for binary or byte formats or for array-valued fields.
The add-in ignores fields with unsupported data types when you create a Table layout
or Form-over-Table layout in the Excel workbook. If, for example, a service that you
use to retrieve data includes the attachment attribute data type, the add-in ignores it
and does not create a column in the data table for this attribute type.
For more information, see the specifications for OpenAPI and JSON Schema:
• OpenApi: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/
3.0.0.md#dataTypes
• JSON Schema: https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2
14-2
Chapter 14
maintains a regular, rectangular structure for the table in the worksheet. So, the
above example generates a table with these columns:
• First Name
• Last Name
• Address / Street
• Address / City
• Address / State
• Address / Zip
• Address / GPS Coords / Latitude
• Address / GPS Coords / Longitude
• Hire Date
REST Operations
Table and Form-over-Table capabilities are enabled as follows:
• Existing row updates are enabled if the item path has either a PUT or PATCH
operation. For PATCH operations, the add-in includes all data values from editable
cells for the changed row(s) on upload, regardless of whether the data value was
edited since download.
• Create new rows is enabled if the collection path has a POST operation
• Delete existing rows is enabled if the item path has a DELETE operation (not
supported for Form-over-Table)
Note:
You can choose to disable a layout's capability even if the business object
supports the operation, by deselecting it in the Layout Designer's Advanced
tab.
Language Support
For every request that the add-in makes to the REST service, the add-in automatically
adds the accept-language header. By default, the value sent with the accept-
language header is the language/culture code that Excel is currently configured to
use. You can change the language as described in Change the Add-in's Language.
Each REST service determines how and whether it will react to the accept-
language header.
14-3
Chapter 14
14-4
Chapter 14
– When creating the business object field from the JSON member, the add-in
uses the member name as the field ID.
– Field IDs that include the / character are incompatible with the add-in, so such
members will not be represented as fields in the business object.
• When providing a URL for an OpenAPI service description, ?
metadataMode=minimal is not supported.
If a REST service owner makes significant changes to the service after the workbook
is configured to integrate with the service, the integration may not function as
expected. In such cases, you will need to re-import the service description and create
a new layout. Or, if the change is minor, you may choose to update the business
object details to match the change in the service. See Edit Service Descriptions and
Business Objects.
14-5
15
Internationalization
The Oracle Visual Builder Add-in for Excel is localized in Oracle standard languages. It
automatically detects the user's preferred language from Microsoft Excel and uses that
language where possible.
The date, date-time, and number formats used by the add-in are culture-sensitive (see
also Appearance of an Integrated Excel Workbook).
When using the add-in, you work with:
• Labels visible on the Oracle Visual Builder ribbon and in various windows
displayed by the add-in. These labels, known as the add-in labels, are owned
by the add-in and are localized.
• Labels visible as column headers and field labels are known as business object
field titles. These titles are owned by the REST service.
The add-in sends the accept-language header to the service on every request. The
language setting specified for Excel is used for the add-in labels and for requests to
the service, including the describe requests that fetches the initial business object field
titles.
Note:
Because business object field titles are owned by the service, contact the
service owner for any missing translations or languages.
15-1
Chapter 15
Refresh All Field Titles
4. Click OK.
5. Restart Excel to make your changes take effect.
The add-in's user interface elements (Download Data and so on) now use the
language you selected. If the selected language uses a right-to-left writing system, the
add-in's user interface elements appear in right-to-left mode. The language that Excel
uses remains unchanged, as does the format used for dates, times, and numbers. See
Excel’s and/or Windows options to change Excel’s language and formats for dates,
times, and numbers.
The language that you choose for the add-in language is stored in a local file in the
Windows user profile. You can select the Use Excel’s Language Setting option in the
Add-in Language drop-down list to remove this setting for the current user.
Caution:
A reset wipes out any local changes made to field titles using the Business
Object Field Editor.
15-2
Chapter 15
Refresh All Field Titles
Note:
The reset functionality relies on the /describe response from the Oracle
business object REST API service, with the add-in sending the current
language preference in the request. A given service may or may not have
translations for the requested language. For any missing translations, contact
the owner of the service.
15-3
16
Security Best Practices
When using the Oracle Visual Builder Add-in for Excel, follow these security-related
best practices and recommendations.
Security Guidelines
Follow these best practices:
• Update the add-in to the latest version available.
• Restrict access to Excel documents containing sensitive data.
• Consider adding passwords to workbooks to further reduce exposure.
• Always use HTTPS endpoints instead of HTTP.
• Do not use basic authentication.
• Ensure that the latest Windows updates and security patches have been applied
to the computers where you install the add-in.
• Turn off older obsolete security protocols such as SSL.
• Also, consider using Excel's Inspect Workbook feature to review and remove your
personal information from the workbook before you distribute it. Do this for un-
published workbooks. You access the Inspect Workbook feature from Excel's File
menu. Clear the check box next to the Hidden Worksheets entry in the Document
Inspector where you choose the content to inspect and potentially remove. You
must not remove hidden worksheets from the Excel workbook that you distribute.
The add-in uses hidden worksheets to integrate the Excel workbook with the
REST service.
Basic Authentication
The add-in supports basic authentication. When using REST service endpoints
protected by basic authentication, the user is prompted for credentials when the
add-in connects to the endpoint. When used with HTTP, basic authentication is not
secure. Basic authentication should only be used with HTTPS, and preferably only in
non-production environments.
16-1
Chapter 16
Note:
In this release of the add-in, using self-signed certificates with the JWT
relay servlet will not work. A valid certificate issued from a well-known root
certificate authority should work fine with the JWT relay servlet.
16-2
17
Troubleshoot Excel Workbooks
The Oracle Visual Builder Add-in for Excel can generate a detailed log file and
diagnostic report to help you identify and resolve issues in the Excel workbooks that
you integrate using the add-in.
In addition, consider running the Client Health Check tool to determine if your
environment is configured correctly after you install the add-in. You download this
tool from My Oracle Support. See How to use Visual Builder Add-in for Excel - Client
Health Check Tool (Doc ID 2477792.1)
Additional information about troubleshooting can be found in Troubleshooting Guide
for the Visual Builder Add-in for Excel (Doc ID 2485062.1).
Network Monitor
Use the Network Monitor window to inspect the content of REST service calls between
your Excel workbook and the REST service that it connects to if you encounter
unexpected behavior.
The Network Monitor window provides information such as the start time, the elapsed
time, and response for each REST call that originates from the workbook. In addition,
it provides the JSON payloads that the Excel workbook and the service exchange.
The Network Monitor window generally goes to the background while you perform the
steps of your use case. Bring the window forward to see the details of each request
and response. You can select and copy information from the window. You may need
this detail when troubleshooting problems with the service owner. The window shows
up to 100 request-response events. Older events are discarded as new ones are
added.
1. In Excel, click the Oracle Visual Builder tab.
2. Select Network Monitor.
The Network Monitor window displays.
3. Repeat the steps that lead to the issue.
4. Review the details of each request and response.
5. Optionally, right-click an entry for a REST service call in the upper table, and
choose the Save request-response details as ... option to save the information
to a file.
Caution:
Request and response payloads may include sensitive information,
including actual data and personally identifiable information. Be sure to
handle these payloads with due care.
17-1
Chapter 17
Logging
Logging
When reporting an issue about the Oracle Visual Builder Add-in for Excel, generate a
detailed log file that captures the steps that lead to the problem you want to report.
1. In Excel, click the Oracle Visual Builder tab.
2. Select Log Activity from the Advanced drop-down list to specify a directory
location and file name for the log file.
This starts the logging session.
3. Repeat the steps that lead to the issue.
4. Exit Excel completely to stop the logging session and before you access the log
file.
Note:
The next time you run Excel logging will no longer be enabled.
The log file that you generate captures information about steps during an Excel
session.
Logging Console
The Logging console displays log messages based on the actions performed. If you
encounter any issues, view the logging messages to troubleshoot and diagnose the
issues.
1. In Excel, click the Oracle Visual Builder tab.
2. Select Log Console.
The Logging Console window displays.
3. Repeat the steps that lead to the issue.
4. Review the logged messages.
5. Optionally, select Set Level and select a value from the drop-down list to specify
the log level.
By default, the log level is set to Off. The change to the log level is temporary. The
log level resets when you exit Excel.
Tip:
Try the Information log level initially.
Diagnostic Report
The diagnostic report contains information that can help resolve issues. Please
provide a diagnostic report when reporting a problem with the Oracle Visual Builder
Add-in for Excel.
17-2
Chapter 17
Diagnostic Report
17-3
18
Known Limitations
Be aware of these limitations when using the Oracle Visual Builder Add-in for Excel.
• Review View and Edit Data Using an Excel Workbook for guidelines on viewing
and editing data in an integrated Excel workbook.
• Review REST Service Support to understand limitations around data type support.
• Review Use Lists of Values in an Excel Workbook to understand limitations around
using lists of values.
• Review Custom Actions to understand custom action support.
• Workbooks created or modified with version 2.3 are generally considered to be
incompatible with prior versions of the add-in.
18-1
19
Migration
You can migrate an Excel workbook integrated with a REST service using version 1.x
of the Oracle Visual Builder Add-in for Excel to use the current version of the add-in.
Once you migrate an Excel workbook to the current version, you can no longer use it
with version 1.x.
During migration of a 1.x workbook, if you fail to log in to the REST service, migration
fails. Close the workbook without saving changes and try again later.
Before you install the current release of the add-in:
• Upload any pending changes from the Excel workbooks that use version 1.x of the
add-in
• Click Clear in the Oracle Visual Builder tab for all layouts in the Excel workbook
before you migrate
• Before you migrate an Excel workbook, make sure you are prepared to log in to
the server configured in the Excel workbook
• If you need to change the service host (the server name that the REST service
uses), be sure to do so with version 1.x of the add-in. You cannot change the
service host during migration using version 2.0 or later of the add-in
After you install version 2.x of the add-in, clear all layouts before using them with the
latest version.
Note:
The add-in's latest version continues to support the migration of 1.x
workbooks to the 2.x format. Future versions may no longer let you migrate
1.x workbooks.
19-1
20
Third Party License
The Oracle Visual Builder Add-in for Excel includes the following third-party software.
20-1
Chapter 20
20-2