1. Guide
  2. Administering Oracle Spatial Studio

2 Administering Oracle Spatial Studio

Administering Oracle Spatial Studio involves certain actions that must be performed before non-administrative users can work with spatial data. If you are an administrative user of Spatial Studio, you must:

  • Download the Oracle Spatial Studio application from Oracle Technical Resources (formerly called Oracle Technology Network) and install it.
  • Set up a database schema to be the Spatial Studio schema, that is, to hold metadata for Spatial Studio.

    The Spatial Studio schema can be either an existing database schema in which Spatial Studio metadata will be added, or a newly created schema that will be used only for Spatial Studio.

  • Configure the newly installed Spatial Studio application.

    When the installation and configuration actions are completed, users can connect to the database, start Spatial Studio, and use its features.

Note:

The Spatial Studio application can be downloaded in either of the following formats:
  • Quick Start: A ready-to-run standalone application packaged in a zip file containing what you need to launch the Spatial Studio web application on your desktop. (You will still need to have JDK 8 64-bit, update 181 or later installed on your desktop, because no Java kit is bundled with this kit.)

    Quick Start is well suited for personal and development use.

  • A WLS-optimized EAR (Enterprise Application aRchive) file. This .ear file can be deployed to an existing WebLogic Server domain administered by an organization's WLS or middleware administrator.

    This is the recommended installation and deployment method if you intend for multiple end users to access the same Spatial Studio web application.

A given person or database user can be both an administrative user and a non-administrative user, or can be only an administrative user or a non-administrative user.

2.1 Prerequisites and Recommendations for Spatial Studio

This section describes the prerequisites and recommendations that apply for using Spatial Studio.

Oracle Spatial must be installed on the database to which any users will connect to perform actions with Spatial Studio. (It is not sufficient to have only Oracle Locator installed.)

The following additional requirements and recommendations apply:
  • Java versions: Java 8 (64-bit, update 181 or later); or JDK 11 (64-bit).
  • Oracle Database 19c or later. This applies both to the Spatial Studio metadata schema and to all database connections that will be used by Spatial Studio users.

    Note:

    Oracle Spatial Studio Releases are backward compatible with supported Oracle Database versions.
  • Oracle WebLogic Server 12.2.1.3 or later.
  • All the privileges listed in section Setting Up the Spatial Studio Metadata Schema are required for each database user that works with Spatial Studio.
  • Quota on the default tablespace for each database user that works with Spatial Studio. ALTER USER statement format: ALTER USER [username] QUOTA [quota value] ON [default tablespace name];

    For example, for a user named test_user with default tablespace users: 

    ALTER USER test_user QUOTA unlimited ON users;
  • The default tablespace for the Spatial Studio repository schema should not use compression.

Parent topic: Administering Oracle Spatial Studio

2.2 Downloading and Installing Spatial Studio

Spatial Studio must be downloaded and installed before anyone can use it to perform interesting work on spatial data.

Go to https://www.oracle.com/database/technologies/spatial-studio/get-started.html to see more information for downloading and installing Spatial Studio.

Parent topic: Administering Oracle Spatial Studio

2.2.1 Installing and Configuring the Spatial Studio Quick Start

Quick Start is an easy method for getting started, and is well suited for personal and development use.

The Quick Start is packaged in a single zip that contains everything you need to start using Spatial Studio, except for Java (64-bit, update 181 or later) and your own database schemas.

Before installing the Quick Start, ensure that you meet the following prerequisite requirements:

  • You must have Java installed on your system and the JAVA_HOME environment variable is pointing to the full JDK installation of Java SE Development Kit. Note that the Quick start installation requires Java 8 (64-bit, update 181 or later) or JDK 11 (64-bit).
  • Ports 8080 and 4040 on your system are not being used by any other (web) applications. Port 8080 is used with the http:// protocol, while port 4040 is for the https:// protocol. Although you can direct Spatial Studio to use different ports, 8080 and 4040 are the default.

    Note that by default Spatial Studio allows access using https only.

You can perform the following steps to install and configure the Spatial Studio Quick Start:

  1. Download the Quick Start zip archive OracleSpatialStudio_qs.zip.
  2. Unzip (extract) the OracleSpatialStudio_qs.zip file.
    This results in the Oracle_Spatial_Studio directory.
  3. Navigate to the Oracle_Spatial_Studio directory from a command window (Windows) or terminal (Linux or Mac).
    This directory contains several .bat or .sh files.
  4. Start the Spatial Studio application by running start.sh or start.bat.
    On Linux or Mac you may need to ensure that the .sh files are executable by first running the command: chmod u+x *.sh
  5. Launch the Spatial Studio web application in your browser using the URL: https://localhost:4040/spatialstudio

    You can login using the default admin user login credentials - admin/welcome1. However, it is strongly recommended that you immediately change the password. See the README file in the Quick Start on how to change the (encrypted) password for the admin user.

    Also, note the following:
    • The default port is 4040. However, you can change the port by editing the conf/server.json file in the Oracle_Spatial_Studio directory. You must restart the application after you make any change to this file. (The same applies if you change the HTTP port value from the default 8080.)
    • The Quick Start provides the following predefined web user login accounts:
      • admin: Administrator user account
      • daustin and bruce: Two regular user accounts

      These predefined users and their login passwords are defined in the conf/jetty-realm.properties configuration file. The passwords are all stored in encrypted form. Before you start the application for the first time, it is strongly recommended that you change the password of the default administrator user admin. See the README file in the Quick Start on how to change the (encrypted) password for the admin user and other regular Spatial Studio users.

      Also, all other passwords, such as those used to log into the Spatial Studio metadata schema or for any user-created connections to database schemas, are strongly encrypted everywhere.

    • The README file also contains information about starting and stopping the web application. To stop the application, the preferred approach is to start a second terminal or command window, then go to the same Oracle_Spatial_Studio folder and run the stop.bat or stop.sh script.

