Edit Semantic Model Files Using Model Administration Tool

About Editing Semantic Models Using Model Administration Tool

Administrators can use Console to upload semantic models from Oracle Analytics Server to Oracle Analytics Cloud. You can also use command line utilities on Linux to upload and download semantic model files (you can't use Model Administration Tool graphical user-interface on Linux).

Prerequisites

After a semantic model is uploaded, semantic model developers can use Model Administration Tool to edit and deploy their updates to Oracle Analytics Cloud. You can also use Model Administration Tool to create new semantic models for data sources not supported by Semantic Modeler

Oracle Analytics Server
(On Windows) A Windows 64–bit machine on which to download Oracle Analytics Client Tools and run the Model Administration Tool. See Download and Install Oracle Analytics Client Tools.

Note:
Oracle publishes new Oracle Analytics Client Tools with each Oracle Analytics Cloud update. After Oracle updates your Oracle Analytics Cloud environment, you must always download and start using the latest Oracle Analytics Client Tools.
A validated semantic model .rpd file.
Valid user credentials. A user in the Oracle Cloud identity management system associated with Oracle Analytics Cloud who has administrator permissions in Oracle Analytics Cloud (that is, a user with the BIServiceAdministrator application role).
Your Oracle Analytics Cloud uses one of these Oracle Cloud identity management systems:
- Oracle Identity Cloud Service (IDCS): If your Oracle Analytics Cloud federates with Oracle Identity Cloud Service you must connect with Oracle Identity Cloud Service user credentials.
- Oracle Cloud Infrastructure Identity and Access Management (IAM) Identity Domains: If your Oracle Analytics Cloud uses an IAM identity domain for identity management, you must connect with identity domain user credentials.
If you're not sure, ask your cloud service administrator. See About Setting Up Users and Groups.

If Oracle Analytics Cloud uses an external identity provider such as Active Directory for Single Sign-on (SSO) and you try to connect with your SSO user credentials, you see the message "Connection failed 401: Unauthorized" when you try to connect.
Check with your cloud service administrator that the required port number is open (that is, port 443 for HTTPS access to Oracle Analytics Cloud, otherwise port 80 for HTTP access ).

Typical Workflow for Using Model Administration Tool to Edit Your Semantic Model

(On Windows) Upload your semantic model. See Upload Semantic Models from a .rpd File Using Console.
(On Windows) Edit your semantic model. See Edit a Semantic Model in the Cloud.
(On Windows) Copy analyses and dashboards built in Oracle Analytics Server to Oracle Analytics Cloud. See Uploading Content from a Catalog Archive in Visualizing Data and Building Reports in Oracle Analytics Cloud.
(On Linux) Use the command line tools runcat.sh and datamodel.sh to manage semantic models (you can't use Model Administration Tool graphical user-interface on Linux). See Using Oracle Analytics Client Tools on Linux.

Download and Install Oracle Analytics Client Tools

Download and install Oracle Analytics Client Tools to enable remote connections from reporting dashboards and analyses. In addition, you might use Model Administration Tool (one of the client tools available for Microsoft Windows) to edit a semantic model (.rpd file) that isn't supported by Semantic Modeler.

You install Oracle Analytics Client Tools on Windows or Linux platforms.

On Windows, the software pack installs the graphical user-interface version of Model Administration Tool , as well as command line utilities such as runcat.cmd (for catalog management).
On Linux, the software pack installs runcat.sh and datamodel.sh command line utilities.

Note:

Oracle updates Oracle Analytics Client Tools with each Oracle Analytics Cloud update. Make sure that you're using the latest update of Oracle Analytics Client Tools.

Navigate to the download page for Oracle Analytics Client Tools.
Click the latest Oracle Analytics Client Tools <Month Year> Update link to display the Oracle Software Delivery Cloud page.
Click the Platforms down arrow, click All, then click outside of the drop-down list or press Enter.
In the Software column of the table, select the download pack for the platform you want.
- For Windows, select Oracle Analytics Client May2023-Win for (Microsoft Windows x64 (64-bit)), <Size in MB>.
- For Linux, select Oracle Analytics Client May2023-Linux for (Linux x86-64), <Size in MB>.
Make sure that other components are de-selected (for example, Data Gateway and Power BI Connector).
Accept the Oracle Cloud Service License Agreement.
Click Download to start Oracle Download Manager, and follow the on-screen instructions.
When the download is complete, click Open Destination.
Extract and run the Oracle installer from the downloaded ZIP file.
For example, extract and run the installer file oac_client-<update ID>-win64.exe, and follow the on-screen instructions.

To start the tools on Windows, go to your Windows Start menu, click Oracle Analytics Client Tools, and then select the name of the tool you want to use. For example, to edit your semantic model, click Model Administration Tool.

On Linux, use the runcat.sh and datamodel.sh command line utilities. See Using Oracle Analytics Client Tools on Linux.

Connect to a Semantic Model in the Cloud

You must enter connection details for Oracle Analytics Cloud before you open, publish, or upload a semantic model to Oracle Analytics Cloud using Model Administration Tool.

Open Model Administration Tool.

Go to your Windows Start menu, click Oracle Analytics Client Tools, and then select Model Administration Tool.
In Model Administration Tool, select how you want to connect to Oracle Analytics Cloud.

For example, click File, then Cloud, then either Open, Publish, or Upload.
Enter connection information for Oracle Analytics Cloud.
1. In User, specify a user in the Oracle Cloud identity management system associated with Oracle Analytics Cloud who has administrator permissions in Oracle Analytics Cloud (that is, a user with the BIServiceAdministrator application role).
  
  If your Oracle Analytics Cloud federates with an external identity management system, you probably sign in to Oracle Analytics Cloud with your single sign-on credentials. You can't use your single sign-on credentials to connect to Oracle Analytics Cloud from Model Administration Tool, you must use Oracle Cloud identity management user credentials. See Prerequisites.
2. In Password, enter the password for the specified User.
3. In Cloud, enter bootstrap.
4. In Host name, enter your Oracle Analytics Cloud URL, excluding https:// and /ui/dv.
  
  For example, if your Oracle Analytics Cloud URL is https://oac123456-oacppacm12345.uscom-central-1.oraclecloud.com/ui/dv, enter oac123456-oacppacm12345.uscom-central-1.oraclecloud.com.
  You can obtain the Oracle Analytics Cloud URL from Oracle Cloud Infrastructure Console. Navigate to your Oracle Analytics Cloud instance, and then copy the value in the URL field. For earlier Oracle Analytics Cloud products, click Manage this instance, and copy the link address for Oracle Analytics Cloud URL.
5. In Port Number, enter 443.
6. Select SSL.
  
  For Trust Store, click Browse, and select the default JDK key store that's bundled with JRE:
  
  <OAC client home>\oracle_common\jdk\jre\lib\security\cacerts
  
  For Password, specify the passphrase for the trust store (JKS) that contains the CA certificate that you trust and has been used to sign the Oracle Analytics Cloud certificate. The Oracle Analytics Cloud certificate is signed by a well-known CA, so you can use a regular Java cacerts (the default JKS trust store that trusts well-known CAs).
7. If you deployed Model Administration Tool on a machine in a proxy-enabled network, select Proxy.
  
  Ask your network administrator for the proxy server URL and Port number.

Expect the initial connection to take between 3–15 minutes, depending on the size of your semantic model.

Edit a Semantic Model in the Cloud

Use Model Administration Tool to edit a semantic model that you previously uploaded to Oracle Analytics Cloud.

Open Model Administration Tool.

Go to your Windows Start menu, click Oracle Analytics Client Tools, and then select Model Administration Tool.
In Model Administration Tool, click the File menu, select Open, and then In the Cloud.
Enter connection information for Oracle Analytics Cloud.
Update your model.
1. Make changes to the model, as required.
2. To validate your changes, click Tools, Show Consistency Checker, and then click Check All Objects.
3. To save the changes locally, click File, and then click Save.
To upload your changes to Oracle Analytics Cloud, click File, Cloud, and then click Publish.

To refresh or discard your changes, use the File submenu:

Refresh – Use this option to refresh your semantic model with the latest updates. If another developer has modified the semantic model, then you’re prompted to initiate a merge.
Discard – Use this option to cancel any changes that you’ve made to the semantic model in the current session.

Upload a Semantic Model to the Cloud

You can use Model Administration Tool to upload a semantic model .rpd file to Oracle Analytics Cloud.

Note:

Administrators can also use the Console to upload semantic model .rpd files. See Upload Semantic Models from a .rpd File Using Console.

In Model Administration Tool, open your semantic model .rpd file.
From the File menu, click Cloud, then click Upload.
Enter connection information for Oracle Analytics Cloud.

To make further changes, you simply connect to Oracle Analytics Cloud and edit the semantic model directly. You don’t have to edit the semantic model .rpd file and upload again.

To refresh or discard your changes, use the File submenu:

Refresh – Use this option to refresh your semantic model with the latest updates. If another developer has modified the semantic model, then you’re prompted to initiate a merge.
Discard – Use this option to cancel any changes that you’ve made to the semantic model in the current session.

Connect to a Data Source Using a Console Connection

Administrators can define database connections for semantic models using the Console in Oracle Analytics Cloud. This includes databases such as Oracle Database Cloud Service, Oracle Autonomous Data Warehouse, and Oracle Autonomous Transaction Processing.

If you want to re-use these database connections in Model Administration Tool, you don’t have to re-enter the connection details. Instead, you refer to the database connections “by name” in the Connection Pool dialog.

If you haven't already done so, create the database connection in Console and note down its name. For example, MyCloudSalesDB.

In Model Administration Tool, navigate to the Physical Layer pane, and open the Connection Pool dialog.
In Name, enter a name for the data source.
Select the Use Console Connection check box.
In Connection Name, enter the name of the database connection exactly as defined in Console (case-sensitive). For example, MyCloudSalesDB.

Note:

Ignore the other options on this dialog, for example Data source name, Shared Logon User Name and Password.

Connect to a Data Source Using a Data Connection

In Oracle Analytics Cloud, users with DV Content Author access can set up connections to a wide range of data sources, and make these data connections available to business modelers building semantic models in Model Administration Tool by setting a connection option called System Connection.

For a list of data sources with the system connection option, see Supported Data Sources.

To use a data connection in Model Administration Tool, you enter its Object ID in the Connection Pool dialog. You don’t have to re-enter the connection details.

In Oracle Analytics Cloud, obtain the Object ID of the connection you want to use in Model Administration Tool.
1. If you haven’t done so already, create a connection to your data source and select the System Connection check box.
  
  See Database Connection Options.
2. On the Home page, click Navigator and then click Connections.
3. In the Connections page, locate the connection, click Actions, and then click Inspect.
4. Click Copy to copy the connection's Object ID.
In Model Administration Tool, navigate to the Physical pane, and open the Connection Pool dialog.
In Name, enter a name for the data source.
Select the Use Data Connection check box.
Enter the Object ID of the data connection you want to use.

Object IDs use the format: 'owner'.'connection name'

For example: 'oac.user@example.com'.'myoracledatabase'

Note:

Ignore the other options on this dialog, for example Data source name, Shared Logon User Name and Password.

Connect a Semantic Model to a Spark Data Source

If you want to connect your semantic model to a Spark data source you must specify the Spark connections details in the .rpd file.

In Model Administration Tool, open your .rpd file, navigate to the Physical pane, right-click, and select New Database.
Enter a name for the database connection, and set the Database type to ODBC Advanced.
Click Connection Pool, and add a connection pool.
Enter a name for the connection pool, and set the Call interface to ODBC 3.5.
In the Data Source Name (DSN) field , add the following:

Substitute the HOST and PORT values with the IP address of your Hive Thrift host and the port value:

DRIVER=Oracle 8.0 Apache Hive Wire Protocol;HOST=<hive_host_ip_address>;PORT=<binaryprotocol port for hive>
Add the authentication details and save the connection pool.
Import the physical layer object and complete the semantic model before uploading the .rpd file to Oracle Analytics.

Working with Model Administration Tool

Use these options to manage and publish a semantic model using Model Administration Tool. Model Administration Tool runs on Windows (you can't use Model Administration Tool graphical user-interface on Linux).

When you connect to Oracle Analytics Cloud in Model Administration Tool, you must provide user credentials for a user in the Oracle Cloud identity management system associated with Oracle Analytics Cloud. You won't be able to sign in as a Single Sign-on user from a federated external identity management system. See Prerequisites.

Menu option	Use it to:
File, then Cloud, then Open	Open a semantic model you uploaded to Oracle Analytics Cloud so you can edit it.
File, then Cloud, then Publish	Publish changes that you made to the data model. Users see the changes the next time they sign-in to Oracle Analytics Cloud.

Using Oracle Analytics Client Tools on Linux

Administrators can manage semantic model files (RPD files) using command line utilities installed with Oracle Analytics Client Tools on Linux. (You can't use Model Administration Tool graphical user-interface on Linux.)

Once you install Oracle Analytics Client Tools Utilities on Linux, access these utilities in <client_install_folder>/bi/bitools/bin.

runcat.sh - Use runcat.sh to manage Oracle Analytics catalogs. This utility supports on-line operations of the runcat utility (you can't use runcat.sh to extract a web catalog from a BAR file).
To display online help, use ./runcat.sh -help.
datamodel.sh - Use datamodel.sh to run these commands: listconnectionpool, updateconnectionpool, downloadrpd, uploadrpd.
To display online help, use ./datamodel.sh -h.

Note: You need a local Oracle Identity Cloud Service user to use runcat.sh and datamodel.sh commands (you can't use a federated single-signon user).

Troubleshoot Issues with Model Administration Tool (Oracle Analytics Client Tools)

Here’s some tips on how to troubleshoot issues when you try to connect to Oracle Analytics Cloud from Model Administration Tool. Model Administration Tool is available with the Oracle Analytics Client Tools download.

Access these log files on your client machine:

BI_client_domain home\domains\bi\servers\obis1\logs\user_name_NQSAdminTool.log
BI_client_domain_home\domains\bi\clients\datamodel\logs\datamodel.log

This table describes some common connection issues and how you can resolve them.

Common Connection Issues	Cause and Resolution
`401: Unauthorized OR Authentication failure`	The login credentials are invalid. Make sure the user account exists. Make sure you spelled the user name and password correctly. Make sure the password doesn't contain an exclamation mark (!) Make sure the user has the BI Service Administrator application role.
`Error initializing TLS secure connection or Proxy exception: java.security.NoSuchAlgorithmException: Error constructing implementation (algorithm: Default, provider: SunJSSE, class: sun.security.ssl.SSLContextImpl$DefaultSSLContext)` OR `Error initializing TLS secure connection or Proxy exception: Remote host closed connection during handshake`	This issue has multiple causes: The connection points to a file which is not trust/key store. The connection points to a trust/key store that doesn’t contain a certificate that can be used to verify the server certificate. The trust store password is incorrect. Use the default JDK key store located in: `BI_client_domain_home\oracle_common\jdk\jre\lib\security\cacerts`.
`Connection failed, the server processes may be down, the host name, port number, service instance, or protocol (http/https) may be incorrect`	This issue has multiple causes: Make sure you’ve specified the correct host name and port number. See Connect to a Semantic Model in the Cloud. If the `datamodel.log` file reports `Connection timed out`, check whether the machine where you installed Oracle Analytics Client Tools is in a proxy-enabled network. If it is, ask your network administrator for the proxy server and port, and specify these when you connect to your semantic model. If you can’t diagnose a connection issue using the client side log files and Oracle Analytics Cloud is deployed in a customer-managed environment, check server side log files `bi-lcm-rest.log.0` and `bi_server1.out`. For example, if the database user doesn’t have the BI Service Administrator application role, the `bi_server1.out`. file shows an error similar to: `oracle.bi.restkit.security.auth.RequiredGroupAuthoriser> <BEA-000000> <Failed authorisation for user: weblogic>`
I can't use Model Administration Tool in SSL mode	If the default security certificates don't work, import the server security certificates. For example, on the machine where you downloaded and installed Oracle Analytics Client Tools, you might use the Key and Certificate Management Tool (keytool) to execute these commands: `C:\Oracle\Middleware\oracle_common\jdk\jre\bin\keytool.exe -importcert -alias oacserver -file C:\Oracle\Middleware\oracle_common\jdk\jre\lib\security\server.crt -keystore C:\Oracle\Middleware\oracle_common\jdk\jre\lib\security\cacerts -storepass password`