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

Some prerequisites and recommendations apply for using Spatial Studio.

Oracle Spatial and Graph 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 12.2 or later. This applies both to the Spatial Studio metadata schema and to all database connections that will be used by Spatial Studio users.
  • Oracle WebLogic Server 12.2.1.3 or later.
  • At least the following privileges for each database user that works with Spatial Studio:

    connect, create session, create table, create view, create sequence, create procedure, create type, create synonym, create trigger

    Note:

    The create trigger privilege is required only if you intend to store and display GeoRaster data in the schema.
  • 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/spatialandgraph.html and find the instructions 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 8 (64-bit, update 181 or later) and your own database schemas.

The following are general steps for getting started:

  1. Download the Quick Start zip archive OracleSpatialStudio_qs.zip.
  2. Unzip (extract) it, which results in a directory named Oracle_Spatial_Studio.
  3. Ensure that the JAVA_HOME environment variable exists on your system, and points to a full JDK installation of Java SE Development Kit 8u181 (64-bit) or later. JDK 11 can also be used.
  4. Ensure that the ports 8080 and 4040 are not being used by any other (web) applications. (You can direct Spatial Studio to use different ports, but 8080 and 4040 are the default.) Port 8080 is to used with the http:// protocol, while port 4040 is for the https:// protocol.

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

  5. From a command window (Windows) or terminal (Linux or Mac), go to (cd) the Oracle_Spatial_Studio directory. This directory contains several .bat or .sh files.
  6. Use start.sh or start.bat to start the application. (On Linux or Mac you may need to ensure that the .sh files are executable by first running the command: chmod u+x *.sh)

    Leave the terminal or command window open.

  7. In your browser, go to the URL: https://localhost:4040/spatialstudio

    The default admin user login credentials are admin/welcome1. It is strongly recommended that you immediately change the password.

    The admin user's and the two built-in regular users’ passwords are all stored in encrypted form. For how to change the (encrypted) password of a Spatial Studio user, see the README file for the Quick Start. This README file also contains information about starting and restarting the Quick Start.

Note:

The following considerations apply to using the Quick Start:

  • The default port is 4040, but you can change it by editing the file conf/server.json in Oracle_Spatial_Studio. You will need to restart the application after you make any change. (The same applies if you change the HTTP port value from the default 8080.)
  • The Quick Start provides several predefined web user login accounts named admin, manager, author, consumer, and limited. These users and their login passwords are defined in the configuration file conf/jetty-realm.properties. You should change the passwords immediately after you unzip the downloaded Quick Start kit.

    Because the Quick Start is intended for personal use, the passwords for the end user accounts are not encrypted. However, 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.

  • 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 to a WebLogic Server Domain

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.

Note that 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.

2.3 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.

Parent topic: Administering Oracle Spatial Studio

2.4 Connection Requirements for Database Users of Spatial Studio

Individuals who analyze spatial data or create spatial applications will want to be able to use Spatial Studio after the tool has been installed.

Each such individual will need to connect as a database user that is authorized to run Spatial Studio. For each such database user, you as the Spatial Studio administrator must enable such access.

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.

In order to be used for Spatial Studio connections, 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.5 Changing the Configuration Using the 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 Studio EAR to a WebLogic domain or are just using the Quick Start.

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.5.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.5.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.5.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.5.4 If the Spatial Studio Repository Schema Password Has Been Changed

It 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 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 Studio 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