Parent topic: Downloading and Installing Spatial Studio

2.2.2 Installing Spatial Studio on Oracle WebLogic Server

Spatial Studio can be deployed to a WebLogic Server domain, the recommended approach if multiple end users will access the same Spatial Studio application.

Note:

A WebLogic Server license is required in order to host Spatial Studio in WebLogic Server for multiple end users.

The general approach for deploying Spatial Studio to WebLogic Server is no different from deploying any other Java EE EAR application. The easiest way to do so is by using the WebLogic Server’s Admin console with the following steps. Note that in all or most steps you can accept the default values provided by the WLS Installation Application Wizard.

  1. Download the Studio EAR archive from Oracle Technical Resources or eDelivery, and save it to your local system.
  2. Log into the target WLS domain’s Admin console.
  3. Click the Deployments link on the left side.
  4. Click Install button under the Deployments section, as shown in the following figure (note that the exact contents may be different for your instance of WLS).

    Figure 2-1 WLS Admin Console for Deploying Spatial Studio

    Description of Figure 2-1 follows
    Description of "Figure 2-1 WLS Admin Console for Deploying Spatial Studio"
  5. On the next page, select the Spatial Studio EAR file downloaded previously, and install it as an application (not as a library).
  6. Click through the remaining steps, including selecting the proper target server. You should accept the default options in all cases unless you know exactly what you are doing. Finally, click Save to complete the deployment.
  7. If your WLS runs in production mode, you may need to activate the changes to ensure the deployment is activated.
  8. Make sure the newly deployed Spatial Studio application is marked Active; otherwise, you may need to explicitly start it from the WLS administrative console.
  9. Access the Studio application using your managed server’s URL with the /spatialstudio context root. For example: http://mycompany.com:7002/spatialstudio

Parent topic: Downloading and Installing Spatial Studio

2.2.2.1 Preventing a Spatial Studio Admin User from General WLS Administration

If you want to prevent a Spatial Studio administrative user from performing other general WebLogic Server administrative operations, follow the instructions in this topic.

The Spatial Studio application by default allows all WebLogic managed admin users (those who are in WebLogic’s Administrators group) to log into the Spatial Studio application and assume Admin role inside the Spatial Studio application as well.

However, in some scenarios, your organization may not want to provide the WebLogic Server admin account information to the user(s) that will be administering only the Spatial Studio application. In such cases, the WLS system administrator can create a new WLS group with the id value of “SGTech_SystemAdmin” in the default WLS security realm. Then, either create a new user or assign an existing non-WLS-admin user to this group. From then on, this user will assume the admin role of the Spatial Studio whenever logged in, but will not be able to administrate the WLS server in general.

Also, note the following:

  • All WLS managed users will be able to log into Spatial Studio by default, but they will be limited to accessing only their own Spatial Studio objects such as connections, datasets, and projects.
  • Administrative users of Spatial Studio will have full access to every Spatial Studio object created by everyone.
  • When using WebLogic's default embedded LDAP security realm as identity provider, if the user name and the assigned application role name differ only by casing (for example, admin and Admin respectively), then it is recommended that you adjust both the names to lowercase. This is to avoid case sensitivity issues in Spatial Studio between user, group, and security policies.

2.2.3 Installing Spatial Studio on Apache Tomcat

Starting with Oracle Spatial Studio patch release 23.1.1, you can deploy and run the Spatial Studio web application on Apache Tomcat version 9.

The following are the general steps for deploying and running Spatial Studio on Tomcat:
  1. Download and install the latest Apache Tomcat version 9.

    See the Apache Tomcat Documentation for setting up Tomcat.

  2. Unzip the Tomcat zip file and configure it as required, such as removing all default web applications found in the <TOMCAT_HOME>/webapps directory.
  3. Download the Spatial Studio Tomcat specific WAR archive from Oracle Software Delivery Cloud.
  4. Copy the downloaded WAR archive into the <TOMCAT_HOME>/webapps/ directory.
  5. Ensure to rename the WAR file to just spatialstudio.war.

    Note that there is no version or build string in the file name. See About the Spatial Studio WAR Archive for Tomcat for more information.

  6. Configure Tomcat users and roles.

    Ensure to configure the ADMIN user for Spatial Studio. See Configuring Tomcat Users for Spatial Studio for more information.

  7. Start the Tomcat server using the startup script in the <TOMCAT_HOME>/bin directory.

    Note that you may need to wait a few seconds for Tomcat and Spatial Studio to fully initialize before attempting to access the Spatial Studio web application.

  8. Launch Spatial Studio in your browser by opening the URL - http://localhost:8080/spatialstudio.

    You can then log in using one of the users you defined on step-6.

    Note that the Spatial Studio access URL uses the default host name and port. If you change the default Tomcat network and port configurations, then you need to adjust the URL accordingly.

    If for some reason you cannot access the URL, then you can always check the following log files:

    • Tomcat’s server logs in the <TOMCAT_HOME>/logs directory.
    • Spatial Studio’s own log files in the <USER_HOME>/.sgtech/logs directory, where <USER_HOME> is the home directory of the operating system user.

Parent topic: Downloading and Installing Spatial Studio

2.2.3.1 About the Spatial Studio WAR Archive for Tomcat

You must download the spatialstudio_tomcat.war archive for running Spatial Studio on Tomcat.

This archive file bundles all the required dependencies that enables it to run on a freshly downloaded and installed Tomcat instance.

It is important to note the following:

  • You must rename the spatialstudio_tomcat.war file to spatialstudio.war when it is placed in the Tomcat’s webapps directory. This is because Tomcat uses the file name as the web application’s context root, and for Spatial Studio it is typically /spatialstudio.
  • If you have an existing Tomcat installation with other web applications running on it or different versions of the dependency libraries are already installed, then there might be issues running Spatial Studio due to library and version conflicts. In such cases, you can raise a service request with My Oracle Support in order to have the issues resolved.
2.2.3.2 Configuring Tomcat Users for Spatial Studio

In order to run Spatial Studio on Tomcat, you need to configure at least one Tomcat user who can act as the administrator for Spatial Studio.

Note that when you access the Spatial Studio web application, the username and password that you enter in the login page are passed to Tomcat for authentication. Once the user is authenticated, Spatial Studio inspects the result principal. If the principal has a role named SGTech_SystemAdmin, then the logged in user will be considered an admin user for Spatial Studio.

If your Tomcat instance has already been configured to provide authentication using an external identity provider, then ensure one or some of the users provided by the external identity provider are assigned the SGTech_SystemAdmin role so they can administrate Spatial Studio.

If your Tomcat installation relies on its simple built-in user management mechanism, then you will likely be adding the role and user to tomcat-user.xml configuration file, which is found in the <TOMCAT_HOME>/conf directory.

The following simple example defines two users and two roles, with one being SGTech_SystemAdmin in tomcat-user.xml configuration file: 

<role rolename=”role1”/>
<role rolename="SGTech_SystemAdmin"/>
<user username="admin" password="Welcome1" roles="manager-gui, manager-script, SGTech_SystemAdmin"/>
<user username="scott" password="Welcome1" role="role1"/>

Once the roles are defined, then you can log into Spatial Studio using either the user name scott or admin. Since the admin user has the SGTech_SystemAdmin role, the user will be able to administrate Spatial Studio once logged in, whereas scott user will just be a regular Spatial Studio user.

2.2.4 Installing Spatial Studio from Oracle Cloud Marketplace

You can provision Spatial Studio to Oracle Cloud from Oracle Cloud Marketplace.

See Deploy Spatial Studio from Cloud Marketplace for more information on deploying Spatial Studio from Cloud Marketplace.

Parent topic: Downloading and Installing Spatial Studio

2.3 Upgrading Spatial Studio

You can upgrade your existing Oracle Spatial Studio deployment to a 23.1 version.

Note:

If you are running a Spatial Studio version earlier than 22.3.0, then you must first download and successfully log into Spatial Studio 22.3.0. This is because a new version control mechanism is introduced for the metadata schema in 23.1.0 and Spatial Studio expects any existing metadata schema to already be at the version of Spatial Studio 22.3.0. Therefore, you must log into the 22.3.0 web application at least once, before you can download and run the latest 23.1.0 version. Otherwise, Spatial Studio version 23.1.0 will log the following SEVERE error message and abort the startup process.

!!! Spatial Studio ver. 22.3.0 must be run at least once against your repository schema before upgrading to this version !!!

Tip:

To check the version of your current Spatial studio installation, log into the web application, then click the About menu item from the Avatar drop-down menu. The version number gets displayed.

If you are already using Spatial Studio 22.3.0, then the following sections explain the steps for upgrading Spatial Studio in an existing host (in-place upgrade) or when deploying to a new host (out-of-place upgrade).

Parent topic: Administering Oracle Spatial Studio

2.3.1 Prerequisite Tasks for Upgrading Spatial Studio

Perform the following prerequisite steps to prepare for Spatial Studio upgrade:
  1. Stop all running Spatial Studio instances.
  2. Take a backup of the following artifacts:
    • Repository metadata schema tables such as:
      • SGTECH_META_VERSION
      • SGTECH_OBJECT
      • SGTECH_SYS_TYPE
      • SGTECH_TASK_BROKER
      • SGTECH_TASK_QUEUE

      You can export the preceding files to a dump file using the data pump utilities. For example, the following shows a data pump export command, assuming the metadata schema name is studio_metadata with the database service name orclpdb: 

      expdp studio_metadata/<password>@orclpdb directory=dumpdir
      dumpfile=spatial_studio_metadata_backup.dmp
      tables=SGTECH_META_VERSION,SGTECH_OBJECT,SGTECH_SYS_TYPE,SGTECH_TASK_BROKER,SGTECH_TASK_QUEUE
    • Working directory (generally, ~/.sgtech)
    • sgtech_config.json configuration file which is generally located in the working directory
  3. Download the Spatial Studio 23.1.0 version and upload it to the host to be upgraded

Parent topic: Upgrading Spatial Studio

2.3.2 In-Place Upgrade

Perform the following step for an in-place Spatial Studio upgrade:
  1. Redeploy the Spatial Studio 23.1.0 application.
    • For Quick Start: Rename the old Quick Start folder. Expand the newly downloaded ZIP file and run start.sh (Linux) or start.cmd (Windows).
    • For EAR deployment: Follow the instructions of your application server to delete the old deployment version. Then, deploy the new version and start the application.

Parent topic: Upgrading Spatial Studio

2.3.3 Out-of-Place Upgrade

Perform the following steps for an out-of-place Spatial Studio upgrade:
  1. Create the working directory in the new host.
    mkdir ~/.sgtech
  2. Copy the sgtech_config.json configuration file from the working directory of the old host to the new host.
    cp old/sgtech_config.json ~/.sgtech

    If the master_seed entry in the configuration file is lost, all connection passwords will be broken. If this occurs, proceed with the upgrade, then log into the upgraded Spatial Studio instance, edit each connection by re-entering the password, and reconnect.

  3. Deploy the Spatial Studio application.
    • For Quick Start: Simply expand the newly downloaded ZIP file and run start.sh (Linux) or start.cmd (Windows).
    • For EAR deployment: Follow the instructions of your application server to deploy the new version and start the application.

    When the application is started, the repository database schema will automatically be upgraded.

Parent topic: Upgrading Spatial Studio

2.4 Setting Up the Spatial Studio Metadata Schema

You must set up a database schema to be the Spatial Studio schema, which will hold metadata used by the Spatial Studio application.

The Spatial Studio schema can be either an existing database schema in which Spatial Studio metadata will be added, or a newly created schema that will be used only for Spatial Studio. The recommended practice is to create a new database user that will be used only by Spatial Studio. The database user for the Spatial Studio schema must have the following privileges:

  • CONNECT
  • CREATE PROCEDURE
  • CREATE SEQUENCE
  • CREATE SESSION
  • CREATE SYNONYM
  • CREATE TABLE
  • CREATE TRIGGER
  • CREATE TYPE
  • CREATE VIEW

Note:

The CREATE TRIGGER privilege is required only if you intend to store and display GeoRaster data in the schema.

For example, when connected as a user with DBA privileges:

SQL> create user SPATIAL_STUDIO identified by <password>;
SQL> grant connect, create procedure, create sequence, create session, create synonym, create table, create trigger, create type, create view to SPATIAL_STUDIO;

When the Spatial Studio application starts running for the first time, it will generate a configuration file in a folder named .sgtech under the current user’s operating system home folder. The configuration file is named sgtech_config.json. This is where Spatial Studio application will be obtaining and storing the connection details in its metadata schema.

After the connection to the metadata schema is established, the Spatial Studio application will automatically check if the required tables and other database objects are already present, and if their versions are up to date with the latest Spatial Studio application software. If these tables are not found, or if the tables require migration, the Spatial Studio application will run the necessary SQL scripts to create or migrate them, all without any intervention from the user.

The Spatial Studio schema will contain the following tables and views:

  • SGTECH_OBJECT: stores all the domain objects for Spatial Studio.
  • SGTECH_SYS_TYPE: defines all the known types of domain objects of Spatial Studio.
  • SGTECH_SYS_JSON_SCHEMA: stores JSON data schema.
  • SGTECH_TASK_QUEUE: stores long-running jobs of Spatial Studio.
  • SGTECH_TASK_BROKER: stores job brokers for Spatial Studio.

Note:

Do not add, delete, or edit any of the Spatial Studio tables or views or the data within them. They are automatically maintained by Spatial Studio, and should not be modified by users unless directed by Oracle Support.

Managing Metadata Schema when Running Multiple Instances of Spatial Studio

Spatial Studio prevents you from running multiple application instances each having its own sgtech_config.json file from using the same metadata schema. In case you want to run another instance, it is recommended that you copy the sgtech_config.json configuration file linked to the initial instance to the system where you want to start the new instance.

Otherwise, any attempt to connect to the same metadata schema from an instance running on a different system is prevented by Spatial Studio with the following warning:

The selected repository is already registered to another instance of Spatial Studio. Check the system logs for more details.

In such a scenario, see Recovery from Lost Master Key to resolve the issue.

Parent topic: Administering Oracle Spatial Studio

2.5 Connection Requirements for Database Users of Spatial Studio

This section describes the connection requirements for database users to work on Spatial Studio.

Each individual user must connect as a database user who is authorized to run Spatial Studio. A Spatial Studio administrator can enable access for the database users.

You can create new database users specifically for Spatial Studio access, or you can modify existing database users to enable Spatial Studio access, or you can do a combination of these approaches.

All database users must have a minimum set of privileges. In addition, each database user that works with Spatial Studio must have quota on its default tablespace. The privilege and quota requirements are explained in Prerequisites and Recommendations for Spatial Studio.

Parent topic: Administering Oracle Spatial Studio

2.6 Changing the Configuration Using the sgtech_config.json File

This section describes the configuration of important properties in sgtech_config.json file.

By default, Spatial Studio will create (if it does not already exist) and use a JSON file named sgtech_config.json for most of its essential configuration information.

This file is typically found in the operating system user’s home directory, in a subfolder named .sgtech. This is true whether you deployed the application EAR to a WebLogic domain or you are just using the Quick Start.

Note:

You must safeguard the sgtech_config.json file and ensure it has a backup on a regular basis. If this file is lost, you will lose the master key that Spatial Studio used to encrypt sensitive information, such as the database schema password for your data connections. This means that next time you start up Spatial Studio, it will no longer be able to decrypt such information, and none of your data connections will be usable, as well as all the datasets in them. In such a scenario, refer to Recovery from Lost Master Key for more information.

The following topics describe some important properties in the configuration file that a system administrator should be aware of:

Parent topic: Administering Oracle Spatial Studio

2.6.1 Allow HTTPS-ONLY Access

One of the top level properties in the sgtech_config.json config file is https_only. When this value is set to true (the default), Oracle Spatial Studio will actively monitor all incoming requests and only allow requests that were made using SSL. Normal http:// requests will be denied.

Thus, if you tried to access the Spatial Studio application using an http:// URL such as http://localhost:8080/spatialstudio, and if the value of https_only is set to true, then you will not be able to log in. In fact, you will not even see the login page itself, because none of the page resources will be accessible by your browser. Similarly, all RESTful requests will be blocked unless accessed using HTTPS.

If your environment (such as WebLogic Server) supports only http access, then you can change the value of https_only to false, and make sure to restart the Spatial Studio application or the JavaEE container where Spatial Studio is deployed.

Parent topic: Changing the Configuration Using the sgtech_config.json File

2.6.2 Connecting to the Spatial Studio Metadata Schema

Spatial Studio must have access to a set of metadata tables, such as SGTECH_OBJECT. These tables are collectively considered the repository of the Spatial Studio application. The database schema that hosts these tables is considered the metadata schema or repository schema of Spatial Studio.

Spatial Studio must be able to establish a connection to this metadata schema as the first step during startup, when the connection details are found in the sgtech_config.json file in the metadata_schema section.

In an emergency situation, you can also manually edit this section to change or correct the connection details. However, be careful whenever editing this file, because any syntax error can cause Spatial Studio to stop working or fail to restart.

When you manually enter the repository schema connection details in the sgtech_config.json file (in the metadata_schema section), you must first specify whether CONTAINER or SPATAL_STUDIO is managing the physical JDBC connections: 

"metadata_schema" : {
    "connection_manager": "CONTAINER"
}

Or

"metadata_schema" : {
    "connection_manager": "SPATIAL_STUDIO"
}

When connection_manager is set to CONTAINER, it means the JDBC connections to the Spatial Studio’s repository schema are managed through a Java EE data source already created in Jetty (for Quick Start) or WebLogic Server. For example, if there is a data source named jdbc/studioMetadata in the WLS domain, and if you want Studio to connect to the target schema using this data source, the relevant section in sgtech_config.json should look like this: 

"metadata_schema" {
"connection_manager" : "CONTAINER",
"container_managed":{
        "jndi_datasource_name" : "jdbc/studioMetadata"
}
}

Note:

As of Spatial Studio Release 19.2, you cannot enter the container-managed connection details in the Spatial Studio application, so manually editing sgtech_config.json file is the only supported approach.

However, if you want Spatial Studio to manage the physical connections to its metadata schema, set connection_manager to SPATIAL_STUDIO, and supply the full set of JDBC connection details, which vary depending on whether the schema resides in an Oracle Autonomous database (which requires a database Wallet for establishing connections), or a regular database on-premises. You can check the inline comments inside the sgtech_config.json file for more details, but it is best if you simply log onto Spatial Studio as an admin user and then interactively supply the connection details for the repository schema. Such details will then be automatically saved in sgtech_config.json after Spatial Studio verifies the connection.

Parent topic: Changing the Configuration Using the sgtech_config.json File

2.6.3 Caching Metadata Objects

During run time as users create connections, datasets, and projects, Spatial Studio is creating, modifying, and storing a large amount of metadata (sometimes called Spatial Studio’s "domain objects"), such as the definition of a dataset and all of its columns, or the definition of a project including the full layout of all of its visualizations.

All the metadata objects are permanently stored in the metadata table SGTECH_OBJECT, but if the database must be accessed frequently (such as every time you open a project or view the properties of a dataset), performance may suffer. If this occurs, the solution is to cache frequently accessed copies of such metadata objects in memory.

The cache section of the sgtech_config.json file lets you specify whether to enable such an in-memory cache of metadata objects. If the cache is enabled, then you can further specify how many such objects can be cached and for how long. A general rule is that max_size (the maximum number of metadata objects to be cached) should be no less than 1000, but probably should not exceed 10000 unless you have a very large amount of memory allocated to Spatial Studio.

Parent topic: Changing the Configuration Using the sgtech_config.json File

2.6.4 Importing Additional Configuration Files in Spatial Studio

Spatial Studio 22.1 allows you to import different configuration files into the main sgtech_config.json configuration file.

The following describes the workflow for handling multiple configuration files:

Figure 2-2 Workflow to Handle Multiple Configuration Files

Description of Figure 2-2 follows
Description of "Figure 2-2 Workflow to Handle Multiple Configuration Files"
  1. At startup, Spatial Studio loads the primary configuration file, sgtech_config.json.

    All the settings defined in sgtech_config.json are used as the base settings.

  2. If the sgtech_config.json file contains the imports directive, then it loads the import files in the order (top to bottom) in which they are declared.

    For each loaded import file, the system reads and appends the settings to the base settings.

  3. Once the base settings are all read in, the system encrypts any sensitive items and saves them back to their corresponding file.
  4. Spatial Studio resumes loading the rest of the system.

Adding imports to sgtech_config.json

You can edit the sgtech_config.json file and add the new top-level imports directive as shown: 

"imports" : {
   "<import_name>" : {
      "module" : "<import_file_path>",
      "description" : "<import_description>"
   }
}

In the preceding code:

  • <import_name>: Name of the import file which must be unique. This is used mainly by Spatial Studio to report errors when loading imports files.
  • <import_file_path>: The file path for the imports files must be relative to the containing directory of the main configuration file (~/.sgtech/sgtech_config.json).
  • <import_description>: To describe the purpose of the import.

    description is an optional parameter for the imports property.

For example, configure the metadata_schema details as shown in the following code in sgtech_config.dbsettings.json file. The file path can be ~/.sgtech/extras/sgtech_config.dbsettings.json:
{
  "metadata_schema" : {
    "connection_manager" : "CONTAINER",
    "container_managed" : {
      ...
    },
  }
}

Also, configure the jobs details separately in sgtech_config.jobs.json following the file path ~/.sgtech/extras/sgtech_config.jobs.json: 

{
  "jobs" : {
    "init_threads_count" : 45
  }
}

You can now include the preceding two configuration files in the imports directive in the main sgtech_config.json file (~/.sgtech/sgtech_config.json) as shown: 

{
  "version" : "22.1.0",
  "work_dir" : "",
  "https_only" : true,
  "master_seed" : "<somerandommasterseed>",
  "logging" : {
    "level" : "INFO"
  },
  "imports" : {
    "jobs" : {
      "module" : "extras/sgtech_config.jobs.json"
    },
    "db" : {
      "module" : "extras/sgtech_config.dbsettings.json",
      "description" : "Database settings optimized for clustering"
    }
  }
}

Import Files Requirements

It is important you adhere to the following requirements when handling multiple import files:

  • Files for imports must be located inside the same directory as the primary sgtech_config.json file, or any of its subdirectories.
  • Settings included in the imports files must not make collision with settings declared already in other configuration files, including the primary sgtech_config.json configuration file.
  • Since imports files can contain sensitive data, only the file owner must have read, write or both access.
  • version, work_dir, master_seed and imports are settings which are restricted to the primary configuration file, sgtech_config.json .

Parent topic: Changing the Configuration Using the sgtech_config.json File

2.6.5 If the Spatial Studio Repository Schema Password Has Been Changed

If the Spatial Studio Repository Schema Password has been changed, you must update the sgtech_config.json configuration file, as follows:

  1. Make a backup copy of the file. For example, copy ~/.sgtech/sgtech_config.json to ~/.sgtech/sgtech_config.json_backup.
  2. On the Spatial Studio compute node, edit the file ~/.sgtech/sgtech_config.json.
  3. In the metadata_schema section, update database_password to the desired value.
  4. Save the file and then restart the Spatial Studio deployment. To restart if you are using the Quick Start kit, see the README file for the Quick Start; to restart if this is a WebLogic Server deployment, use the WebLogic Server console.
  5. Open the Spatial Studio application. You should be able to log in.

You will still have all the artifacts you had created, including other (non-repository) connections, which you can edit as needed.

Parent topic: Changing the Configuration Using the sgtech_config.json File

2.7 Recovery from Lost Master Key

If you accidentally delete or replace the sgtech_config.json file, then the master key is lost and the Spatial Studio application will throw an error.

The sgtech_config.json file includes a master seed property which contains the master key value that enables decryption of encrypted items such as database passwords. It is therefore recommended to backup your sgtech_config.json file in a safe location.

However, if you lose the sgtech_config.json file, then it is possible to recover from a lost master key by performing the following steps:

  1. Stop the Spatial Studio instance by running the following command from the application installation directory:
    ./stop.sh

    If you installed the application from the Cloud Marketplace, then use the following command:

    sudo systemctl stop spatialstudio
  2. Run the following command in your Spatial Studio repository using a SQL client (such as Database Actions, SQL Plus or SQL Developer):
    DELETE
    "SGTECH_OBJECT"
WHERE
    "TENANTID" = 'GLOBAL'
    AND (
        "ID" IN ('id__sgtech.safe_text.magicword', 'id__sgtech.key_pair.rsa')
        OR "OBJECTTYPE" = 'access_token'
    );
COMMIT;
  3. Start Spatial Studio by running the following command from the application installation directory:
    ./start.sh

    If you installed the application from the Cloud Marketplace, then use the following command:

    sudo systemctl start spatialstudio
  4. Log into Spatial Studio as the admin user.
  5. Navigate to the Connections page.
  6. Right-click on each connection, select Edit, and re-enter the password for each connection.
  7. Open Access Tokens dialog and delete each active token.
  8. Navigate to the Administration page.
  9. Optionally, if you had created a custom basemap with a separate API key, then re-enter the API Key by editing the required custom basemap.
    Click Basemaps under Settings to view and edit your custom basemap.
  10. Optionally, if you had created a Cesium basemap with a separate API key, then re-enter the API Key by editing the required Cesium basemap.
    Click Cesium Basemaps under Settings to view and edit your Cesium basemap.
Make sure to back up the sgtech_config.json configuration file safely this time so you do not have to repeat this process in the future.

Parent topic: Administering Oracle Spatial Studio

2.8 Enabling IDCS as Identity Provider in Spatial Studio

Starting from Oracle Spatial Studio Release 22.1.0, you can log into your Spatial Studio instance using users already managed by your own Oracle Cloud tenancy's IDCS identity domain.

The workflow to setup IDCS as the identity provider for Spatial Studio involves the following three steps:

  1. Adding Spatial Studio roles as Groups in IDCS.
  2. Creating an Application in IDCS.
  3. Copying IDCS settings into Spatial Studio's configuration file.

Before you begin, see Prerequisite Requirements for Setting Up IDCS with Spatial Studio to ensure that you meet all the prerequisite requirements.

Parent topic: Administering Oracle Spatial Studio

2.8.1 Prerequisite Requirements for Setting Up IDCS with Spatial Studio

To integrate IDCS with Spatial Studio, you must obtain the following details:

Retrieving IDCS Instance details

You can obtain the IDCS instance details by inspecting any of the IDCS URLs. For instance, you can inspect the IDCS login URL which you receive in the email when you are added as a user in IDCS. For example, consider the following sample IDCS cloud account login URL:

https://idcs-54656e616e742d4578616d706c652121.identity.oraclecloud.com/ui/v1/signin

You can now derive the IDCS instance details from the preceding URL as shown:
  • IDCS tenant: idcs-54656e616e742d4578616d706c652121
  • IDCS host: identity.oraclecloud.com

Parent topic: Enabling IDCS as Identity Provider in Spatial Studio

2.8.1.1 Determining the IDCS Console URL

OCI tenancies include a default IDCS instance and you can obtain the IDCS console URL using the OCI console.

Perform the following steps to identify the URL to access IDCS console:
  1. Sign in to the OCI console using your Oracle Cloud credentials.
  2. Open the navigation menu and select Identity and Security.
  3. Click Federation under Identity.
    The Federation page opens as shown:

    Figure 2-3 Default IDCS Instance on the Federation Page

    Description of Figure 2-3 follows
    Description of "Figure 2-3 Default IDCS Instance on the Federation Page"
  4. Click on the default IDCS instance, shown highlighted in the preceding figure.
    The Identity Provider Details page opens.
  5. Note the IDCS console URL in the Oracle Identity Cloud Service Console field as shown:

2.8.2 Adding Spatial Studio Role as a Group in IDCS

You must add the system administrator role supported in Spatial Studio as a group in IDCS.

The system administrator role in Spatial Studio is identified by SGTech_SystemAdmin. This implies that the administrator has full access to the entire system.

You need to add this role as an IDCS group. However, the following applies:

  • Users assigned to this group will have admin rights in the Spatial Studio instance that is being set up.
  • Users who do not belong to this group will have regular access to the Spatial Studio instance when added to the IDCS application.
As a prerequisite, you must obtain the IDCS console URL. See Determining the IDCS Console URL for details.

Perform the following steps to create the groups in IDCS:

  1. Open the IDCS login page using the IDCS console URL in your browser.
  2. Enter the ADMIN user credentials and sign in as shown:
  3. Open the navigation menu on top left, select Groups and click Add to create a new group as shown:

    Figure 2-6 Adding an IDCS Group

    Description of Figure 2-6 follows
    Description of "Figure 2-6 Adding an IDCS Group"
    The Add Group dialog opens and displays the Step 1: Group Details page.
  4. Enter Name as SGTech_SystemAdmin.
    Note that the role name is case sensitive.
  5. Optionally, enter a Description.
  6. Click Next as shown:

    Figure 2-7 Step-1: Group Details

    Description of Figure 2-7 follows
    Description of "Figure 2-7 Step-1: Group Details"
    Step 2: Assign Users to Group (Optional) page opens listing all the existing users.
  7. Select the required user and click Finish.
    For example, the following figure shows assigning spatialstudio_user to the group role SGTech_SystemAdmin:

    Figure 2-8 Step2: Assign Users to a Group

    Description of Figure 2-8 follows
    Description of "Figure 2-8 Step2: Assign Users to a Group"
  8. Verify that the newly added group is listed on the Groups page:

Parent topic: Enabling IDCS as Identity Provider in Spatial Studio

2.8.3 Creating an Application in IDCS

This section describes the steps to add the Spatial Studio application in IDCS.

  1. Sign in to IDCS using ADMIN user credentials.
  2. Open the navigation menu on top left, select Applications and click Add to add a new application as shown:

    Figure 2-10 Adding an Application

    Description of Figure 2-10 follows
    Description of "Figure 2-10 Adding an Application"
    The Add Application dialog opens.
  3. Select Confidential Application.

    Figure 2-11 Add Application Dialog

    Description of Figure 2-11 follows
    Description of "Figure 2-11 Add Application Dialog"
    The Add Confidential Application wizard opens displaying the Details page.
  4. Enter the application Name.
  5. Optionally, add a Description and click Next.

    Figure 2-12 Add Confidential Application: Details Page

    Description of Figure 2-12 follows
    Description of "Figure 2-12 Add Confidential Application: Details Page"
    The Client page opens.
  6. Click Configure this application as a client now to configure the authorization information for the new application.
    Perform the following in the Authorization section:
    1. Enable Client Credentials and Authorization Code for Allowed Grant Types.
    2. Enter <spatial_studio_url>/idcscallback in Redirect URL.
    3. Enter <spatial_studio_url> in Post Logout Redirect URL.
    4. Optionally, for Security, you can enable Trusted Client to import a custom certificate.

    Figure 2-13 Configuring Client Details

    Description of Figure 2-13 follows
    Description of "Figure 2-13 Configuring Client Details"
    Perform the following in the Token Issuance Policy section:
    1. Click Add under Grant the client access to Identity Cloud Service Admin APIs to enable the application to access IDCS APIs.

      The Add App Role window opens listing the application roles.

    2. Select Me and Authenticator Client and click Add to assign these application roles to the application as shown:

      Figure 2-14 Configuring Token Issuance Policy

      Description of Figure 2-14 follows
      Description of "Figure 2-14 Configuring Token Issuance Policy"
    3. Click Next on the top right of the page to continue.
  7. Skip Resources and Web Tier Policy by clicking the Next button and navigate to the Authorization page.
  8. Enable the Enforce Grants as Authorization option.
  9. Click Finish.

    Figure 2-15 Configuring Authorization

    Description of Figure 2-15 follows
    Description of "Figure 2-15 Configuring Authorization"
    The application is added and the Application Added dialog box opens.

    Figure 2-16 Confirmation Dialog

    Description of Figure 2-16 follows
    Description of "Figure 2-16 Confirmation Dialog"
  10. Note the Client ID and Client Secret to be used later to complete the configuration.

    Tip:

    You can also obtain the client credentials for the application from the Configuration tab in the General Information section, once the application is activated.
  11. Click Close.

    The new application’s Details page is displayed.

  12. Click Activate to grant users access to the application and confirm the operation on the prompt that follows.

    Figure 2-17 Confirmation for Activating Application

    Description of Figure 2-17 follows
    Description of "Figure 2-17 Confirmation for Activating Application"
  13. Click the Groups tab and then click Assign to add the group created in Adding Spatial Studio Role as a Group in IDCS as shown:

    Figure 2-18 Assigning Groups to an Application

    Description of Figure 2-18 follows
    Description of "Figure 2-18 Assigning Groups to an Application"
  14. Optionally, add non-admin users through the Users tab or using other groups.

    Figure 2-19 Assigning Non-Admin Users

    Description of Figure 2-19 follows
    Description of "Figure 2-19 Assigning Non-Admin Users"

Parent topic: Enabling IDCS as Identity Provider in Spatial Studio

2.8.4 Copying IDCS Settings into Spatial Studio's Configuration File

To integrate Spatial Studio with IDCS, you must add the IDCS settings into the sgtech_config.json configuration file.

The configuration file is located at ~/.sgtech/sgtech_config.json path. You can directly append the IDCS settings into the sgtech_config.json file. However, the best practice is to have the IDCS settings in a separate configuration file and then import this file into the main configuration file.
Perform the following steps to create a configuration file for the IDCS settings and to import this configuration in sgtech_config.json:
  1. Create a new empty JSON configuration file in the ~/.sgtech directory.
    For example:

    ~/.sgtech/sgtech_config.idcs.json

  2. Edit the created file with a file editor of your choice and add the IDCS settings information as shown:
    {
  "idcs" : {
    "Host" : "identity.oraclecloud.com",
    "ClientTenant" : "<tenant_id>",
    "ClientId" : "<client_id>",
    "ClientSecret" : "<client_secret>",
    "redirectURL" : "https://localhost:4040/spatialstudio/idcscallback",
    "postLogoutRedirectURL" : "https://localhost:4040/spatialstudio/"
  }
}

    In the preceding file:

    • Host: IDCS host.
    • Client Tenant: IDCS tenant.
    • ClientId : Generated when creating the IDCS application.
    • ClientSecret : Generated when creating the IDCS application.
    • redirectURL : Same as the Redirect URL used when creating the IDCS application.
    • postLogoutRedirectURL : Same as the Post Logout Redirect URL used when creating the IDCS application.
  3. Save the sgtech_config.idcs.json file.
  4. Edit the main sgtech_config.json file and add the import configuration as shown:
    {
  "version" : "23.1.0",
  "work_dir" : "",
  ...
  "jobs" : {
    "init_threads_count" : 15
  },
  "imports" : {
    "idcsclient" : {
      "module" : "sgtech_config.idcs.json"
    }
  }

    It is important to note that there can be only one imports object in the main sgtech_config.json file. Therefore, if an imports configuration is already existing in the main sgtech_config.json file, then you can add the idcsclient entry to the imports block as shown: 

    {
  "version" : "23.1.0",
  "work_dir" : "",
  ...
  "jobs" : {
    "init_threads_count" : 15
  },
  "imports" : {
    "idcsclient" : {
      "module" : "sgtech_config.idcs.json"
    },
    "rolesmapping" : {
      "module" : "sgtech_config.security.json"  
    }
  }
  5. Save the sgtech_config.json file.

Parent topic: Enabling IDCS as Identity Provider in Spatial Studio

2.8.5 Testing IDCS Login

After all the setup steps are completed, you can test and verify the IDCS login.

  1. Ensure you have logged out from IDCS.
  2. Ensure all Spatial Studio instances are stopped.
    You can stop a Spatial Studio instance by executing stop.sh for Linux and stop.cmd for Windows.
  3. Run Spatial Studio by executing start.sh (Linux) or start.cmd (Windows).
  4. Open the main URL in your browser, once Spatial Studio is running. For example:
    https://localhost:4040/spatialstudio/
    The IDCS login screen as shown in Figure 2-5 opens instead of Spatial Studio's standard login screen.
  5. Enter your credentials and click Sign In.
    You will be automatically redirected to the Spatial Studio instance. You can verify the logged in user by clicking on the Avatar icon as shown:

    Figure 2-20 Profile Menu

    Description of Figure 2-20 follows
    Description of "Figure 2-20 Profile Menu"
  6. Click Sign out in the Profile menu to logout from Spatial Studio.
    Note, this will also log you out from any other application that is running on IDCS.

Parent topic: Enabling IDCS as Identity Provider in Spatial Studio

2.9 Mapping External User Principals to Built-In Spatial Studio Roles

Spatial Studio supports mapping IDCS and other identity provider principals to the Spatial Studio built-in roles. This enables dynamically granting permissions to users by using custom groups, for instance.

In order to map the principals to Spatial Studio roles, you must add the security settings into the sgtech_config.json configuration file.
The configuration file is located at ~/.sgtech/sgtech_config.json path. You can directly append the security settings into the sgtech_config.json file. However, the best practice is to have the security settings in a separate configuration file and then import this file into the main configuration file.
Perform the following steps to create a configuration file containing the security settings and then import this configuration in sgtech_config.json:
  1. Create a new empty JSON configuration file in the ~/.sgtech directory.
    For example:

    ~/.sgtech/sgtech_config.security.json

  2. Edit the created file with a file editor of your choice and add the security settings information as shown:
    {
  "security" : {
    "role-assignments" : [
        {
          "role" : "<role_name>",
          "principals" : [
            "<principal_name>"
           ]
        }
    ]
  }
}

    In the preceding file:

    • role: This refers to one of Spatial Studio built-in roles, specifically SGTech_SystemAdmin or SGTech_TenantAdmin. Note that the role name is case-sensitive.
    • principals: List of all principals’ names that must be mapped to the specified role. For example, ["Power_User_Members", “IT_Support_Team”], which might be IDCS or WebLogic Server groups, or properties designated in conf/jetty-realm.properties file in QuickStart.
    • role-assignments: List of the roles mapping. You can specify as many entries as required.
  3. Save the sgtech_config.security.json file.
  4. Edit the main sgtech_config.json file and add the import configuration as shown:
    {
  "version" : "23.1.0",
  "work_dir" : "",
  ...
  "jobs" : {
    "init_threads_count" : 15
  },
  "imports" : {
    "rolesmapping" : {
      "module" : "sgtech_config.security.json"
    }
  }

    It is important to note that there can be only one imports object in the main sgtech_config.json file. Therefore, if an imports configuration is already existing in the main sgtech_config.json file, then you can add the rolesmapping entry to the imports block as shown: 

    {
  "version" : "23.1.0",
  "work_dir" : "",
  ...
  "jobs" : {
    "init_threads_count" : 15
  },
  "imports" : {
    "idcsclient" : {
      "module" : "sgtech_config.idcs.json"
    },
    "rolesmapping" : {
      "module" : "sgtech_config.security.json"  
    }
  }
  5. Save the sgtech_config.json file.
    This grants all users from the groups configured for the principals, the respective role that was specified in the role configuration, when logging into Spatial Studio.

Parent topic: Administering Oracle Spatial Studio