Rocket Multivalue Integration Server Installation

Rocket MultiValue Integration Server

Installation and User Guide

Version 1.3.0

March 2021 MVIS-130-IUG-01 Notices

Edition

Publication date: March 2021 Book number: MVIS-130-IUG-01 Product version: Version 1.3.0

Trademarks

Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks go to: www.rocketsoftware.com/about/legal. All other products or services mentioned in this document may be covered by the trademarks, service marks, or product names of their respective owners.

Examples

This information might contain examples of data and reports. The examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

License agreement

This software and the associated documentation are proprietary and confidential to Rocket Software, Inc. or its affiliates, are furnished under license, and may be used and copied only in accordance with the terms of such license.

Note: This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when exporting this product.

2 Corporate information

Rocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks, and compliance; database servers and tools; business information and analytics; and application development, integration, and modernization. Website: www.rocketsoftware.com Rocket Global Headquarters 77 4th Avenue, Suite 100 Waltham, MA 02451-1468 USA To contact Rocket Software by telephone for any reason, including obtaining pre-sales information and technical support, use one of the following telephone numbers.

Country Toll-free telephone number United States 1-855-577-4323 Australia 1-800-823-405 Belgium 0800-266-65 Canada 1-855-577-4323 China 400-120-9242 France 08-05-08-05-62 Germany 0800-180-0882 Italy 800-878-295 Japan 0800-170-5464 Netherlands 0-800-022-2961 New Zealand 0800-003210 South Africa 0-800-980-818 United Kingdom 0800-520-0439

Contacting Technical Support

The Rocket Community is the primary method of obtaining support. If you have current support and maintenance agreements with Rocket Software, you can access the Rocket Community and report a problem, download an update, or read answers to FAQs. To log in to the Rocket Community or to request a Rocket Community account, go to www.rocketsoftware.com/support. In addition to using the Rocket Community to obtain support, you can use one of the telephone numbers that are listed above or send an email to [email protected].

3 Contents

Notices...... 2 Corporate information...... 3 Part I: MultiValue Integration Server Installation Guide...... 7 Chapter 1: MultiValue Integration Server Overview...... 8 Deployment Scenarios...... 8 Chapter 2: System requirements...... 11 Chapter 3: Installing MVIS...... 13 Installing MVIS on Windows...... 13 Installing MVIS on Linux and UNIX...... 14 Installing MVIS as a Docker container image...... 14 Chapter 4: Starting and stopping MVIS...... 16 Starting the MultiValue Integration Server service...... 16 Starting the MVIS Admin on Windows...... 16 Opening the MVIS Web Admin UI...... 16 Starting MVIS from the MVIS Web Admin UI...... 17 Stopping and shutting down MVIS...... 17 Chapter 5: Upgrading MVIS...... 18 Upgrading MVIS on Windows...... 18 Upgrading MVIS on Linux and AIX...... 19 Upgrading MVIS as a Docker container image...... 19 Chapter 6: Uninstalling MVIS...... 20 Part II: MultiValue Integration Server User Guide...... 21 Chapter 7: Important concepts to understand when working with MVIS...... 22 REST...... 22 Cloud Platforms...... 23 Scaling and Clustering...... 24 Containerization...... 25 Monitoring and Logging...... 26 DevOps...... 26 Chapter 8: Using MVIS with Docker containers...... 28 Installing and configuring Docker for MVIS...... 28 Deployment using shared volumes (local storage)...... 28 Deploying using Redis as a shared storage and notification server...... 30 Setting logging levels...... 32 MVIS and Docker examples...... 33 Chapter 9: Configuring MVIS...... 35 Adding an account to MVIS...... 35 Adding REST endpoints...... 38 Creating REST data resources with MVIS...... 39 Calling data resources with MVIS...... 40 Optimistic concurrency control...... 40 Creating REST subroutine endpoints with MVIS...... 41 Calling BASIC subroutines with MVIS...... 43 Sharing REST server endpoints...... 43 Importing a U2 REST server...... 44 Invoking the health check endpoint in U2REST...... 45 Converting your WebDE configuration file to a cm.ini configuration file...... 45 Enabling SBXA for MVIS...... 47 Modifying connection defaults...... 47 Monitoring connections...... 50 Defining the yellow and red triggers of the monitor from the MVIS Web Admin UI...... 51

4 Contents

Defining the yellow and red triggers of the monitor...... 51 Viewing MVIS logs...... 52 Configuring performance statistics with the cm.ini file...... 53 Configuring performance statistics with the MVIS Web Admin UI...... 53 Viewing and setting MVIS log levels...... 54 Configuring logging to the console on Linux/UNIX...... 54 Configuring logging to the console on Windows...... 55 Vanity URLs...... 55 Setting-up vanity URLs...... 55 Using Thymeleaf to create templates...... 58 Using u2version in PUT and PATCH requests...... 60 Filtering and sorting Get type Vanity URL results...... 61 Creating vanity endpoints when using Docker shared volumes...... 62 Creating vanity endpoints when using Docker Redis cache...... 62 Vanity URL data resource examples...... 63 Vanity URL subroutine examples...... 67 Chapter 10: Working with associations in MVIS...... 85 Chapter 11: Using MVIS in the cloud...... 93 Azure overview...... 93 Setting up an MVIS Kubernetes cluster in Azure...... 93 Logging to Application Insights on Windows...... 97 Logging to Application Insights on Linux/UNIX...... 97 Sending performance statistics to Application Insights on Linux/UNIX...... 97 Configuring MVIS and the MVIS Admin for Azure Blob storage...... 98 Configuring MVIS for Blob storage on Linux/UNIX...... 98 Configuring the MVIS Admin for Blob storage on Linux/UNIX...... 99 Configuring MVIS for Blob storage on Windows...... 99 Configuring the MVIS Admin for Blob storage on Windows...... 100 Configuring MVIS and the MVIS Admin for Azure Service Bus...... 100 Configuring MVIS for Azure Service Bus on Linux/UNIX...... 101 Configuring the MVIS Admin for Azure Service Bus on Linux/UNIX...... 101 Configuring MVIS for Azure Service Bus on Windows...... 102 Configuring the MVIS Admin for Azure Service Bus on Windows...... 102 AWS overview...... 103 Setting up an MVIS Kubernetes cluster in AWS...... 103 Logging to Amazon CloudWatch on Windows...... 106 Logging to Amazon CloudWatch on Linux/UNIX...... 107 Sending performance statistics to AWS CloudWatch on Windows...... 108 Sending performance statistics to AWS CloudWatch on Linux / UNIX...... 108 Configuring MVIS and the MVIS Admin for Amazon S3 storage...... 109 Configuring MVIS for Amazon S3 storage on Linux/UNIX...... 109 Configuring the MVIS Admin for Amazon S3 storage on Linux/UNIX...... 109 Configuring MVIS for Amazon S3 storage on Windows...... 110 Configuring the MVIS Admin for Amazon S3 storage on Windows...... 110 Chapter 12: Enabling security for MVIS...... 112 Encrypting the password for the MVIS Web Admin UI and MVIS Admin...... 112 Setting up SSL...... 113 Security between the client and the MVIS Admin...... 113 Security between applications and MVIS...... 114 Security between MVIS and the database...... 114 REST server security configuration...... 115 Defining HTTP users...... 115 Defining access control...... 116 Setting-up OAuth authentication...... 117 Appendix A: cm.ini file properties...... 118 Appendix B: MVIS Java options...... 123

5 Contents

Appendix C: Limitations...... 125

6 Part I: MultiValue Integration Server Installation Guide

The Rocket MultiValue Integration Server Installation Guide includes information for installing, uninstalling and upgrading MVIS on Windows, Linux, UNIX and as a Docker image. • MultiValue Integration Server Overview Rocket MultiValue Integration Server (MVIS) is a piece of middleware that sits between an application and the MultiValue database server and provides connection management, monitoring, and administration services. • System requirements The tables below describes the different requirements for each platform that must be completed prior to installation and the hardware requirements for MVIS: • Installing MVIS MVIS installation is composed of installing MVIS and the MVIS Admin. • Starting and stopping MVIS After you've installed MVIS, perform the following tasks to start or stop MVIS. • Upgrading MVIS Review the information below prior to upgrading MVIS and the MVIS Admin: • Uninstalling MVIS Compete these instructions to uninstall MVIS.

7 Chapter 1: MultiValue Integration Server Overview

Rocket MultiValue Integration Server (MVIS) is a piece of middleware that sits between an application and the MultiValue database server and provides connection management, monitoring, and administration services. ▪ MVIS manages and monitors API connections to the data servers. ▪ MVIS includes a web-based user interface (MVIS Web Admin UI) for the purpose of administration and monitoring functions. ▪ MVIS requires a Java 8 runtime and can be installed on your data server machine, or on any machine that has network access to the data server. ▪ Use MVIS to easily expose your business logic (subroutines) or data resources as RESTful endpoint using the MVIS Web Admin UI or by using the MVIS Admin's APIs. ▪ MVIS can provide an additional layer of resiliency and failover through the support of clustering and graceful shutdown. ▪ The MVIS Web Admin UI is integrated with the Swagger OpenAPI 2.0. You can access the OpenAPI 2.0 definition for a specific endpoint directly from a subroutine or data resource definition. In addition, MVIS's administrative REST endpoints are also available through the Swagger UI for you to use in your own applications. These administrative OpenAPI endpoint definitions are available by clicking the Swagger icon from the bottom left-hand corner of the MVIS Web Admin UI. ▪ MVIS also provides the Swagger Editor which allows you to generate client- and server-side code to assist with mocking. Parent topic: MultiValue Integration Server Installation Guide Deployment Scenarios

Review the deployment scenario diagrams to get a better understanding of the deployment of the MVIS system.

8 Deployment Scenarios

Figure 1: MVIS Rest API Server scenario

Figure 2: MVIS UO API Server scenario

9 Chapter 1: MultiValue Integration Server Overview

Figure 3: MVIS Cloud Deployment 1 scenario

Figure 4: MVIS Cloud Deployment 2 scenario

10 Chapter 2: System requirements

The tables below describes the different requirements for each platform that must be completed prior to installation and the hardware requirements for MVIS:

Platform requirements

Platform Requirements Windows: ▪ UniVerse 11.3.1 or later, or UniData 8.2.1 or later running on a local or remote machine that is licensed for connection pooling. Windows Server 2012 ▪ Java (JDK or JRE) version 1.8, OpenJDK 1.8. To download OpenJDK 1.8, go to https://openjdk.java.net/install/. ▪ Python 3.7 with the latest version of pip (Python’s package manager). Do not use version 3.4 that currently comes with UniVerse and UniData.

Note: Python 3.8 is not supported for Windows platforms. For a workaround to this issue, see Tech Note 000017690 - MVIS Install Fails When Using Python 3.8 or Later On Windows on the Rocket Community: https://my.rocketsoftware.com/RocketCommunity/RCLogin It is recommended that you upgrade to the latest version of pip before beginning installation. If you are installing Python for the first time, select Add Python 3.X to PATH from the Setup window. If you already have Python installed, ensure that the path-to- Python\Scripts directory is included in your PATH environment variable so the pip executable can be located. To update pip to the latest version, enter the following: python -m pip install -U pip Linux and AIX: ▪ UniVerse 11.3.1 or later, or UniData 8.2.1 or later running on a local or remote machine that is licensed for connection pooling. RedHat Enterprise Linux 7 ▪ Java (JDK or JRE) version 1.8, OpenJDK 1.8. To download OpenJDK 1.8, go to https://openjdk.java.net/install/. AIX 7.2 ▪ Python 3.7 with the latest version of pip (Python’s package manager).Do not use version 3.4 that currently comes with UniVerse and UniData. It is recommended that you upgrade to the latest version of pip before beginning installation. To update pip to the latest version, enter the following: pip install -U pip Each Linux distribution has its own recommended mechanism to install Python 3.X. Follow the recommendations for your particular Linux distribution.

Hardware requirements

CPU 2vCPU Memory Minimum of 4 GB available memory. Disk space Minimum of 2 GB available disk space.

11 Chapter 2: System requirements

Parent topic: MultiValue Integration Server Installation Guide

12 Chapter 3: Installing MVIS

MVIS installation is composed of installing MVIS and the MVIS Admin. Before installing MVIS: ▪ Download MVIS from Rocket RBC at https://rbc.rocketsoftware.com/ ▪ Ensure that you have administrator rights setup on the system on which you are installing MVIS.

Caution: Prior to installing MVIS, it is imperative that you upgrade your system to the minimum versions of Java and Python (Windows and Linux only) as described in System Requirements. This includes installing the packages, setting the appropriate Environment Variables and Java path, and restarting your system to ensure that your changes are enabled.

Note: After installing MVIS, you may receive a message when connecting to the server stating that your UniVerse or UniData license has expired. Receiving such a message indicates that your server is not currently licensed for Connection Pools. In such a case, you will need to purchase/add a Connection Pool license for your server to use MVIS.

Parent topic: MultiValue Integration Server Installation Guide Installing MVIS on Windows

Install MVIS on either the data server machine or a separate machine with network access to the data server.

Important: Before beginning your installation, be certain that your system matches all the requirements for your platform as described in System Requirements. Also, see Installing MVIS for additional information that you will need to review and complete before installing MVIS.

Procedure

1. After downloading the application, install it from the build folder. 2. From the Command Prompt, navigate to the directory containing the complete_install.py file and enter the following command: python complete_install.py install A complete installation begins and pip packages are installed on the machine (even without an Internet connection). 3. You will be prompted whether you want to install MVIS and where the new files should be installed. Specify this information. 4. An MVIS installation requires administrator rights. If administrator rights were not specified earlier in the process, a prompt will display requesting these rights. Accept the request. A new window will open and the installation finishes. 5. When the prompts are complete, enter Y to start the MVIS Admin.

Note: To see a list of other commands, enter the following command at the Command Prompt: python complete_install.py --help

13 Chapter 3: Installing MVIS

Installing MVIS on Linux and UNIX

Install MVIS on either the data server machine or a separate machine with network access to the data server.

Procedure

Note: To see a list of other commands, enter the following command at the Command Prompt: python complete_install.py --help

Installing MVIS as a Docker container image

MVIS supports being deployed as a Docker container image.

About this task

Download and install docker from http://www.docker.io. MVIS ships with the following two (MVIS and the MVIS Admin) container images:

▪ cm-1.3.x_nnnn.tar.gz ▪ cmadmin-1.3.x_nnnn.tar.gz

Procedure

1. To install the MVIS and MVIS Admin Docker images, navigate to the directory containing the cm-1.3.x_nnnn.tar.gz and cmadmin-1.3.x_nnnn.tar.gz container images, and then run the following commands: $ docker load -i cm-1.3.x_nnnn.tar.gz

14 Installing MVIS as a Docker container image

$ docker load -i cmadmin-1.3.x_nnnn.tar.gz 2. To load the MVIS image into the local Docker repository, enter the following command: $ docker image load -i cm-1.3.x_nnnn.tar.gz 3. To load the MVIS Admin image into the local Docker repository, enter the following command: $ docker image load -i cmadmin-1.3.x_nnnn.tar.gz

15 Chapter 4: Starting and stopping MVIS

After you've installed MVIS, perform the following tasks to start or stop MVIS. • Starting the MultiValue Integration Server service There are two ways to start the MultiValue Integration Server service: from the Windows Services menu and from the MVIS Web Admin UI. • Starting the MVIS Admin on Windows On Windows, you can start and stop the MVIS Admin from the Microsoft Windows Services menu. • Opening the MVIS Web Admin UI After you've started the MVIS Admin, open the MVIS Web Admin UI. • Starting MVIS from the MVIS Web Admin UI Start MVIS from the MVIS Web Admin UI. • Stopping and shutting down MVIS Perform the following steps to stop and shut down MVIS. Parent topic: MultiValue Integration Server Installation Guide Starting the MultiValue Integration Server service

There are two ways to start the MultiValue Integration Server service: from the Windows Services menu and from the MVIS Web Admin UI.

Procedure

Do one of the following depending on your implementation: ▪ For Windows: Do one of the following: ▫ From the Windows Services window, find and select MultiValue Integration Server and click Start the service. ▫ Enter the following command to start MVIS from the command prompt:

C:\u2\cm> start-cm.bat

▪ For Linux or AIX, navigate to /opt/cm directory and run the following command:

./start-cm.sh

Parent topic: Starting and stopping MVIS Starting the MVIS Admin on Windows

On Windows, you can start and stop the MVIS Admin from the Microsoft Windows Services menu. Parent topic: Starting and stopping MVIS Opening the MVIS Web Admin UI

After you've started the MVIS Admin, open the MVIS Web Admin UI. 1. Open a browser window. 2. In the address bar, enter http://host:7077.

16 Starting MVIS from the MVIS Web Admin UI

host is the location where MVIS is installed. 7077 is the default port for the MVIS Web Admin UI, but this port can be changed. 3. In the Username and Password field, enter your username and password. admin is the default for both fields. 4. Click Sign In. The MVIS Web Admin UI is displayed. Parent topic: Starting and stopping MVIS Starting MVIS from the MVIS Web Admin UI

Start MVIS from the MVIS Web Admin UI. From the MVIS Web Admin UI, on the MultiValue Integration Server Status section, enter the server where MVIS is running, and then click Start.

Note: If you are running in MVIS in a container environment, the container command should be used to start the MVIS containers.

Parent topic: Starting and stopping MVIS Stopping and shutting down MVIS

Perform the following steps to stop and shut down MVIS.

About this task

Note: If you are running in a container environment, the container command can be used to stop the MVIS container.

Procedure

1. If you are running MVIS on UNIX, complete the following steps: a. Enter the following command to shutdown MVIS from the Command Prompt: $ ./stop-cm.sh 2. If you are running MVIS on Windows, do one of the complete the following: ▪ Stop the MVIS Windows Service. ▪ Enter the following command to shutdown MVIS from the command prompt: C:\u2\cm> stop-cm.bat Parent topic: Starting and stopping MVIS

17 Chapter 5: Upgrading MVIS

Review the information below prior to upgrading MVIS and the MVIS Admin: ▪ Download MVIS from Rocket RBC at https://rbc.rocketsoftware.com/. ▪ Ensure that you have administrator rights setup on the system on which you are upgrading MVIS. ▪ If you are keeping the configuration files on a local file system (non-cloud-mode), make a copy of your cm.ini and application.properties files and u2rest directory, which you can manually restore after the upgrade.

Note: In MVIS 1.3.0, the following option names have been changed in the application.properties file.

Old option name New option name server.session.timeout server.servlet.session.timeout spring.http.multipart.maxFileSize spring.servlet.multipart.max-file-size spring.http.multipart.maxRequestSize spring.servlet.multipart.max-request-size spring.resources.cache-period spring.resources.cache.period

The MVIS installation will automatically update these option names (if being used) in the application.properties file present inside the cm directory during the upgrade process. No user action is required. However, if you want to use an older backed-up version of the application.properties file, then you will need to update the file manually with new option names (if the older options were used) before adding the file to the cm directory and executing the MVIS services.

• Upgrading MVIS on Windows To upgrade MVIS on Windows, perform the following steps. • Upgrading MVIS on Linux and AIX To upgrade MVIS on Linux or AIX, perform the following steps. • Upgrading MVIS as a Docker container image To upgrade MVIS as a Docker container image, perform the following steps. Parent topic: MultiValue Integration Server Installation Guide Upgrading MVIS on Windows

To upgrade MVIS on Windows, perform the following steps. See Upgrading MVIS for additional information that you will need to review and complete before upgrading MVIS.

18 Upgrading MVIS on Linux and AIX

4. An MVIS upgrade requires administrator rights. If administrator rights were not specified earlier in the process, a prompt will display requesting these rights. Accept the request. A new window will open and finish the upgrade process. 5. When the prompts are complete, enter Y to start the MVIS Admin.

Note: To see a list of other commands, enter the following command at the Command Prompt: python complete_install.py --help

Parent topic: Upgrading MVIS Upgrading MVIS on Linux and AIX

To upgrade MVIS on Linux or AIX, perform the following steps. See Upgrading MVIS for additional information that you will need to review and complete before upgrading MVIS.

1. After downloading the application, begin the upgrade process it from the build folder. 2. In the Command Prompt, change to the new directory and enter the following command: python complete_install.py upgrade The upgrade process begins and pip packages are upgraded on the machine (even without an Internet connection). 3. Then, it asks you if want to upgrade MVIS and where the files should be located. Specify this information. 4. An MVIS upgrade requires administrator rights. If administrator rights were not specified earlier in the process, a prompt will display requesting these rights. Accept the request. A new window will open and finish the upgrade process. 5. When the prompts are complete, enter Y to start the MVIS Admin.

Note: To see a list of other commands, enter the following command at the Command Prompt: python complete_install.py --help

Parent topic: Upgrading MVIS Upgrading MVIS as a Docker container image

To upgrade MVIS as a Docker container image, perform the following steps. See Upgrading MVIS for additional information that you will need to review and complete before upgrading MVIS.

Procedure

Follow the steps described in Installing MVIS as a Docker container image, on page 14. If you are storing your configuration files in the cloud or on a mounted file system that the containers access, they will remain unchanged during the upgrade. Parent topic: Upgrading MVIS

19 Chapter 6: Uninstalling MVIS

Compete these instructions to uninstall MVIS.

1. Navigate to the directory containing the complete_install.py file. 2. At the Command Prompt, enter the following command: python complete_install.py uninstall The uninstall process begins. First, it uninstalls most pip packages (not all packages are deleted during this process). Then, it prompts you to provide the location in which MVIS is located. 3. Specify this information. The MVIS files are uninstalled from the specified location. Parent topic: MultiValue Integration Server Installation Guide

20 Part II: MultiValue Integration Server User Guide

The MultiValue Integration Server User guide includes the information you need for running, configuring, securing and using MVIS. • Important concepts to understand when working with MVIS Review the following topics to familiarize yourself with and gain a better understanding of the concepts and related applications used in MVIS. • Using MVIS with Docker containers Docker is a container platform provider. Containers allow an application or its services and configurations to be packaged as a container image. This containerized application can then be tested as a unit and deployed as an image instance to the OS. • Configuring MVIS Use the MVIS Web Admin UI or cm.ini file to monitor accounts and performance and perform administration tasks. • Working with associations in MVIS Review the instructions and examples below for information on working with associations in MVIS. • Using MVIS in the cloud Cloud-based services can be used to build, deploy, and manage applications through a global network of data centers. • Enabling security for MVIS To enable security for MVIS, complete the following tasks: • cm.ini file properties The cm.ini file contains many of the parameters used to configure MVIS. • MVIS Java options Use Java options to supply configuration parameters on the command line to either MVIS or the MVIS Admin. • Limitations The following limitations exist in the current version of MVIS.

21 Chapter 7: Important concepts to understand when working with MVIS

Review the following topics to familiarize yourself with and gain a better understanding of the concepts and related applications used in MVIS. Parent topic: MultiValue Integration Server User Guide REST

REST is an architectural style that some Web APIs adhere to. It is not a mandatory architectural style, and in practice, even "RESTful" APIs may only adhere to certain parts of the style. REST is characterized by adhering to the architecture of the Web overall. Just as the Web exposes resources such as web pages and images, RESTful Web APIs expose resources that represent entities which are accessible from the URLs that comprise the API. Here is an example of how a Member might be represented (accessible via the Member's id): http://example.com/Members/1001. Accessing this resource might return a JSON representation of the Member whose id is 1001. ▪ REST Tenets https://en.wikipedia.org/wiki/Representational_state_transfer Representational State Transfer ▫ Stateless - no state maintained on the server ▫ Cacheability - resources should declare whether or not they can be cached ▫ Uniform Interface - Standards-based approach for defining the API ▫ URIs define resources

▫ Resources manipulated through standard HTTP commands (GET/PUT/POST/DELETE/PATCH for Read/Update/Create/Delete) ▫ Self-descriptive messages - the message declares how it should be interpreted ("application/ json", etc.) ▫ Client/Server model ▫ Layered System - client cannot tell if it is directly talking to the server, or to an intermediary ▪ Data Formats Data can be represented using different formats. JSON is typical, but others, including XML and YAML can be used ▪ Example of REST API GET http://example.com/Members [ { "id": 1001, "lastName": "Smith", "firstName": "John" }, { "id": 1002, "lastName": "Jones", "firstName": "Samantha"

22 Cloud Platforms

} ] GET http://example.com/Members/1001 { "id": 1001, "lastName": "Smith", "firstName": "John" } PUT http://example.com/Members/1001 { "lastName": "Smith", "firstName": "John" } PATCH http://example.com/Members/1001 { "firstName": "Jonathan" } POST http://example.com/Members { "id": "9999", "firstName": "Regis", "lastName": "Johnson" } ▪ Swagger/Open API Open API (previously known as Swagger) is a standard for documenting REST APIs (https:// en.wikipedia.org/wiki/Open_API) ▪ Vanity URLs Vanity URLs allow you to provide a more descriptive, identifiable name alias for APIs rather than using the existing data resource or subroutine name. This enables consumers of the API to more readily identify what an API provides. See Vanity URLs for more information. Cloud Platforms

There are multiple competing cloud platforms available today. Microsoft Azure, Amazon Web Services (AWS), and Google Compute Platform (GCP) are just a few. Each of these platforms provide services to their customers, including compute services, virtual machine management, storage services, message queues, serverless computing services, and many others. Rocket MVIS employs native hooks that allow it to directly leverage some of these services from AWS and Azure, including storing configurations in S3 and Azure Blob Storage, and utilizing AWS Simple Notification Service and Azure Service Bus for orchestrating clusters of MVIS servers. ▪ Amazon Web Services (AWS) Amazon's Cloud platform https://aws.amazon.com/ ▪ Azure Microsoft's Cloud platform https://azure.microsoft.com Cloud Platform Services Cloud providers offer a set of services on their platform. Examples include compute, storage, business analytics tools, and many others.

23 Chapter 7: Important concepts to understand when working with MVIS

AWS offers S3 for storage, while Azure offers Azure Blob Storage. AWS offers Simple Notification Service (SNS) for a message broker, while Azure offers Azure Service Bus. ▪ Storage Cloud providers offer storage services for their platform. ▪ AWS S3 https://aws.amazon.com/s3/ ▪ Azure Blob Storage https://azure.microsoft.com/services/storage/blobs/ ▪ Message Queues ▫ AWS Simple Notification Service (SNS) https://aws.amazon.com/sns/ ▫ Azure Service Bus https://docs.microsoft.com/azure/service-bus/ ▪ Analytics Cloud providers offer application monitoring services to which applications such as Rocket MVIS can send data and logs. These monitoring services provide advanced analytics, historical data, alerts, and more. ▪ AWS CloudWatch (AWS's analytics and monitoring solution) CloudWatch can accept telemetry data from applications, including Rocket MVIS, to provide business analytics on the data, including graphs, historical data, alerts, and more. https://aws.amazon.com/cloudwatch/ ▪ Azure Application Insights (Azure's analytics and monitoring solution) Azure Application Insights can accept telemetry data from applications, including Rocket MVIS, to provide business analytics on the data, including graphs, historical data, alerts, and more. https://docs.microsoft.com/azure/azure-monitor/app/app-insights-overview Redis https://redis.io/ Redis can be used as a centralized storage of configurations for a cluster of MVIS servers. Coordination between the MV Admin Server and the cluster of MVIS servers can be setup using the Redis message queue. Scaling and Clustering

Scaling the number of application servers can increase throughput of a system. Scaling servers down when load decreases can save on resource usage. Scaling is often setup via an orchestrator, but can also be performed manually. Redis https://redis.io/ Redis can be used as a centralized storage of configurations for a cluster of MVIS servers. Coordination between the MV Admin Server and the cluster of MVIS servers can be setup using the Redis message queue.

24 Containerization

Containerization

Containerization is a technology that bundles applications and their dependencies together into a deployable unit. This enables robustness as applications are always deployed independently of the environment they are deployed to, reducing the chances of environment-specific errors. Due to layering, containers are considered lightweight as compared to VMs. the dependencies that make up an application are themselves distributed in layers which can be reused by other containers with the same dependencies. Containers are inexpensive because they run as an operating system process rather than an entire VM. Thus they use few resources and can start and stop extremely quickly. This makes them extremely beneficial when it comes to clustering, where new containers can be started quickly and with little impact to the system's resources. Orchestration Kubernetes, Amazon Container Services, Azure Container Services. Kubernetes (k8s) is the most well-known container orchestrator. https://kubernetes.io/

Example of a Kubernetes deployment

controllers/nginx-deployment.yaml

apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment labels: app: nginx spec: replicas: 3 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:1.7.9 ports: - containerPort: 80 Docker https://www.docker.com/ Docker is the most well-known container runtime. It provides a set of services that allow a user to easily manage containers, including creating, stopping/starting, as well as providing a repository in which to store the container images.

Table 1:

Images Images are static representations of containers. Container instances are launched from the container image.

25 Chapter 7: Important concepts to understand when working with MVIS

Containers Container instances are runtime instances of container images. docker-compose Containers often need to be run together. docker- compose allows you to specify a set of container images that will be run together as a group.

version: '3' services: cm: image: cm:latest ports: - 7171:7171 - 7870:7870 - 7871:7871 expose: - "7171" - "7870" - "7871" cm-admin: image: cmadmin:latest ports: - 7077:7077 expose: - "7077" Monitoring and Logging

Fluentd integration is our solution for pushing data out to common monitoring and logging solutions such as DataDog, Prometheus, Splunk ▪ Telemetry Data Telemetry data is data from a running application that represent statistics for that application. ▪ 3rd Party Telemetry Consumers There are many popular business analytics solutions that analyze telemetry data: ▪ DataDog - https://www.datadoghq.com/ ▪ Prometheus - https://prometheus.io/ ▪ Splunk - https://www.splunk.com/ DevOps

DevOps is a set of practices that combine software development and deployment with the goal of achieving greater reliability and quicker time to market. ▪ Continuous Integration/Continuous Delivery (CI/CD) Practice that defines how software move's through the deployment pipeline, where each change is tested and ultimately deployed to production server. ▪ Deployment Rolling updates and blue-green deployments are important techniques to DevOps deployments. They allow new versions and bug fixes to be deployed with minimal impact to the overall system. ▪ Upgrading Zero-downtime upgrades are an important goal of DevOps. By utilizing techniques such as rolling-updates and blue-green deployments, DevOps teams can roll out upgrades with minimal impact to a system.

26 DevOps

▪ Packaging Containers are often used for packaging applications in DevOps. ▪ Source Code Control Version control systems are a key part of the DevOps pipeline. They participate in the DevOps cycle by advertising changes and pushing the changes into the pipeline as soon as they occur, using methods such as webhooks.

27 Chapter 8: Using MVIS with Docker containers

Docker is a container platform provider. Containers allow an application or its services and configurations to be packaged as a container image. This containerized application can then be tested as a unit and deployed as an image instance to the OS. Each container image contains one application. Container images can then be created at each build or release without waiting until it's deployed. Creating container images at each build or release allows for environments to be consistent between a development and production environment. Containers are deployed from the OS level rather than from a hardware level. OS level deployment allows containers to be isolated from other containers and the host. Each container has its own file system and acts independently of other containers. Since containers are not tied to a specific infrastructure or file system, containers are portable across different cloud environments and operating systems. Deploying applications from the hardware level relies on users installing the application on a host that uses the operating system package manager. All application executables, libraries, and configuration are stored together, which can cause users to use the incorrect components. This type of deployment also relies on VMs, which are non-portable. Containers are also capable of scalability. Users can create a new container for short-term tasks. By default, there is no orchestration framework in place when running MVIS with Docker. Installing an orchestration framework, such as Kubernetes, allows users to automate the deployment process by setting up parameters to ensure that images are created under certain circumstances. While this is helpful in most situation, users do not need to have an orchestration framework to run MVIS with Docker; however, users will have to manually deploy or create images when necessary. Parent topic: MultiValue Integration Server User Guide Installing and configuring Docker for MVIS

The two methods for installing and configuring Docker for MVIS are deploying using shared volumes and deploying using Redis as a shared storage. Before using either of the two methods, the following prerequisites must be met: ▪ Docker must be installed on your system. See https://docs.docker.com/install/. ▪ The cm (MVIS) and cmadmin (MVIS Admin) tar ball Docker images must be downloaded.

Deployment using shared volumes (local storage)

Complete the steps below to deploy using shared volumes. 1. Load the mvis and mvisadmin Docker images by running these commands: docker image load -i cm-1.3.0_xxxxx.tar.gz docker image load -i cmadmin-1.3.0_xxxxx.tar.gz 2. (Optional) Tag the mvis and mvisadmin Docker images by running these commands: docker tag cm:latest cm:1.3.0.xxxxx docker tag cmadmin:latest cmadmin:1.3.0.xxxxx

28 Deployment using shared volumes (local storage)

3. Verify that the Docker images exist by running the following command: docker images For example:

4. Create a folder on your local machine for sharing data to the container and then add the cm.ini file to that folder. For example: ▪ For Windows: C:\shareddockerdata ▪ For Linux: /home/blwmv/demo 5. Create a new folder named u2rest inside the folder you created in the above step. 6. Run the mvis and mvisadmin containers using the commands below: For Windows:

docker run -d -p 7077:7077 -e "JAVA_OPTS=-DTYPE=MVCM -DFS_DIR=/data/" -v c:\shareddockerdata:/data cmadmin:1.3.0_xxxxx docker run -d -p 7171:7171 -p 7870:7870 -p 7871:7871 -p 7172:7172 -e "JAVA_OPTS=-DTYPE=MVCM -DFS_DIR=/data/" -v c:\shareddockerdata:/data cm:1.3.0_xxxxx For Linux:

docker run -d -p 7077:7077 -e "JAVA_OPTS=-DTYPE=MVCM -DFS_DIR=/data/" -v /home/blwmv/demo:/data cmadmin:1.3.0.xxxxx

docker run -d -p 7171:7171 -p 7870:7870 -p 7871:7871 -e "JAVA_OPTS=-DTYPE=MVCM -DFS_DIR=/data/" -v /home/blwmv/demo:/data cm:1.3.0.xxxxx Note that JAVA_OPTS is used for setting the environment variables we want to add. ▪ -DFS_DIR specifies the volume.

▪ /data is used for retrieving/modifying the cm.ini and other files or folders such as u2rest and mvis.log. Using this docker run command we have mounted /data/ to the c:\shareddockerdata shared folder (for Windows) or to the /home/blwmv/demo shared directory (for Linux).

Note: You must provide recursive write access to the shared volume so that the container process can read and write on the shared volume before running the container.

29 Chapter 8: Using MVIS with Docker containers

7. Confirm that the mvis and mvisadmin containers are running using this command: docker container ps For example:

8. Go to http://machine_name:7077 and change the host name to the machine name or IP address of the mvis container. For example:

Tip: To get the mvis container IP address use this command:

docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}'

9. Run the command below to check cm.ini and its contents: docker exec -it /bin/sh For example:

10. Add an account using UniVerse or UniData and then verify whether or not the account is available.

Deploying using Redis as a shared storage and notification server

Use Redis as a shared storage for the cm.ini file and the u2rest folder.

30 Deploying using Redis as a shared storage and notification server

1. Deploy Redis as docker image using the following command: docker run --name recorder-redis -p 6379:6379 -d redis:alpine 2. First run the mvisadmin container and then run the mvis container using the following commands: docker run -d -p 7077:7077 -e "JAVA_OPTS=-DTYPE=MVCM -DREDIS_HOST=10.115.15.27" cmadmin:1.3.0.xxxxx

docker run -d -p 7171:7171 -p 7870:7870 -p 7871:7871 -e "JAVA_OPTS=-DTYPE=MVCM -DREDIS_HOST=10.115.15.27" cm:1.3.0.xxxxx where DREDIS_HOST is the IP address of the container/server machine where Redis is running. 3. Check the configuration on the Rest server page. For example, the configuration location as illustrated in the image should contain "RedidKey:u2rest".

4. Using one of the links below, download and install the Redis database application which is used to manage the data. ▪ Redily :- https://www.softpedia.com/get/Internet/Servers/Database-Utils/Redily.shtml ▪ Redislabs:- https://redislabs.com/blog/so-youre-looking-for-the-redis-gui/ 5. Open Redily and click Add Connection from the Connections menu and then enter the Name and Address as illustrated below. The Address can be expressed as the machine name or IP address of the machine.

31 Chapter 8: Using MVIS with Docker containers

6. Click Add when done. 7. Double-click the newly created connection to connect.

cm.ini displays in the Keys panel as illustrated below:

8. Add a data resource (Members) and refresh the connection. The u2rest/rest_test.json key displays in the Keys panel as illustrated below:

Setting logging levels

Complete these steps to set the logging level to debug when running mvisadmin in the container. 1. To set the logging levels, run the following commands: docker run -d -p 7077:7077 -e "JAVA_OPTS=-DTYPE=MVCM -Dlogging.level.com.rs.mv=DEBUG

32 MVIS and Docker examples

-DFS_DIR=/data/" -v /home/blwmv/demo:/data cmadmin:1.3.0.xxxxx

docker run -d -p 7171:7171 -p 7870:7870 -p 7871:7871 -e "JAVA_OPTS=-DTYPE=MVCM -DFS_DIR=/data/" -v /home/blwmv/demo:/data cm:1.3.0.xxxxx Note that -Dlogging.level.com.rs.mv=DEBUG is used to check the detailed logs in MVIS admin. 2. Run the following command to view the mvis.log which resides in the /opt/cm/logs folder: docker exec -it /bin/sh For example:

3. You can also run the container by overriding the properties in the application.properties file. For example: docker run -d -p 7077:7077 -e "JAVA_OPTS=-DTYPE=MVCM -Dserver.servlet.session.timeout = 1200 -DFS_DIR=/data/" -v /home/blwmv/demo:/data cmadmin:1.3.0.xxxxx Note that server.servlet.session.timeout is the server property in application.properties file. MVIS and Docker examples

In the following example, the MVIS image is run as a container using the Docker run command, passes in a Java options environment variable that will use Azure Blob storage and Azure Service Bus, and logs to Application Insights. See Installing MVIS as a Docker container image for more information. $ sudo docker run -p 7171:7171 -p 7870:7870 -p 7871:7871 -e "JAVA_OPTS=-DTYPE=MVCM\ -DBUCKET_NAME=cm-config -DCONFIG_NAME=cm.ini\ -DAZURE_SB_SAS_KEY=\ -DAZURE_SB_NAMESPACE=\ -DAZURE_ACCOUNT=\-DAZURE_ACCOUNT_KEY= -DCLOUD_LOGGING=AZURE\ -DAPPLICATION_INSIGHTS_IKEY=" cm

Note: When opening Docker containers in Windows, this syntax can be used from the Windows command prompt, but it is not valid syntax for the PowerShell prompt.

In the following example, the MVIS Admin image is run as a container using the Docker run command, passes in a Java options environment variable that will use Azure Blob storage and Azure Service Bus, and logs to Application Insights:

33 Chapter 8: Using MVIS with Docker containers

$ sudo docker run -p 7077:7077 -e\ "JAVA_OPTS=-DTYPE=MVCM -DBUCKET_NAME=cm-config\ -DCONFIG_NAME=cm.ini -DAZURE_SB_SAS_KEY=\ -DAZURE_SB_NAMESPACE=\ -DAZURE_ACCOUNT=\ -DAZURE_ACCOUNT_KEY=\ -DCLOUD_LOGGING=AZURE -DAPPLICATION_INSIGHTS_IKEY=" cmadmin

Note: When opening Docker containers in Windows, this syntax can be used from the Windows command prompt, but it is not valid syntax for the PowerShell prompt.

34 Chapter 9: Configuring MVIS

Use the MVIS Web Admin UI or cm.ini file to monitor accounts and performance and perform administration tasks. Use the MVIS Web Admin UI to restart, disable, and delete accounts, edit account details, enable SSL, enable different forms of logging, and make other edits to a MVIS configuration. You can also use MVIS to perform these functions with your own client through the MVIS Admin REST API. To configure MVIS, perform the following tasks: • Adding an account to MVIS Complete these instructions to create an account definition. • Adding REST endpoints From the MVIS Web Admin UI, you can add REST endpoints. • Converting your WebDE configuration file to a cm.ini configuration file You can convert an existing WebDE 5.3 JavaScheduler.ini configuration file to a MVIS cm.ini configuration file using the WebDE Configuration Conversion Tool (webdeConverterTool.jar). • Enabling SBXA for MVIS To enable SBXA for MVIS you need to create and properly configure a new account in MVIS. • Modifying connection defaults You can check and edit the default connection details in the MVIS Web Admin UI. • Monitoring connections MVIS features a performance monitor that records statistics on the requests processed for each account and displays results in a table. These statistics provide data to help you manage request processing and determine whether to make adjustments. • Viewing MVIS logs You can view log information in the MVIS Web Admin UI and in individual log files stored in the MVIS directory. • Vanity URLs Vanity URLs allow you to provide a more descriptive, identifiable name alias for APIs rather than using the existing data resource or subroutine name. This enables consumers of the API to more readily identify what an API provides. Parent topic: MultiValue Integration Server User Guide Adding an account to MVIS

Complete these instructions to create an account definition.

Note: If MVIS encounters a failure when establishing a connection to an account, it will decrease the connection attempts to that account to limit the possibility of the data server being overloaded with connection attempts during a failure scenario.

1. From the MVIS Web Admin UI, select Configuration → Accounts, and then click Add account. 2. In the Account Configuration window, click one of the following tabs: ▪ Server Details ▪ Optional Settings

35 Chapter 9: Configuring MVIS

▪ Monitor Warnings ▪ Environment Variables ▪ SB Connections 3. In the Server Details tab, complete the following fields:

Field Action

Account Name Specify a name for the account. This does not have to match the name of the account on the data server.

MV Server Name Specify the host name or IP address of the data server where the account resides.

MV Server Port Specify the unirpc service port for the data server where the account resides by entering a value between 1 and 65535. The default value is 31438.

Protocol Specify one of the following protocols that this account should use when being accessed from a client: ▪ UNIOBJECTS: Select this option to open the account pool to UOJ and UO.NET clients. This option is selected by default. ▪ REST: Select this option to open the account pool to REST clients.

Account Path Specify the path to the MV account on the data server.

Connection String Specify the entry from the unirpcservices file on the data server where the specified account is located. The default is uvcs for UniVerse and udcs for UniData. User ID Specify the operating system-level user ID of the user that will be used to connect to the data server for pooled connections to the account.

User Password Specify the password to the operating system-level user ID that will be used to connect to the data server for pooled connections to the account. The password will be encrypted when saved.

SSL connection(s) to MV Select this drop-down to activate SSL between MVIS and the Server data server hosting the account. Note, the database must be configured to allow SSL by the connection string service defined in the unirpcservice. Additionally, Trust Store Enabled must be enabled from the Security tab to enable SSL at the account level.

SSL hostname validation When set to enabled, this specifies that the SSL connections, from MVIS to the data server, for the account require the hostname on the data server's SSL certificate match the server name for the account. By default, this is set to disabled.

Execution Timeout Specifies the number of seconds that the connection to the MV (seconds) server will wait for a response before timing out and throwing an error.

36 Adding an account to MVIS

Field Action

MV Server Keep Alive Select this check box to specify that a server-level keep alive heartbeat should be sent at a recurring interval between MVIS and the connections to the data server for the account. This option enables MVIS to keep its persistent connections alive, even when routers or cloud-based networks actively terminate idle connections. This option is enabled by default.

MV Server Keep Alive Specify the interval, in milliseconds, to send a server-level keep Interval (milliseconds) alive heartbeat between MVIS and the connections to the data server for the account. The default is 60000 milliseconds.

Encoding Specify the encoding for the connections to this account.

Minimum Pool Size Specify the minimum number of connections in the connection pool for the account.

Maximum Pool Size Specify the maximum number of connections maintained in the connection pool for the account.

Test Connection Click this button to test your account connection settings.

4. In the Optional Settings tab, complete the following fields:

Field Action

Service Definition Name If you want to use an existing, shared REST server definition, type the name of the account whose service should be used in the current account.

Deactivate account Select this check box to disable the account.

Enable server-side Select this check box to turn on COMO logs at the data server for logging for this account the connections to the account.

Enable TCP Keep Alive Select this check box to turn on the TCP keepalive socket option between UO Clients and between MVIS and its clients. MVIS

Enable development Select this check box to enable developer mode for this account. mode for this account This allows all requests to get the latest version of compiled code rather than using a cached version of the object code. Development mode causes database processes to restart after each method call, while allowing newly compiled code to be picked up. This mode carries a performance overhead, as the associated database processes are ended and recreated after each method call.

Note: Development mode is not recommended for production use.

5. In the Monitor Warnings tab, complete the following fields:

Field Action

Average Response Time Specifies an average response time for requests. If this response (Lifetime) time is exceed, the monitor warning level is triggered.

37 Chapter 9: Configuring MVIS

Field Action

Average Response Time Specifies the average response time for requests to the account. (Interval) If this response time is exceed during a monitor refresh interval, the monitor warning level is triggered.

Requests Waiting Specifies the number of requests that are waiting for service. If this response time is exceed, the monitor warning level is triggered.

Slow Request Specifies the amount of time that a process can run before the monitor warning level is triggered.

6. In the Environment Variables tab, perform the following steps to add a variable: a. Click Add Variable. b. In the Variable Name field, enter a name, and click OK. c. In the Variable Value field, enter a value for your variable, and then click OK. d. Click OK. 7. In the SB Connections tab, complete the following fields to setup your System Builder connection. Click Test SB Credentials when done to confirm the connection.

Field Action

SB User ID Specifies an SB+ user id to use in REST calls that require an SB + environment. Note that this user must have a default terminal definition of DEFAULT.TERM. Without this terminal definition, the connection could get assigned to the wrong connection type and cause the MVIS connection to hang.

SB Password Specifies the password for the SB+ user to use in REST calls that require an SB+ environment.

SB System ID Specifies the name of the SB+ system id to use in REST calls that require an SB+ environment.

8. Click OK. Parent topic: Configuring MVIS Adding REST endpoints

From the MVIS Web Admin UI, you can add REST endpoints. There are two types of endpoints that you can create: ▪ Data resources ▪ Subroutines When you create a REST endpoint that calls a subroutine, you can optionally specify a dynamic array structure for mapping to and from JSON for any of the subroutine parameters. • Creating REST data resources with MVIS Create a REST data resource if you want to create, read, update, or delete a file. • Calling data resources with MVIS After you've created a data resource, use your browser to call the data resource. • Optimistic concurrency control MVIS implements optimistic locking to prevent concurrent updates to the same data.

38 Creating REST data resources with MVIS

• Creating REST subroutine endpoints with MVIS You can create REST endpoints that invoke a BASIC subroutine on the data server. • Calling BASIC subroutines with MVIS • Sharing REST server endpoints REST server endpoints can be shared across multiple accounts. Complete these steps to share an existing REST server endpoint for an account to another account. • Importing a U2 REST server You can import an existing U2 REST server into MVIS. When importing an existing U2 REST server, all associated Data Resources, Subroutines, Dynamic Arrays and security configurations are exposed to MVIS. • Invoking the health check endpoint in U2REST MVIS provides a health check REST endpoint, which can be used to check if the MVIS REST server is running. Users can quickly check that the server is available. Parent topic: Configuring MVIS

Creating REST data resources with MVIS

Create a REST data resource if you want to create, read, update, or delete a file. 1. From the MVIS Web Admin UI, select Administration → REST Server → Accounts → Data Resources. 2. Click Add Data Resource. 3. From the Data Resource window, enter the name of a U2 file in the Data Resource field. 4. In the Data Resource Name field, enter a name for the data resource. 5. Select the fields that you want to include in the data resource. 6. A foreign key is a field that is used in the TRANS virtual field to bring data from another file into the host. If you want to link your data resources from related files through the use of a foreign key, select the check box in the F/K column that is associated with the dictionary item you selected in the previous step. The linked file is displayed in the Joined Files tab. 7. To change the name of your linked file, from the Joined Files tab, enter a new name in the Foreign Key field. 8. For additional information on the sub-resources, click the Data Subresources tab. 9. Click OK.

Tip: To access the OpenAPI 2.0 definition for a specific endpoint, click the Swagger icon that is displayed in-line with the data resource definition. In addition, you can also use the MVIS administrative REST endpoints to create REST data resources. These administrative endpoints can be accessed by clicking the Swagger icon from the bottom left-hand corner of the MVIS Web Admin UI. The Swagger Editor is also available for generating client- and server-side code to assist with mocking. To open the Swagger Editor, click the Swagger icon that is displayed in-line with the account name in the REST Server > Accounts section.

Parent topic: Adding REST endpoints

39 Chapter 9: Configuring MVIS

Calling data resources with MVIS

After you've created a data resource, use your browser to call the data resource. 1. Open a browser window. 2. Enter the following URL: http://MVIS_location:port/account/data_resource_name where: ▪ MVIS_location is the location of your MVIS. ▪ port is the port number located in the REST Server Status section. ▪ account is the account that is associated with the data resource. ▪ data_resource_name is the name of the data resource. 3. Press Enter. The data is returned in a JSON format in your browser.

Note: When calling data resource endpoints with select criteria, you must use spaces around the comparison operators in the select clause. For example, to select records with the last name of Smith, use the following format: http://server/account/file?select=lastName = “Smith”

Parent topic: Adding REST endpoints

Optimistic concurrency control

MVIS implements optimistic locking to prevent concurrent updates to the same data. Optimistic locking is a means of ensuring that no locks are put on a resource when it is read. However, when changes to the resource are ready to be written back, MVIS first locks it and then checks to see whether the resource has been changed since it was first read. If a change occurs, an optimistic locking violation error is thrown. Since changes (including update, delete, and create requests) are generally much less frequent than reads, this technique improves performance and scalability, while at the same time guaranteeing data consistency.

The u2version field

The u2version field holds a calculated value when a data resource is read and sent back to the client as a name/value pair. When the client wants to make a change to the resource, the HTTP PUT or HTTP DELETE request must include the original u2version value in the If-Match HTTP header field. The MVIS server uses this value to check against the current data on the U2 server. If they match, it allows the update or delete request to be processed; otherwise, it sends back an HTTP 412 error indicating an optimistic locking violation error has occurred. At this time, the client must re-read the data and try the update again. A data resource shares the same u2version value with all of its sub-resources. Thus, when you update a sub resource, even though it may not have changed since first read, if the top-level resource or any of its sub-resources has changed, the update fails. The same process is true for a top-level resource. For more information on If-Match, see the HTTP PUT method, HTTP DELETE method, and HTTP PATCH method topics in Chapter 7: U2 RESTful Web Services Developer of the Rocket U2 DBTools User Guide.

40 Creating REST subroutine endpoints with MVIS

Parent topic: Adding REST endpoints

Creating REST subroutine endpoints with MVIS

You can create REST endpoints that invoke a BASIC subroutine on the data server. 1. From the MVIS Web Admin UI, select Administration → REST Server → Accounts → Subroutine Resources → Subroutines, and then click Add Subroutine. 2. In the Subroutine Details tab from the Subroutine Service window, complete the following fields:

Field Action

Subroutine Name Enter the subroutine name.

Add Paramter Click the Add Parameter button to add the required number of parameters for your subroutine.

3. Click the Add Parameter button to add the required number of parameters for your subroutine. Complete the following fields for each parameter:

Field Action

Name Specify a parameter name.

Parameter Type Specify the type of parameter, whether input, output or in/out.

Data Type Specify the data type for the parameter, whether string, json or dynamic array.

Dynamic Array Name (Optional) Specify the name of a dynamic array associated with the input parameter.

Tip: Parameter positions in the list can be adjusted by dragging parameters up or down in the parameters list.

4. To use MVIS to optionally store BASIC subroutine source code in the subroutine definition file, which allows the MVIS Web Admin UI and Admin REST API to upload, compile, and catalog the subroutine source code to the specified account, in the Optional Code tab, complete the following fields:

Field Action

Source Directory Specifies the name of the directory where the source code is uploaded.

Create source Specifies to create the source directory if a source directory does directory if it doesn't not exist. exist

Allow to compile and Specifies whether to upload, compile, and catalog the source code catalog subroutine from the Source code tab on a save action. code

Compile Options Specifies any optional compile flags that should be sent to the compile operation.

41 Chapter 9: Configuring MVIS

Field Action

Catalog Options Specifies any optional catalog flags that should be sent to the catalog operation. The following catalog commands are issued by default: ▪ UniData: CATALOG ProgramFile SubroutineName FORCE ▪ UniVerse: CATALOG ProgramFile *SubroutineName

Note: For UniVerse PICK flavored accounts, the LOCAL catalog option should be used (this will result in the following command being executed: CATALOG ProgramFile SubroutineName LOCAL)

Source code Specifies the source code for the subroutine endpoint definition

5. Click OK. 6. To add a dynamic array, in the Dynamic Arrays section, click Add Dynamic Array. 7. In the Dynamic Array window, enter the name of the dynamic array in the Dynamic Array Name field, and then click OK. 8. Click Add Field and complete the following fields:

Field Action

Name Enter the name of the field in the dynamic array.

Location Enter the location of the field in the dynamic array.

Type Enter the type of field. Valid types are: ▪ s - Single-valued ▪ mv - Multivalued ▪ ms - Multi-subvalued

Association Associations are tied to specific fields. If you've selected a field that contains an association, the association will be displayed in the Association column.

Sub Association Sub-level of associations. Sub-associations will display in the Sub Association column.

9. To import a file dictionary as a new dynamic array definition, click the Import tab 10. From the Import tab, enter the name of a U2 file in the U2 file name field. Click OK. 11. Select the check box next to the dynamic array that you want to import, and click Import. The dynamic array is displayed in the Dynamic Array Details tab. 12. Click OK.

42 Calling BASIC subroutines with MVIS

Tip: To access the OpenAPI 2.0 definition for a specific endpoint, click the Swagger icon that is displayed in-line with the subroutine resource definition. In addition, you can also use the MVIS administrative REST endpoints to create REST subroutine resources. These administrative endpoints can be accessed by clicking the Swagger icon from the bottom left- hand corner of the MVIS Web Admin UI. The Swagger Editor is also available for generating client- and server-side code to assist with mocking. To open the Swagger Editor, click the Swagger icon that is displayed in-line with the account name in the REST Server > Accounts section.

Parent topic: Adding REST endpoints

Calling BASIC subroutines with MVIS

Prerequisites

▪ Have a BASIC subroutine that is globally or locally cataloged and compiled in your U2 account. If a subroutine does not exist on the server, use the Optional tab in the Subroutine Editor.

Procedure

1. From the MVIS Web Admin UI, select Administration → Configuration → Accounts, and then click Add Account. 2. Create an account with the Protocol field set to REST. 3. Click OK. 4. Create a subroutine. 5. Verify your REST port by selecting Administration → Configuration → Ports. By default, the REST port is set to 7171. 6. Start MVIS. 7. In your browser, enter the URL, for example: http://localhost:7171/account_name/ where account_name is the name of the account definitions created in Step 2. A list of available subroutines and data resources is displayed. 8. From the List Resource page, click the name of the subroutine to see the input fields, and then click Call Service. If the subroutine call was successful, the results will display. If it failed, an exception or error will be displayed. Parent topic: Adding REST endpoints

Sharing REST server endpoints

REST server endpoints can be shared across multiple accounts. Complete these steps to share an existing REST server endpoint for an account to another account. These instructions assume that you have multiple accounts and an existing REST server endpoint on one of the accounts.

43 Chapter 9: Configuring MVIS

1. From the MVIS Web Admin UI, select Administration → Configuration → Accounts, and then click the Edit account button for the account that contains the REST server definition you want to share. 2. In the Account configuration dialog box, select the Optional Settings tab. 3. Type a name for the REST server definition to share in the Service Definition Name text box and click OK. This is the name you will use when sharing the REST server definition to anotherd account. 4. Click the Edit account button for the account to which you want to share the REST server definition. 5. In the Account configuration dialog box, select the Optional Settings tab. 6. Type the name of the shared REST server definition in the Service Definition Name text box and click OK. This is the same name you used when sharing the REST server definition from the first account. 7. Confirm that the REST server definition has been shared. From the Administration menu, select REST Server → Accounts and confirm that any Data Resources and Subroutine Resources defined on the sharing account now also exist on the shared to account. Parent topic: Adding REST endpoints

Importing a U2 REST server

You can import an existing U2 REST server into MVIS. When importing an existing U2 REST server, all associated Data Resources, Subroutines, Dynamic Arrays and security configurations are exposed to MVIS. To import an existing U2 REST server, you must first export the REST server from the U2 RESTful Web Services Toolkit.

Note: ▪ U2 REST servers imported from the U2 RESTful Web Services Toolkit will have service definition files that are named after the U2 REST Resource Folder(s) hosted by the U2 REST server. In MVIS, service definition files are named after the cm.ini entry that a service is representing. As such, you should ensure that your cm.ini has an entry that corresponds to each U2 Resource Folder that you are importing from the U2 REST server. The one exception to this is if the cm.ini entry is using a Shared Definition. In such cases, the Shared Definition name should be represented by a U2 Resource Folder being imported. ▪ Only one U2 REST Server cay be imported into MVIS. ▪ Any rest endpoints defined on a U2 REST Server can be imported with the U2 RESTful Web Services Toolkit and then subsequently deployed.

1. In the U2 RESTful Web Services Toolkit, right-click the REST server you want to export and select Export. The Export REST Server dialog box displays. 2. Select the REST server you want to export from the Available REST Servers check-boxes and then click Finish. 3. Open the MVIS Web Admin UI and select REST Server from the MENU. 4. Click Browse... from the Export/Import section and select the .zip file where is the name of the U2 REST Server that was exported from the U2 RESTful Web Services Toolkit.

44 Invoking the health check endpoint in U2REST

5. Check the Deployment from Web DE or RESTful Services Toolkit check box, and specify the name of the rest server that you are importing from the U2 RESTful Web Services Toolkit.

Note: When importing from the .zip file, by default MVIS Admin avoids overwriting any existing service definition files. To override this behavior, click the Force overwrite existing files check box.

6. Click Import. The REST server is imported into MVIS and all associated Data Resources, Subroutines and Dynamic Arrays display in a new account on the REST Server page.

Note: The security configuration files (files with extensions .realm and .acl) are automatically re-encrypted upon import. This means that they will be decrypted using the U2 RESTful service algorithm and then re-encrypted using the MVIS encryption algorithm. The files names are also changed from server_name to cm.rest and are moved to the MVIS REST config location.

Parent topic: Adding REST endpoints

Invoking the health check endpoint in U2REST

MVIS provides a health check REST endpoint, which can be used to check if the MVIS REST server is running. Users can quickly check that the server is available. However, in most cases, an automated service will run these health checks at a preconfigured interval and take an automated action if a problem is detected. For example, if a server is acting as part of a cluster and it fails to respond, the server will be taken out of the cluster and automatically replaced by a new instance. The MVIS REST server provides a health check endpoint at the following location:

http://host:port/healthcheck This endpoint is automatically started when MVIS is configured to serve a REST API, so no configuration is required to enable the health check.

The endpoint can be invoked by a using a GET request. It will return an HTTP Status Code of 200 OK and a payload of OK. The following is an example of a health check request and response:

GET http://host:port/healthcheck

HTTP/1.1 200 OK Content-Length: 2

OK Parent topic: Adding REST endpoints Converting your WebDE configuration file to a cm.ini configuration file

You can convert an existing WebDE 5.3 JavaScheduler.ini configuration file to a MVIS cm.ini configuration file using the WebDE Configuration Conversion Tool (webdeConverterTool.jar).

45 Chapter 9: Configuring MVIS

The WebDE Configuration Conversion Tool is included in your MVIS installation package. It searches your WebDe installation directories for the JavaScheduler.ini file and then converts it to a MVIS cm.ini configuration file.

1. Locate the JavaScheduler.ini configuration file in your WebDE installation directory and make a note of the location. 2. Locate the application.properties file in the \apiserver folder of your WebDE installation. 3. Run the following command from the command prompt: java -DFS_DIR=JavaScheduler_Path -jar webdeConverterTool.jar

where JavaScheduler_Path is the directory where the JavaScheduler.ini file resides. The program converts the JavaScheduler.ini file to a MVIS cm.ini configuration file. Additionally, this program also converts your WEBDE application.properties file to an MVIS Admin application.properties file.

Note: If you don't know the location of the JavaScheduler.ini file on your system, you can run the following command instead: java -jar webdeConverterTool.jar

This version of the command will search for the JavaScheduler.ini file in the following locations: ▪ the current working folder ▪ the path set in the U2WDE environment variable

▪ the C:\Windows folder on Windows and the /etc folder on Unix

Upon completion of the program, the new cm.ini file is saved in the same directory as the original JavaScheduler.ini file. Be aware that in many cases, names used for properties in the JavaScheduler.ini file have been changed in the cm.ini file. The table below lists the property names that have changed and indicates the new property name used in the cm.ini file: Table 2: JavaScheduler.in & cm.ini Property Mapping

JavaScheduler.ini cm.ini General Section IdleRemoveExecInterval idleConnectionCheckInterval MaxRestartWait maxPoolRestartWaitTime PoolingDebug connectionTracingEnabled SchedulerPort connectionManagerPort socketBackLog uoMaxServerRequestQueue usingTrustStore trustStoreEnabled sslKeyStore sslKeyStorePath sslTrustStore sslTrustStorePath ThreadSocketTimeOut uoClientConnectionTimeout AvgRespTime avgRespTimeThresholds AvgRespTimeIteration respTimeThresholds AcctRequestsQueued requestsQueuedThresholds usingssl uoSSLEnabled

46 Enabling SBXA for MVIS

JavaScheduler.ini cm.ini server mvServer Account Section server mvServer MinimumPoolSize minPoolSize MaximumPoolSize maxPoolSize SlowProcessTime slowRequestThreshold AvgRespTime avgRespTimeThresholds AvgRespTimeIteration respTimeThresholds AcctRequestsQueued requestsQueuedThresholds unirpcPort mvServerPort uniRpcTimeout mvServerConnectionTimeout como serverSideLoggingEnabled devmode devModeEnabled tcpKeepAlive uoClientTCPKeepAliveEnabled usingssl uoSSLEnabled

Parent topic: Configuring MVIS Enabling SBXA for MVIS

To enable SBXA for MVIS you need to create and properly configure a new account in MVIS. Complete these steps to enable SBXA for MVIS.

1. Complete the instructions in Adding an account to MVIS to add an account that will be used to enable SBXA. 2. Navigate to the MVIS installation directory (for Windows the default path is c:\u2\CM) and open the cm.ini file for editing. 3. Scroll to the cm.ini section for the new account you just created and assign appropriate values to the sbUserId, sbPassword, and sbSysId properties. For more information on cm.ini file properties, see Appendix A: cm.ini file properties. 4. In the MVIS Admin Console, edit the SB account and change the Protocol property value to REST. This step allows MVIS to encrypt the sbPassword you entered and forces a change in the account configuration to trigger the encryption action by MVIS. Parent topic: Configuring MVIS Modifying connection defaults

You can check and edit the default connection details in the MVIS Web Admin UI. 1. From the MVIS Web Admin UI, select Administration → Configuration. 2. From the MultiValue Integration Server Configuration section, select one of the following sections: ▪ Ports ▪ Control ▪ Security ▪ Logging

47 Chapter 9: Configuring MVIS

3. In the Ports tab, complete the following fields:

Field Action

MultiValue Specify the port number to access MVIS. The default port is 7870. Integration Server Port

HTTP Port Specify the port number associated with REST. The default port is 7171.

Monitor Port Specify the port number for the monitor. The default port is 7871.

4. In the Control tab, complete the following steps:

Field Action

Idle Connection Set the number of milliseconds that a connection to a backend data Timeout server can remain idle before it is flagged for removal. The default value (milliseconds) is 60000.

Idle Connection Set the number of milliseconds to wait before checking for and removing Check Interval backend data server connections whose idle time has exceeded the value (milliseconds) in Idle Connection Timeout. The default value is 60000.

Open Session Set the maximum amount of time to wait for a response from a data Timeout server connection before timing out. The default value is 1000. (milliseconds)

Connection This option logs detailed connection activity from MVIS to the data Tracing servers. This option is disabled by default.

Graceful This option sets whether the http server should be given time to Shutdown gracefully shutdown before stopping MVIS. This option is disabled by default.

Graceful Specify the timeout in milliseconds to use for the graceful shutdown of Shutdown the http server when Graceful Shutdown is enabled. The default value is Timeout 300000. (milliseconds)

max Connection Maximum number of attempts to create a connection pool for an account Attempts before the account is suspended. The default is 0.

REST Maximum Set the maximum size in bytes for a request payload for rest endpoints. Request Body Size The default is 200000 (200K bytes). (bytes).

48 Modifying connection defaults

Field Action

Rest Resources Set the number of services that will be cached by the running MVIS after Cache Size (items) they are loaded from disk or other configuration storage. The default is 50.

HTTP Idle Timeout Specify the number milliseconds before an idle http connection from a (milliseconds) REST client times out. The default is 30000 (30 seconds).

Max Server Specify the number of requests that can be queued on the listening Request Queue socket when accepting connections from UO clients. The default value is (UO) 50 requests.

5. In the Security tab, complete the following fields:

Field Action

SSL HTTP(s) Enable this option to use SSL on the MVIS's client-facing REST port. This option is disabled by default.

SSL Key Store Path Enter the location of the SSL certificate for MVIS to protect client-facing connections.

SSL Key Store Enter the password for the SSL keystore. Password

SSL Key Manager Enter the password for the REST Jetty server's KeyManagerFactory. If Password not specified, the SSL keystore password is used.

Trust Store Enabled Enable this property to enable the truststore. This property must be enabled to create a secure connection to the MV Server.

SSL Trust Store Enter the path of the truststore that MVIS will use to validate secure Path connections to the data servers. If left unspecified, the default truststore is employed.

SSL Trust Store Enter the password to the Java truststore specified in SSL Trust Store Password Path. The password should be encrypted.

Excluded Cipher Enter a space-delimited list of cipher suites to exclude when negotiating Suites SSL.

Excluded Protocols Enter a space-delimited list of protocols to exclude when negotiating SSL

HTTP Specify the type of HTTP authentication to use when securing Authentication connections to REST services hosted from MVIS. The following options are available: ▪ http-basic ▪ http-digest ▪ none

6. In the Logging tab, complete the following fields:

Field Action

Log Path Specify the path to the cm.log file.

49 Chapter 9: Configuring MVIS

Field Action

Log Levels Select one of the following logging levels: ▪ OFF ▪ TRACE ▪ DEBUG ▪ INFO ▪ WARNING ▪ ERROR By default, Info is selected.

7. Click Save. Many of these details are created either by default or by user designation during the installation process, and they are stored in the cm.ini configuration file. When you make changes in the MVIS Web Admin UI, the changes are reflected in the cm.ini file, which is by default in the cm folder. Parent topic: Configuring MVIS Monitoring connections

MVIS features a performance monitor that records statistics on the requests processed for each account and displays results in a table. These statistics provide data to help you manage request processing and determine whether to make adjustments. 1. From the MVIS Web Admin UI, select Administration → Configuration. 2. In the MultiValue Integration Server Status section, in the Host field, enter the hostname of the MVIS that you want to monitor. 3. Click Monitoring. 4. In the Monitor Control area, click Start. Your active account processes are displayed in a table in the lower portion of the MVIS Web Admin UI, where you can see requests, intervals, response times, and more. Slow processes are marked with yellow or red highlighting, depending on the severity of the slowdown. You can customize the triggers for fields being marked yellow and red; see Defining the yellow and red triggers of the monitor from the MVIS Web Admin UI, on page 51 or Defining the yellow and red triggers of the monitor, on page 51. Additionally, you can view a BASIC call stack trace for each account shown in your monitor. Click the View Stack button to the right of an account name to view a stack trace for that account. 5. If performance statistic logging was not automatically started by the startPerfStatsLoggingEnabled property in cm.ini file, you can turn on performance statistics logging by completing the following steps: a. Expand the Administration section in the Menu. b. Click Performance Statistics. c. Change the default Update Interval by clicking the value next to the label, or accept the default. d. Check Comma-Delimit Log if you want the log to be comma-delimited, or leave the box unchecked if you prefer that the log is written in table format. e. Check Log License Distribution if you want to log only the distribution of the number of requests processed by each database session or license, or leave the box unchecked if you want all of the performance statistics to be logged.

50 Defining the yellow and red triggers of the monitor from the MVIS Web Admin UI

f. Click the Start button to begin logging performance statistics.

Note: You cannot make changes to the Update Interval, Comma-Delimit Log, or Log License Distribution settings while the Performance Statistics Logger is running because the controls are disabled. Click the Stop button to make changes if the logger is already running, and then restart the logger.

Logs are written to the file perfstats.log, which is stored by default in the cm directory. For information on logging while running in the cloud, see Using MVIS in the cloud, on page 93. Parent topic: Configuring MVIS

Defining the yellow and red triggers of the monitor from the MVIS Web Admin UI

You can define the triggers for MVIS monitor from the MVIS Web Admin UI. Triggers monitor warnings when the overall average request response time exceeds these values. The average covers the period since the was last started.

1. In the MVIS Web Admin UI, expand Administration in the Menu. 2. Select Configuration. 3. In the Accounts area, select the account for which you want to define triggers, and to the right of the account, click the Edit accounts button. 4. Click Monitor warnings. 5. Edit the trigger details for Average Response Time (Lifetime), Average Response Time (Interval), Requests Waiting, and Slow Request as desired.

Defining the yellow and red triggers of the monitor

The triggers for the monitor can be modified in the file. Open the file in a text editor and add the following parameters to the appropriate account section:

Parameter Description Table field affected avgRespTimeThresholds=n1 n2 Triggers monitor warnings when Avg Response Time the overall average request (Lifetime) response time exceeds these values. The average covers the period since the was last started. n1 is the amount of time in milliseconds when the monitor displays yellow; n2 is the amount of time in milliseconds when the monitor displays red.

51 Chapter 9: Configuring MVIS

Parameter Description Table field affected requestsQueuedThresholds=n1 Triggers monitor warnings Requests Waiting n2 when the number of requests waiting to be served exceeds these values. n1 is the amount of time in milliseconds when the monitor displays yellow; n2 is the amount of time in milliseconds when the monitor displays red. respTimeThresholds=n1 n2 Triggers monitor warnings when Avg Response Time the average request response (Interval) time exceeds these values. The average covers a single monitor refresh interval. n1 is the amount of time in milliseconds when the monitor displays yellow; n2 is the amount of time in milliseconds when the monitor displays red. slowRequestThreshold=n1 Triggers monitor warnings when Slow Request any requests exceeds this value. n1 is the amount of time in milliseconds when the monitor displays red. Viewing MVIS logs

You can view log information in the MVIS Web Admin UI and in individual log files stored in the MVIS directory. Use the MVIS Web Admin UI to view logs.

You can also view log information in log files, which are stored in the logs folder in the cm directory by default. You can alter the default log location by changing the logpath property in the cm.ini file. MVIS automatically creates some logs during certain processes. These log files generally are stored in the logs directory in the cm folder. If you are running MVIS in a cloud environment, your logs can be stored in the cloud when MVIS is used in cloud-mode. For more information, see Using MVIS in the cloud, on page 93. Select one of the following methods to configure logging:

• Configuring performance statistics with the cm.ini file Configure the cm.ini file to automatically log performance statistics prior to starting MVIS. • Configuring performance statistics with the MVIS Web Admin UI Use the MVIS Web Admin UI to start logging performance statistics for MVIS. • Configuring logging to the console on Linux/UNIX Setup logging to the console (standard output) when you are troubleshooting MVIS or the MVIS Admin. This can also be useful when running MVIS or MVIS Admin containers from a container orchestrator, such as Kubernetes, where the orchestrator takes data written to the console and provides an interface to inspect it while the container is running. • Configuring logging to the console on Windows

52 Configuring performance statistics with the cm.ini file

Configuring performance statistics with the cm.ini file

Configure the cm.ini file to automatically log performance statistics prior to starting MVIS. About this task

Use this method to configure logging if you have several instances of MVIS running in a cluster or you need to get statistics from MVIS to Application Insights or CloudWatch. If you use the MVIS Web Admin UI to configure logging, you will have to login to each MVIS Admin and switch on performance statistic logging.

Using the cm.ini file allows new cluster nodes to send the statistics to Application Insights or CloudWatch when you start MVIS without additional tuning. This option can also be used if you are not running in a cluster or a cloud environment, but you want to start logging statistics after launching MVIS.

Procedure

1. Open the cm.ini file. 2. In the [Default] section of the cm.ini file, set the startPerfStatsLoggingEnabled to True. By default, the startPerfStatsLoggingEnabled property is set to False. When the startPerfStatsLoggingEnabled property is set to False, MVIS must be started and performance statistics logging must be turned on using the MVIS Web Admin UI.

If the startPerfStatsLoggingEnabled is set to True, MVIS sends the statistics with the default values for the Update Interval, Comma-Delimited Log, and Log License Distribution fields. These values can only be changed in the MVIS Web Admin UI.

Logs are saved to the Perfstats.log file, which is located in the cm directory. For information on logging to Application Insights, see Logging to Application Insights on Windows, on page 97 or Logging to Application Insights on Linux/UNIX, on page 97. For information on logging to CloudWatch, see Logging to Amazon CloudWatch on Windows, on page 106 or Logging to Amazon CloudWatch on Linux/UNIX, on page 107. Parent topic: Viewing MVIS logs

Configuring performance statistics with the MVIS Web Admin UI

Use the MVIS Web Admin UI to start logging performance statistics for MVIS. 1. From the MVIS Web Admin UI, select Administration → Performance Statistics. 2. From the Performance Statistic Logging Control window, click Start. 3. To configure additional settings, complete the following fields:

53 Chapter 9: Configuring MVIS

Field Action

Update Interval Specifies the delay in seconds between the data provided in the log entries. By default, the update interval is set to 1 second.

Comma-Delimit Log Select this check box to remove headers from the log and comma delimit the log entry. This option is ignored when performance statistics are sent to Azure Application Insights because values are sent as separate numeric metrics attached to a custom event. For information on logging to Azure Application Insights, see Logging to Application Insights on Windows, on page 97 or Logging to Application Insights on Linux/UNIX, on page 97. For information on logging to CloudWatch, see Logging to Amazon CloudWatch on Windows, on page 106 or Logging to Amazon CloudWatch on Linux/UNIX, on page 107.

Log License Distribution Select this check box to log the distribution requests for U2 licenses.

Parent topic: Viewing MVIS logs

Viewing and setting MVIS log levels

You can view and adjust log levels for MVIS in the MVIS Web Admin UI.

Procedure

1. From the MVIS Web Admin UI, select Administration → Configuration. 2. Expand the Log Level section. 3. Review your log level setting and make any desired changes by selecting the appropriate radio button. 4. Click Save.

Configuring logging to the console on Linux/UNIX

Setup logging to the console (standard output) when you are troubleshooting MVIS or the MVIS Admin. This can also be useful when running MVIS or MVIS Admin containers from a container orchestrator, such as Kubernetes, where the orchestrator takes data written to the console and provides an interface to inspect it while the container is running. 1. To enable logging to the console for MVIS, complete the following steps: a. Navigate to the MVIS installation directory, and find the start-cm.sh script. b. Open start-cm.sh with a text editor, and then add the following lines to enable logging to the console: export JAVA_OPTS=-DTYPE=MVCM -DCONSOLE_LOGGING=1 java $JAVA_OPTS -jar cm.jar 2. To enable logging to the console for the MVIS Admin, complete the following steps: a. Navigate to the MVIS installation directory and open the application.properties file with a text editor. b. In the [Logging] section, add the following property:

54 Configuring logging to the console on Windows

logging.console.enabled=true Parent topic: Viewing MVIS logs

Configuring logging to the console on Windows

Setup logging to the console (standard output) when you are troubleshooting MVIS or the MVIS Admin. This can also be useful when running MVIS or MVIS Admin containers from a container orchestrator, such as Kubernetes, where the orchestrator takes data written to the console and provides an interface to inspect it while the container is running. 1. To enable logging to the console for MVIS, complete the following steps: a. Navigate to the MVIS installation directory, and find the start-cm.bat script. b. Open start-cm.bat with a text editor, and then add the following lines to enable logging to the console: set JAVA_OPTS=-DTYPE=MVCM -DCONSOLE_LOGGING=1 java %JAVA_OPTS% -jar "c:\u2\cm\cm.jar" 2. To enable logging to the console for the MVIS Admin, complete the following steps: a. Navigate to the MVIS installation directory and open the application.properties file with a text editor. b. In the [Logging] section, add the following property: logging.console.enabled=true Logs from MVIS are now sent to the console. Parent topic: Viewing MVIS logs Vanity URLs

Vanity URLs allow you to provide a more descriptive, identifiable name alias for APIs rather than using the existing data resource or subroutine name. This enables consumers of the API to more readily identify what an API provides. Vanity URLs also allow you to assign multiple unique names to the same endpoint, thus allowing you to modify aspects of the same data resource (for example, changing pointers to the data sources or passing in different parameters) and define what the API provides for that particular vanity URL. • Setting-up vanity URLs Complete these instructions to configure a vanity URL. • Vanity URL data resource examples This topic provides multiple unique vanity URL data resource examples. • Vanity URL subroutine examples This topic provides multiple unique vanity URL subroutine examples. Parent topic: Configuring MVIS

Setting-up vanity URLs

Complete these instructions to configure a vanity URL. To configure a vanity URL:

1. Open the endpoints.yaml file and configure the following parameters:

55 Chapter 9: Configuring MVIS

Parameter Description display-name Use-case specific name to assign to the endpoint. method The method used for this endpoint operation. Available methods are GET, POST, PUT, DELETE, PATCH or HEAD. path Relative path to the resource. Named-variables are enclosed in brackets {} and are passed to the underlying database operation. Subroutines can be passed any named-variable but direct file operations must use the {id} of the record id. db-operation Database operation to perform when the endpoint is run. The following parameters must be configured, depending upon the specified db- operation: mvis-account: MVIS account upon which the specified db-operation is to be performed. read operations read a single record. Note that the path for the endpoint must include an {id} to the read operation. The following parameters apply: ▪ file-name: name of the file from which to read the record. ▪ fields: optional list of dictionary fields. If specified, then only the listed fields are returned from the read operation. Any existing output conversions for the field are applied to the record returned. ▪ template: Templates are used to return a subset of information contained within a record. If no template is specified, the entire record is returned. Templates are thyme-leaf based and are run in the TEXT TemplateMode. For more information, see https:// www.thymeleaf.org/doc/tutorials/3.0/usingthymeleaf.html#textual- template-modes. ▫ name: file name for the .template file to use. This file must exist in the CM\u2rest\ folder. ▫ one-based-record-indexing: (true|false) specifies whether to use one-based indexing for the record dynamic array returned from the read operation. the default is false. ▫ response-variable: (optional) If this variable is specified, then it can be used in writing the template file. Otherwise, the default variable is record.

56 Setting-up vanity URLs

Parameter Description write operations write a single record. Note that the path for the endpoint must include an {id} to pass to the write operation. The following parameters apply: ▪ file-name: name of the file to which to write the record. ▪ fields: a list of field objects used to process the write operation. The fields are: ▫ name: name of a dictionary field (if position is not specified). ▫ position: an integer indicating the attribute position (if name is not specified).

▫ type: type of attribute to write (either array or string). ▫ array-delimiter: delimiter to use to delimit the array type field (either VM or SM). ▫ binding: Currently only json-path is supported. ▫ json-path: a jsonpath expression that specifies from where in the json document payload the attribute should be extracted. For a jsonpath overview, see https://github.com/json-path/ JsonPath#getting-started. call operations call a subroutine. The following parameters apply: ▪ subroutine: cataloged name of the subroutine to run. For UniVerse, this might include a prefix (such as an *) for globally cataloged subroutines. ▪ params: (a list of parameter objects for the subroutine) ▫ name: the name of the subroutine parameter. ▫ position: an integer indicating the position of the subroutine parameter.

▫ type: the type of the subroutine parameter (either array or string). ▫ binding: type of binding to use when binding the subroutine parameter to the http request or response. Supported types are path-param, query-param, json-path, request-body, request-headers, request-header, response-body, template response-headers, response-header and status.

Tip: See Vanity URL data resource examples and Vanity URL subroutine examples to see many examples of how to configure the endpoints.yaml file for various types of operations.

Note: ▪ The path and display-name of an endpoint as defined in the yaml file should be unique across the file. ▪ A GET type of endpoint must have at least one field defined when retrieving all records.

2. Add the endpoints.yaml file to the CM\u2rest\ folder of your MVIS installation.

57 Chapter 9: Configuring MVIS

3. From the REST Server screen of the MVIS Web Admin UI, click the Refresh Endpoints button to update the endpoints (as defined in the endpoints.yaml file) displayed in the Data Resources and/or Subroutines lists for the account.

Tip: Users can be assigned access to data resource and subroutine endpoints from the REST Server screen of the MVIS Web Admin UI (select REST Server Security Configuration > Define Access Control). See Defining Access Control for more information.

Parent topic: Vanity URLs

Using Thymeleaf to create templates

The following information will help you get started with creating a Thymeleaf template for use with Vanity URLs. For more information, see https://www.thymeleaf.org/doc/tutorials/3.0/ usingthymeleaf.html#textual-template-modes.

Note: See Vanity URL subroutine examples for more examples of using Thymeleaf templates with Vanity URLs.

Definitions

Literal string

Now you are looking at a template file.

Numeric literal

The year is 1492.

Boolean literal

Iteration in Thymeleaf

In Thymeleaf, iteration is achieved using the th:each attribute. One thing to note about this attribute is that it allows iteration over different data types, such as: ▪ objects implementing java.util.Iterable ▪ objects implementing java.util.Map ▪ arrays ▪ any other object is treated as though it were a single-valued list containing one element Now we can invoke the th:each attribute with the data we set up in our example above:

This code snippet shows the th:each iterating over the list of students. The model attribute is accessed using the ${} notation, and each element in the list is passed to the body of the loop via the student variable

58 Using Thymeleaf to create templates

Thymeleaf also employs a useful mechanism to keep track of the iteration process via the status variable. The status variable provides the following properties: ▪ index: the current iteration index, starting with 0 (zero). ▪ count: the number of elements processed thus far. ▪ size: the total number of elements in the list. ▪ even/odd: checks if the current iteration index is even or odd. ▪ first: checks if the current iteration is the first one. ▪ last: checks if the current iteration is the last one. Now we can explore how the status variable works in our example:

font-weight: bold;'" th:alt-title="${iStat.even}? 'even' : 'odd'">

In the example above we included the iStat.odd property to evaluate the condition and set a bold style for the current row. The same is done on the next evaluation, but this time we used iStat.even to print a value via the alt-title HTML attribute. In we were to omit the explicit creation of the status variable (presented as iStat in our example), we could invoke our status variable using studentStat, which is the aggregation of the variable student with the suffix Stat.

// code placeholder [ [# th:each="rec , iterState: ${record}"] { "firstName": "[(${rec[1]})]", "lastName": "[(${rec[2]})]", "address": "[(${rec[5]})]", "status": "[(${rec[17]})]", "cardNums":[ [# th:each="item, iterState: ${rec[18]}"] "[(${item})]"[(${iterState.size-1 > iterState.index}? ',':'')] [/] ] }[(${iterState.size-1 > iterState.index}? ',':'')]

[/] ]

${rec[1]} - this is used to identify the data in the first field which is being selected in the select list provided to the vanity URL. Or, in cases where no select list is provided, this retrieves the first field of the data file (Location).

${rec[2][1]} - this retrieves first data value in MultiValue field 2. ${rec[2][1][1]}- this retrieves first subvalue of the first data value in MultiValue field 2.

59 Chapter 9: Configuring MVIS

Using u2version in PUT and PATCH requests

When using the PUT or PATCH types, the u2version field is required in the PUT or PATCH request.

Note: RESTful PUT and POST requests on Data Resource are limited by client-side optimistic locking to maintain data integrity. Optimistic locking in MVIS is achieved using the u2version id fetched as a part of a RESTful GET request from the Data Resource. Previously, this was a required field in DELETE RESTful operations as well. However, since a DELETE RESTful call is an idempotent request, u2version is no longer a required field for either the Data Members or Vanity URLs for a Data Resource.

The procedure below illustrates updating a record using a PUT vanity endpoint. Note that a similar procedure could be used for PATCH vanity endpoints. The instructions below assume the hypothetical existence of an account named XDEMO.

1. Create the endpoints.yaml file as shown below. Note that the PUT endpoint requires a corresponding GET endpoint. Also note that the fields in the two endpoints are the same and are presented in the same order. - display-name: get-customers method: GET path: /hr/get/customers/{id} db-operation: mvis-account: XDEMO read: file-name: MEMBERS field-names: - FIRST_NAME - CITY - STATE - ZIP - display-name: put-customers method: PUT path: /hr/put/customers/{id} db-operation: mvis-account: XDEMO write: file-name: MEMBERS fields: - name: FIRST_NAME position: 1 type: string binding: json-path json-path: $.FIRST_NAME - name: CITY position: 2 type: string binding: json-path json-path: $.CITY - name: STATE position: 3 type: string binding: json-path json-path: $.STATE - name: ZIP position: 4 type: string binding: json-path json-path: $.ZIP

60 Filtering and sorting Get type Vanity URL results

2. From the MVIS Web Admin UI, select Rest Server → Accounts → Data Resources. 3. Go to the get-customers vanity endpoint and click the View Swagger icon. 4. Select the GET customers member from the list of Members and then click Try Me Out. 5. Click Execute to get the u2version (displayed in the Response Body). 6. Back in the MVIS Web Admin UI, go to the put-customers vanity endpoint and click the View Swagger icon. 7. Select the put-customers operation from the list of Members and then enter the u2version in the If-Match text box. For more information on the If-Match text box, see Optimistic concurrency control. For further information, see the HTTP PUT method, HTTP DELETE method, and HTTP PATCH method topics in Chapter 7: U2 RESTful Web Services Developer of the Rocket U2 DBTools User Guide. 8. Enter a record ID in the id text box. 9. Enter a record in the body text box. For example: { "FIRST_NAME": "Bill", "CITY": "Denver", "STATE": "CO", "ZIP": "80108", } 10. Click Execute to add the record.

Filtering and sorting Get type Vanity URL results

Review the instructions below to learn how to filter and sort GET type Vanity URL results. The instructions below assume the hypothetical existence of an account named XDEMO.

1. Create the endpoints.yaml file as shown below. - display-name: get-membersallrecords-1 method: GET path: /hr/membersAllRecords db-operation: mvis-account: XDEMO read: file-name: MEMBERS field-names: - FIRST_NAME - CITY template: name: "employees1.template" one-based-record-indexing: true 2. Add the employees1.template file illustrated below to the u2rest directory of your MVIS installation. [ [# th:each="rec , iterState: ${record}"] { "firstName": "[(${rec[1]})]", "city": "[(${rec[2]})]" }[(${iterState.size-1 > iterState.index}? ',':'')]

[/] ] 3. From the MVIS Web Admin UI, select Rest Server → Accounts → Data Resources. 4. Go to the get-membersallrecords-1 vanity endpoint and click the View Swagger icon.

61 Chapter 9: Configuring MVIS

5. Select the GET membersallrecords member from the list of Members and click Try it out. 6. Enter your select and sort criteria in the select and sort text boxes of the Parameters section. For example, if you want to search for all members in cities that begin with the letters DE, you could enter CITY=DE in the select text box. If you then wanted to sort results by city, you could enter BY CITY in the sort text box. 7. Click Execute to display your sorted results.

Creating vanity endpoints when using Docker shared volumes

Complete these steps to create vanity endpoints when using Docker shared volumes. 1. Run both the cm and cmadmin containers as described in Deployment using shared volumes. 2. Create a folder named u2rest in the following folder: ▪ For Windows: c:\shareddockerdata ▪ For Linux: /home/blwmv/demo 3. Add one data resource (such as Members) and confirm that the proper json file is created in the / data folder. For example:

4. Create the endpoints.yaml file in the u2rest folder and then add endpoints to the endpoints.yaml file. Confirm in the UI that the endpoints are created for the account. For example:

Creating vanity endpoints when using Docker Redis cache

Complete these steps to create vanity endpoints when using Docker Redis cache.

62 Vanity URL data resource examples

1. Open Redily and open the previously created connection as described in Deploying using Redis as a shared storage and notification server. 2. From the Keys panel, click New Key. 3. Add a Name and Type as illustrated below and then click Add.

4. Refresh the connection to see the newly added key named u2rest/endpoints.yaml. Then add endpoints to that file using the Editor panel as illustrated below.

5. Confirm that the endpoints have been added in the account from MVIS.

Vanity URL data resource examples

This topic provides multiple unique vanity URL data resource examples.

63 Chapter 9: Configuring MVIS

http POST request

This request is used to create the record. In the request body, ID is the required key. Sample URL: {{protocol}}://{{server}}//{restport}}/hr/members endpoints.yaml

- display-name: post-members-direct method: POST path: /hr/members db-operation: mvis-account: XDEMO write: file-name: MEMBERS fields: - name: ID position: 1 type: string binding: json-path json-path: $.id - name: FIRST_NAME position: 2 type: string binding: json-path json-path: $.firstname - name: CITY position: 3 type: string binding: json-path json-path: $.city - name: STATE position: 4 type: string binding: json-path json-path: $.state - name: ZIP position: 5 type: string binding: json-path json-path: $.zip Input Json { "id":"9891127", "firstname":"Bob", "city": "Melbourne", "state":"xyz", "zip":"4778" }

http PUT request

This request either creates the record (if record does not exist) or updates the existing record. Sample URL: {{protocol}}://{{server}}//{restport}}/hr/members/{id} endpoints.yaml

- display name: put-members-direct method: PUT path: /hr/members/{id} db-operation: mvis-account: XDEMO write: file-name: MEMBERS fields: - name: FIRST_NAME

64 Vanity URL data resource examples

position: 1 type: string binding: json-path json-path: $.firstname - name: CITY position: 2 type: string binding: json-path json-path: $.city - name: STATE position: 3 type: string binding: json-path json-path: $.state - name: ZIP position: 4 type: string binding: json-path json-path: $.zip Input Json { "firstname":"John", "city": "Sydney", "state":"XYZ", "zip":"8798" } http PATCH request

This Request only updates the existing record. Sample URL: {{protocol}}://{{server}}//{restport}}/hr/members/{id} endpoints.yaml

- display name: PATCH-members-direct method: PATCH path: /hr/members/{id} db-operation: mvis-account: XDEMO write: file-name: MEMBERS fields: - name: FIRST_NAME position: 1 type: string binding: json-path json-path: $.first_name - name: CITY position: 2 type: string binding: json-path json-path: $.city - name: STATE position: 3 type: string binding: json-path json-path: $.state - name: ZIP position: 4 type: string binding: json-path json-path: $.zip Input Json

65 Chapter 9: Configuring MVIS

{ "firstname":"John", "city": "Sydney", "state":"XYZ", "zip":"8798" }

http DELETE request

This Request deletes the existing record. Sample URL: {{protocol}}://{{server}}//{restport}}/hr/members/{id} endpoints.yaml

- display name: delete-members-direct method: DELETE path: /hr/members/{id} db-operation: mvis-account: XDEMO write: file-name: MEMBERS

http GET request

This request fetches the record of a particular ID. Sample URL: {{protocol}}://{{server}}//{restport}}/hr/members/{id} endpoints.yaml

- display name: get-members-direct - method: GET path: /hr/members/{id} db-operation: mvis-account: XDEMO read: file-name: MEMBERS field-names: - FIRST_NAME - CITY

http GET request

This request fetches all records in a specified file (no ID). Sample URL: {{protocol}}://{{server}}//{restport}}/hr/members endpoints.yaml

- display name: get-members-direct - method: GET path: /hr/members db-operation: mvis-account: XDEMO read: file-name: MEMBERS field-names: - FIRST_NAME - CITY

http GET request

This request records using a specified template. Note that the specified template must be located in the same directory as the endpoints.yaml file.

66 Vanity URL subroutine examples

Sample URL: {{protocol}}://{{server}}//{restport}}/hr/members/{id} endpoints.yaml

- display name: get-members-direct - method: GET path: /hr/members/{id} db-operation: mvis-account: XDEMO read: file-name: MEMBERS field-names: - FIRST_NAME - CITY template: name: cust-rec-read.template one-based-record-indexing: true

Parent topic: Vanity URLs

Vanity URL subroutine examples

This topic provides multiple unique vanity URL subroutine examples.

Note: If a UniData subroutine is modified, the account in MVIS must be restarted for the updated subroutine to take effect. MVIS connections cache the subroutine object-code, and therefore the newly modified code will not be invoked by MVIS until the connections are reset.

Get an employee record by ID using Path Param binding without a template

Request URL: {{protocol}}://{{server}}:{{restport}}/v4/hr/employees/{id} endpoints.yaml

- display name: get-employee method: GET path: /v4/hr/employees/{id} db-operation: mvis-account: xdemo call: subroutine: GET.EMPLOYEE.RAW params: - name: id position: 1 type: string binding: path-param param-direction: IN - name: record position: 2 type: string binding: response-body param-direction: OUT Subroutine: GET.EMPLOYEE.RAW

67 Chapter 9: Configuring MVIS

SUBROUTINE GET.EMPLOYEE.RAW(ID, RESPONSE)

RESPONSE = ''

OPEN '','MEMBERS' TO F.MEMBERS THEN READ REC FROM F.MEMBERS, ID THEN RESPONSE = REC END CLOSE F.MEMBERS END

RETURN Output

MoralesþTomþWþMrþ1187 Fleet StreetþBirminghamþOHþ52007þMþ8665þ5365877799þ5367792258 þ[email protected]þgatewayþU2FsdGVkX1/lGg4oSBL5CSTcfymWl1wEXV2mZv0qIFM=þtmorales. jpgþAþ8722156453786129þU2FsdGVkX18kSxqrJkgVxVt6a0lIDTD0O44gaXrSceYKp14HYDolp7RQ6z 1nrf+/þMCþ17930þ811

Get an employee record by ID using Path Param binding and response in the specified template

Note: This example employs a Thymeleaf template. For more information, see Using Thymeleaf to create templates.

Request URL: {{protocol}}://{{server}}:{{restport}}/v2/hr/employees/{id} endpoints.yaml

- display name: get-employee-via-template method: GET path: /v2/hr/employees/{id} db-operation: mvis-account: xdemo call: subroutine: GET.EMPLOYEE.RAW params: - name: id position: 1 type: string binding: path-param param-direction: IN - name: record position: 2 type: string binding: template param-direction: OUT template: name: "employee.template" one-based-record-indexing: false Subroutine: GET.EMPLOYEE.RAW

68 Vanity URL subroutine examples

SUBROUTINE GET.EMPLOYEE.RAW(ID, RESPONSE)

RESPONSE = ''

OPEN '','MEMBERS' TO F.MEMBERS THEN READ REC FROM F.MEMBERS, ID THEN RESPONSE = REC END CLOSE F.MEMBERS END

RETURN employee.template

{ "firstName": "[(${record[1]})]", "lastName": "[(${record[2]})]", "address": "[(${record[5]})]", "status": "[(${record[17]})]", "cardNums":[ [# th:each="item, iterState: ${record[18]}"] "[(${item})]"[(${iterState.size-1 > iterState.index}? ',':'')] [/] ] } Output

{ "firstName": "Wade", "lastName": "Pat", "address": "1543 Kodre Street", "status": "A", "cardNums":[

"8443776129453786", "1335880336981446", "6880335880335881"

] }

Get an employee record by ID using Request Body Binding and response in the specified template

Request URL:{{protocol}}://{{server}}:{{restport}}/request-body-binding/employee endpoints.yaml

69 Chapter 9: Configuring MVIS

- display name: get-employee-via-template-request-body-binding method: POST path: /request-body-binding/employee db-operation: mvis-account: xdemo call: subroutine: GET.EMPLOYEE.RAW params: - name: id position: 1 type: string binding: request-body param-direction: IN - name: record position: 2 type: string binding: template param-direction: OUT template: name: "employee.template" one-based-record-indexing: true Subroutine: GET.EMPLOYEE.RAW

SUBROUTINE GET.EMPLOYEE.RAW(ID, RESPONSE)

RESPONSE = ''

OPEN '','MEMBERS' TO F.MEMBERS THEN READ REC FROM F.MEMBERS, ID THEN RESPONSE = REC END CLOSE F.MEMBERS END

RETURN Request Body

1297 Output

{ "firstName": "Wade", "lastName": "Pat", "address": "1543 Kodre Street", "status": "A", "cardNums":[

"8443776129453786", "1335880336981446", "6880335880335881"

] }

Get an employee record by ID using Path Param Binding and Get response using Response Binding

Request URL:{{protocol}}://{{server}}:{{restport}}/v4/hr/employees/{id} endpoints.yaml

70 Vanity URL subroutine examples

- display name: get-employee-request-path-param-binding method: GET path: /v4/hr/employees/{id} db-operation: mvis-account: xdemo call: subroutine: GET.EMPLOYEE.RAW params: - name: id position: 1 type: string binding: path-param param-direction: IN - name: record position: 2 type: string binding: response-body param-direction: OUT Subroutine: GET.EMPLOYEE.RAW

SUBROUTINE GET.EMPLOYEE.RAW(ID, RESPONSE)

RESPONSE = ''

OPEN '','MEMBERS' TO F.MEMBERS THEN READ REC FROM F.MEMBERS, ID THEN RESPONSE = REC END CLOSE F.MEMBERS END

RETURN Output

MoralesþTomþWþMrþ1187 Fleet StreetþBirminghamþOHþ52007þMþ8665þ5365877799þ5367792258þ [email protected]þgatewayþU2FsdGVkX1/lGg4oSBL5CSTcfymWl1wEXV2mZv0qIFM=þtmorales.jpgþ Aþ8722156453786129þU2FsdGVkX18kSxqrJkgVxVt6a0lIDTD0O44gaXrSceYKp14HYDolp7RQ6z1nrf+/ þMCþ17930þ811

Get an employee record by ID using json-path Binding and Get response as JSON

Request URL:{{protocol}}://{{server}}:{{restport}}/v4/hr/employees endpoints.yaml

- display name: get-employee-json-path-binding method: POST path: /v4/hr/employees db-operation: mvis-account: xdemo call: subroutine: GET.EMPLOYEE.RAW params: - name: id position: 1 binding: json-path json-path: $.something.a param-direction: IN - name: abc position: 2 type: string binding: json-path json-path: $.response param-direction: OUT

71 Chapter 9: Configuring MVIS

Subroutine: GET.EMPLOYEE.RAW

SUBROUTINE GET.EMPLOYEE.RAW(ID, RESPONSE)

RESPONSE = ''

OPEN '','MEMBERS' TO F.MEMBERS THEN READ REC FROM F.MEMBERS, ID THEN RESPONSE = REC END CLOSE F.MEMBERS END

RETURN Request Body

{ "response": "", "something": { "a": "2137", "b": 2 } } Output

{ "abc": [ "Hawkes", "Jim", "F", "Mr", "4116 Curlewis Street", "Malden", "RI", "13477", "M", "2005", "9136681136", "9131446666", "[email protected]", "david", "U2FsdGVkX19ax0Skd5AxkcNukOypueiRpnKFoOAOKII=\n", "jhawkes.jpg", "A", [ "4437861294536759", "7922477922477922", "5476922477922477", "9911376921477922" ], [ "U2FsdGVkX187Q21vn2a6jJERGW2gwo9HWRl3nd8lQi8w5TuYWBD2Pl23TijAJGR6\n", "U2FsdGVkX1+t3YtkirWWiDe8J5RTw4DJKZ9egdxgCPbhjQ3I3NUnqDoVMHj77Kj/\n", "U2FsdGVkX1+royPXZLBTUk4f3y5EuILGLvXuu89M2L9U9v/VRE3eEvsAzedv1eHb\n", "U2FsdGVkX19Oe3Ei8p38Q0+aKBqqqnYZqRgBqtEh5W5pjXNWlU/ZLmRk9712mz6x\n" ], [ "MC", "MC", "AMEX", "V" ], [ "17227", "16954",

72 Vanity URL subroutine examples

"16923", "16893" ], [ "557", "355", "800", "255" ] ] }

Get an employee record by ID using Query Param Binding and Get response in the specified template

Note: This example employs a Thymeleaf template. For more information, see Using Thymeleaf to create templates.

Request URL:{{protocol}}://{{server}}:{{restport}}/v6/hr/employee endpoints.yaml

- display name: get-employee-via-template method: GET path: /v6/hr/employee db-operation: mvis-account: xdemo call: subroutine: GET.EMPLOYEE.RAW params: - name: id position: 1 type: string binding: query-param param-direction: IN - name: record position: 2 type: string binding: template param-direction: OUT template: name: "employee.template" one-based-record-indexing: true Subroutine: GET.EMPLOYEE.RAW

SUBROUTINE GET.EMPLOYEE.RAW(ID, RESPONSE)

RESPONSE = ''

OPEN '','MEMBERS' TO F.MEMBERS THEN READ REC FROM F.MEMBERS, ID THEN RESPONSE = REC END CLOSE F.MEMBERS END

RETURN employee.template

73 Chapter 9: Configuring MVIS

{ "firstName": "Hawkes", "lastName": "Jim", "address": "4116 Curlewis Street", "status": "A", "cardNums":[

"4437861294536759", "7922477922477922", "5476922477922477", "9911376921477922"

] }

Get an employee record by ID using Path Param Binding and Get response as an array using the specified template

Note: This example employs a Thymeleaf template. For more information, see Using Thymeleaf to create templates.

Request URL: {{protocol}}://{{server}}:{{restport}}/v7/hr/employees/{id} endpoints.yaml

- display name: get-employee-via-template-e method: GET path: /v7/hr/employees/{id} db-operation: mvis-account: xdemo call: subroutine: GET.EMPLOYEE.RAW params: - name: id position: 1 type: string binding: path-param - name: response position: 2 type: string array-delimiter: RM binding: template param-direction: OUT template: name: "employees.template" force-list: false one-based-record-indexing: true Subroutine: GET.EMPLOYEE.RAW

74 Vanity URL subroutine examples

SUBROUTINE GET.EMPLOYEE.RAW(ID, RESPONSE)

RESPONSE = ''

OPEN '','MEMBERS' TO F.MEMBERS THEN READ REC FROM F.MEMBERS, ID THEN RESPONSE = REC END CLOSE F.MEMBERS END

RETURN employees.template

[ [# th:each="rec : ${response}"] { "firstName": "[(${rec[1]})]", "lastName": "[(${rec[2]})]", "salary": "[(${rec[3]})]", "dept": "[(${rec[4]})]", "interests": [ [# th:each="interest : ${rec[5]}"] "[(${interest})]", [/] ] }, [/] ] Output

[

{ "firstName": "Hawkes", "lastName": "Jim", "salary": "F", "dept": "Mr", "interests": [

"4116 Curlewis Street",

] },

]

Create (POST) a resource using JSON Path Binding and get response as JSON

Request URL: {{protocol}}://{{server}}:{{restport}}/resource endpoints.yaml

- display name: create-resource-using-subroutine method: POST path: /resource db-operation: mvis-account: xdemo call: subroutine: CREATERESOURCE params: - name: id position: 1 type: string binding: json-path

75 Chapter 9: Configuring MVIS

json-path: $.id param-direction: IN - name: firstName position: 2 type: string binding: json-path json-path: $.firstName param-direction: IN - name: failureReson position: 3 type: string binding: json-path json-path: $.failureReason param-direction: IN - name: response position: 4 type: string binding: json-path json-path: $.result param-direction: OUT Subroutine: CREATERESOURCE

SUBROUTINE CreateResource(ID, FirstName, Result, FailureReason) * Res ID - Input * FirstName - Input * Result - Output. Success or failure condition. * FailureReason - details of the failure * Result = 0 ; *Success Condition OPEN "","MEMBERS" TO MEMBERS ELSE ; * Open MEMBERS file Result = 1 ; * Failure Condition FailureReason = "Unable to open MEMBERS file" RETURN END * READ MEM.REC FROM MEMBERS, ID THEN ; * Read MEMBERS file to make sure the Resource ID is already Result = 1 ; * If resource Id already exists then we return and set the failure condition FailureReason = "ID already exists" RETURN END ELSE MEM.REC = "" END * MEM.REC<1> = FirstName ; * Assuming field 1 is first name WRITE MEM.REC ON MEMBERS, ID; * Write away record to the MEMBERS file IF STATUS() NE -2 THEN Result = STATUS() FailureReason = "Write failure on MEMBERS file" RETURN END ELSE Result = STATUS() FailureReason = "Write success on MEMBERS file" RETURN END * RETURN Request Body

76 Vanity URL subroutine examples

{ "id":"12891288", "firstName": "Hello parlour", "failureReason":"", "result": "" } Output

{ "response": "Write success on MEMBERS file" }

POST: Get employee record by ID using XPath binding

Request URL:{{protocol}}://{{server}}:{{restport}}/hr/employees endpoints.yaml

- display-name: hr-get-employees-record method: POST path: /hr/employees db-operation: mvis-account: XDEMO call: subroutine: GET.EMPLOYEE.RAW params: - name: id position: 1 binding: xpath xpath: /root/id type: string param-direction: IN - name: res position: 2 binding: response-body type: string param-direction: OUT Subroutine: GET.EMPLOYEE.RAW

SUBROUTINE GET.EMPLOYEE.RAW(ID, RESPONSE) RESPONSE = '' OPEN '','MEMBERS' TO F.MEMBERS THEN READ REC FROM F.MEMBERS, ID THEN RESPONSE = REC END CLOSE F.MEMBERS END RETURN Request Body

1903 Output

77 Chapter 9: Configuring MVIS

WadeþPatþPþMrsþ1543 Kodre StreetþKununurraþNDþ82295þFþ-173þ3143588033þ3141136692 þ[email protected]þjenniferþU2FsdGVkX19qQBe5UW0dEG307kt99qplJtcf2b3y0B8= þpwade.jpgþAþ8443776129453786ý1335880336981446ý6880335880335881þU2FsdGVkX1+pINQMkin EECWVjGL4zP+CQEO3GyjW4qSJIaxu/xfmkfojXSDRDCcv ýU2FsdGVkX18HefLUNwxvxs8nOX8Z2WhsHfSGGv3rt6Vo6bNAOPJxambmvEAW2d+L ýU2FsdGVkX1/ejDq5Orb0eyjbi465bwnN+t6TjWe631bifJWPM4nEzVOlE446y1mC þMCýAMEXýVþ15919ý15888ý15858þ222ý766ý111

Update (PUT) a resource using JSON Path Binding and get response as JSON

Request URL:{{protocol}}://{{server}}:{{restport}}/resource endpoints.yaml

# update resource using subroutine - display name: update-resource-using-subroutine method: PUT path: /resource db-operation: mvis-account: xdemo call: subroutine: UPDATERESOURCE params: - name: id position: 1 type: string binding: json-path json-path: $.id param-direction: IN - name: firstName position: 2 type: string binding: json-path json-path: $.firstName param-direction: IN - name: failureReson position: 3 type: string binding: json-path json-path: $.failureReason param-direction: IN - name: response position: 4 type: string binding: json-path json-path: $.result param-direction: OUT Subroutine: UPDATERESOURCE

78 Vanity URL subroutine examples

SUBROUTINE UpdateResource(ID, FirstName, Result, FailureReason) * Res ID - Input * FirstName - Input * Result - Output. Success or failure condition. * FailureReason - details of the failure * Result = 0 ; *Success Condition OPEN "","MEMBERS" TO MEMBERS ELSE ; * Open MEMBERS file Result = 1 ; * Failure Condition FailureReason = "Unable to open MEMBERS file" RETURN END * MEM.REC<1> = FirstName ; * Assuming field 1 is first name WRITE MEM.REC ON MEMBERS, ID; * Write away record to the MEMBERS file IF STATUS() NE -2 THEN Result = STATUS() FailureReason = "update failure on MEMBERS file" RETURN END ELSE Result = STATUS() FailureReason = "update success on MEMBERS file" RETURN END * RETURN Request Body

{ "id":"128909", "firstName": "Hello abc", "failureReason":"", "result": "" } Output

{ "response": "update success on MEMBERS file" }

DELETE a resource using Path Param Binding and get response using response body binding

Request URL:{{protocol}}://{{server}}:{{restport}}/resource/{id} endpoints.yaml

79 Chapter 9: Configuring MVIS

# delete resource using subroutine using path param id - display name: delete-resource-using-subroutine method: DELETE path: /resource/{id} db-operation: mvis-account: xdemo call: subroutine: DELETERESOURCE params: - name: id position: 1 type: string binding: path-param json-path: $.id param-direction: IN - name: response position: 2 type: string binding: response-body param-direction: OUT Subroutine: DELETERESOURCE

SUBROUTINE DeleteResource(ID, RESPONSE)

Result = 0 ; *Success Condition OPEN "","MEMBERS" TO MEMBERS ELSE ; * Open MEMBERS file Result = 1 ; * Failure Condition RESPONSE= "Unable to open MEMBERS file" RETURN END * DELETE MEMBERS, ID ; * delete away record to the MEMBERS file IF STATUS() NE 17 THEN Result = STATUS() RESPONSE= "delete failure on MEMBERS file" RETURN END ELSE Result = STATUS() RESPONSE= "delete success on MEMBERS file" RETURN END * RETURN Output

delete success on MEMBERS file

Get employee record by lastName using response header, responseBody, requestHeader mapping

Request URL: {{protocol}}://{{server}}:{{restport}}/v4/hr/customers?lastName={value} endpoints.yaml

- display-name: get-customers-by-last-nametest method: GET path: /v4/hr/employees db-operation: mvis-account: XDEMO call: subroutine: GET.CUSTOMERS.BY.LAST.NAME params: - name: lastName position: 1 type: string

80 Vanity URL subroutine examples

binding: query-param param-direction: IN - name: REQUEST.HEADERS position: 2 type: string binding: request-headers param-direction: IN - name: RESPONSE.HEADER.CONTENT.TYPE position: 3 type: string param-direction: OUT binding: response-header - name: RESPONSE.BODY position: 4 type: string binding: response-body param-direction: OUT - name: STATUS position: 5 type: string binding: status param-direction: OUT Subroutine: GET.CUSTOMERS.BY.LAST.NAME

SUBROUTINE GET.CUSTOMERS.BY.LAST.NAME(LONGNAME, REQUEST.HEADERS, RESPONSE.HEADER.CONTENT.TYPE, RESPONSE.BODY, STATUS)

FOR I = 1 TO DCOUNT(REQUEST.HEADERS, @AM) IF REQUEST.HEADERS<1,I> = "Accept" AND REQUEST.HEADERS<2,I> = "application/xml" THEN GOSUB BUILD.XML.RESPONSE GOTO EXIT END NEXT I

GOSUB BUILD.ERROR.RESPONSE GOTO EXIT

BUILD.XML.RESPONSE: STATUS = 200 RESPONSE.HEADER.CONTENT.TYPE = "application/xml"

EXECUTE 'LIST MEMBERS WITH FULL_NAME LIKE "...':LONGNAME:'..." ALLTOXML' CAPTURING RESPONSE.BODY CONVERT @AM TO '' IN RESPONSE.BODY

RETURN

BUILD.ERROR.RESPONSE: STATUS = 400 RESPONSE.HEADER.CONTENT.TYPE = "application/xml" RESPONSE.BODY = '' RESPONSE.BODY = RESPONSE.BODY : '' RESPONSE.BODY = RESPONSE.BODY : "Unsupported Content Type in Accept Header" RESPONSE.BODY = RESPONSE.BODY : "Please provide a supported content type in the Accept header" RESPONSE.BODY = RESPONSE.BODY : ''

RETURN

EXIT:

81 Chapter 9: Configuring MVIS

RETURN END RequestHeader

"Accept": "application/xml" Output

LIST MEMBERS WITH FULL_NAME LIKE "...Mike..." ALLTOXML 09:05:22pm 20 Nov 2019 PAGE 1 MEMBERS... Full Name...... Status Desc 0930 Mike Sun Active 0322 Mike Santiago Active 0139 Mike Crand Active 1156 Mike Colburn Active 0607 Mike Carvey Active 1421 Mike Miller Active 0157 Mike Keeney Active 1743 Mike Sine Active 8 records listed.

Get employee record by ID and response as a json array

Request URL:{{protocol}}://{{server}}:{{restport}}/v7/hr/employees/{id} endpoints.yaml

SUBROUTINE GET.EMPLOYEE.RAW(ID, RESPONSE)

RESPONSE = ''

OPEN '','MEMBERS' TO F.MEMBERS THEN READ REC FROM F.MEMBERS, ID THEN RESPONSE = REC END CLOSE F.MEMBERS END

RETURN Output

82 Vanity URL subroutine examples

[

{ "firstName": "Wade", "lastName": "Pat", "salary": "P", "dept": "Mrs", "interests": [

"1543 Kodre Street",

] },

]

Get an employee record by ID containing date using Request Body Binding and response in the specified template

Note: This example employs a Thymeleaf template. For more information, see Using Thymeleaf to create templates.

Request URL: {{protocol}}://{{server}}:{{restport}}/request-body-binding/employee endpoints.yaml

SUBROUTINE GET.EMPLOYEE.RAW(ID, RESPONSE) RESPONSE = '' OPEN '','MEMBERS' TO F.MEMBERS THEN READ REC FROM F.MEMBERS, ID THEN RESPONSE = REC RESPONSE<10> = OCONV(RESPONSE<10>,"D4/") END CLOSE F.MEMBERS RETURN END employee.template

83 Chapter 9: Configuring MVIS

{ "firstName": "[(${record[1]})]", "lastName": "[(${record[2]})]", "date": "[(${record[10]})]", "status": "[(${record[17]})]", "cardNums":[ [# th:each="item, iterState: ${record[18]}"] "[(${item})]"[(${iterState.size-1 > iterState.index}? ',':'')] [/] ] } Output

{ "firstName": "Wade", "lastName": "Pat", "date": "07/11/1967", "status": "A", "cardNums":[

"8443776129453786", "1335880336981446", "6880335880335881"

] }

Parent topic: Vanity URLs

84 Chapter 10: Working with associations in MVIS

Review the instructions and examples below for information on working with associations in MVIS. A data resource can be a primary, top-level resource (a data file) or a sub-resource (a data file association). Primary resources typically contain collections of sub-resources. A sub-resources can contain a collection of other sub-resources.

As an example, the HS.SALES Customer resource is a primary resource that maps to the CUSTOMER file. The HS.SALES Customer resource contains a collection of sub-resources, including the Order resource, which corresponds to the ORDER association. The Order resource, in turn, contains a collection of sub-resources, including Item, which represents all of the items in a single order and includes all of the multi-subvalue fields in the ORDER association.

Procedure

1. Select Configuration → MultiValue Integration Server Configuration → Accounts and then click Add account to create a new REST account (for example, rest_test which is an XDEMO account in the database). 2. Select REST Server → Accounts and then click the new REST account created above. 3. Click the Data Resources item in that account and then click Add Data Resource. 4. Check the id and last_name check boxes.

85 Chapter 10: Working with associations in MVIS

5. Select the ASSOC option from the Search drop-down and then select one association field (for example, ENC_CARD_INFO) from the filter text box.

6. Select one field from the association (note how the other associated fields are then automatically selected).

86 Working with associations in MVIS

7. Select the Data Subresources tab and expand the new subresource to view the result. Click OK to save your Data Resource.

8. Get the MultiValue record as follows: a. Select MV in the SM column for each Field Name in the list.

b. Click View Swagger from the Members data resource.

87 Chapter 10: Working with associations in MVIS

c. From Swagger, open the Get Member (/XDEMO/Members/{id}) and click Try It Out. d. Enter an ID in the id text box (for example, 0312) and click Execute.

Note how the result displays the MultiValue records for ID 0312.

{ "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/rest_test/ Members/0312", "enc_card_info_list": { "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/rest_test/ Members/0312/Enc_card_info", "Enc_card_info": [ { "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/ rest_test/Members/0312/Enc_card_info/1", "cardnum_enc": "U2FsdGVkX1/7M9YNAL1WfqveIcXeP0qNvObf0ZysSBOWI pG8PPhhOUhTNojONsRs\n", "cardsec_enc": "570", "cardtype_enc": "AMEX", "u2version": "-4144898357870150118", "cardexp_enc": "04/01/2015" }, {

88 Working with associations in MVIS

"@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/ rest_test/Members/0312/Enc_card_info/2", "cardnum_enc": "U2FsdGVkX1/z3QNvvJuVZJGkAAvzFsWfR4Penp+pIg smFsbh7XvytBkXnT0U1RqK\n", "cardsec_enc": "588", "cardtype_enc": "AMEX", "u2version": "-4144898357870150118", "cardexp_enc": "04/01/2012" }, { "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/ rest_test/Members/0312/Enc_card_info/3", "cardnum_enc": "U2FsdGVkX18OhfTlT9m/Hx1nFFXmBkEZy+D/ICpNEG DflD6Kd2Pjr4tsqtsfzsFq\n", "cardsec_enc": "668", "cardtype_enc": "V", "u2version": "-4144898357870150118", "cardexp_enc": "10/01/2013" } ] }, "last_name": "Markowski", "_id": "0312", "u2version": "-4144898357870150118" } 9. Post the MultiValue record as follows: a. From Swagger, open the POST Member and click Try It Out. b. Type the following json code in the body text box and click Execute: { "id": "8888", "last_name": "Biden", "enc_card_info_list": { "Enc_card_info": [ { "cardnum_enc": "U2FsdGVkX1+ZhLSW17gXb0ldah+VSXpMCjUgm+QCU lrJZ6uUiAIzPNX33yDiX7g/", "cardtype_enc": "MC", "cardexp_enc": "07/01/2021", "cardsec_enc": "123" } ] } }

10. Get the Multi-SubValue record as follows:

89 Chapter 10: Working with associations in MVIS

a. From the Data Resource, select MS in the SM column for each Field Name in the list.

b. Click View Swagger from the Members data resource. c. From Swagger, open the GET Member (/XDEMO/Members/{id}) and click Try It Out. d. Enter an ID in the id text box (for example, 0313) and click Execute.

Note how the result displays the Multi-SubValue records for ID 0313.

{ "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/rest_test/ Members/0313", "enc_card_info_list": { "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/rest_test/ Members/0313/Enc_card_info", "Enc_card_info": [ { "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/ rest_test/Members/0313/Enc_card_info/1", "enc_card_info_ms_list": { "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/ rest_test/Members/0313/Enc_card_info/1/Enc_card_info_ms", "Enc_card_info_ms": [

90 Working with associations in MVIS

{ "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/ rest_test/Members/0313/Enc_card_info/1/Enc_card_info_ms/1", "cardnum_enc": "U2FsdGVkX1/hdq4Kt26dU8cWWgYIszq/BCT1Wysyd VxMOU7+pwLCDx3J5rwxdx/C\n", "cardsec_enc": "446", "cardtype_enc": "V", "u2version": "6023662882069197057", "cardexp_enc": "01/01/2016" } ] }, "u2version": "6023662882069197057" }, { "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/ rest_test/Members/0313/Enc_card_info/2", "enc_card_info_ms_list": { "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/ rest_test/Members/0313/Enc_card_info/2/Enc_card_info_ms", "Enc_card_info_ms": [ { "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/ rest_test/Members/0313/Enc_card_info/2/Enc_card_info_ms/1", "cardnum_enc": "U2FsdGVkX18Jp2yaEGLZNR6gAIqZMhyaiAt8Iy3Sxa C3DqjugdbuiOmRyNyrCH7e\n", "cardsec_enc": "991", "cardtype_enc": "MC", "u2version": "6023662882069197057", "cardexp_enc": "11/01/2017" } ] }, "u2version": "6023662882069197057" }, { "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/ rest_test/Members/0313/Enc_card_info/3", "enc_card_info_ms_list": { "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/ rest_test/Members/0313/Enc_card_info/3/Enc_card_info_ms", "Enc_card_info_ms": [ { "@uri": "http://dendevmvdtqa12.dev.rocketsoftware.com:7171/ rest_test/Members/0313/Enc_card_info/3/Enc_card_info_ms/1", "cardnum_enc": "U2FsdGVkX19YWc6e8dZe3yfRM3ptfNM7L08bmW70J zao2iBMAH/yeF28QDC5hLVN\n", "cardsec_enc": "436", "cardtype_enc": "AMEX", "u2version": "6023662882069197057", "cardexp_enc": "10/01/2017" } ] }, "u2version": "6023662882069197057" } ] }, "last_name": "Watson", "_id": "0313", "u2version": "6023662882069197057" 11. Post the Multi-SubValue record as follows: a. From Swagger, open the POST Member and click Try It Out. b. Type the following json code in the body text box and click Execute:

91 Chapter 10: Working with associations in MVIS

{ "id": "9999", "last_name": "Trump", "enc_card_info_list": { "Enc_card_info": [ { "enc_card_info_ms_list": { "Enc_card_info_ms": [ { "cardnum_enc": "U2FsdGVkX1+ZhLSW17gXb0ldah+VSX pMCjUgm+QCUlrJZ6uUiAIzPNX33yDiXfff7g/", "cardtype_enc": "V", "cardexp_enc": "09/10/2021", "cardsec_enc": "666" } ] } } ] } }

Parent topic: MultiValue Integration Server User Guide

92 Chapter 11: Using MVIS in the cloud

Cloud-based services can be used to build, deploy, and manage applications through a global network of data centers. MVIS is available on the following cloud services: • Azure overview Microsoft Azure is a series of cloud-based services that can be used to build, deploy, and manage applications through a global network of data centers. • AWS overview Amazon Web Services (AWS) is a secure cloud services platform. Parent topic: MultiValue Integration Server User Guide Azure overview

Microsoft Azure is a series of cloud-based services that can be used to build, deploy, and manage applications through a global network of data centers. When working with Azure, the following definitions are used: Application Insights A unified console that simplifies building, deploying, and managing cloud resources. Application Insights is also an analytic service that helps users understand the performance and usage of their live web applications. Blob storage An object storage service that can be used for cloud applications, content distribution, backups, archiving, and disaster recovery. Service bus Service bus allows MVIS clusters to communicate via messaging. Shared Access Signatures (SAS) SAS is the primary security mechanism for service bus messaging and guards the service bus based on authorization rules. These rules are configured on a namespace or messaging entity (relay, queue, or topic). Parent topic: Using MVIS in the cloud

Setting up an MVIS Kubernetes cluster in Azure

Perform the following steps to deploy Redis, cmadmin and cm on an Kubernetes cluster.

Procedure

93 Chapter 11: Using MVIS in the cloud

-DAZURE_ACCOUNT=xxx -DAZURE_ACCOUNT_KEY=xxx -DBUCKET_NAME=xxx -DCONFIG_NAME=cm.ini -DAZURE_SB_NAMESPACE=mvtools -DAZURE_SB_SAS_KEY=z+q9wn1oPfxJ0hAqWYbrATgTcZChqWj8y+ahSHZ/yDU= -DAPPLICATION_INSIGHTS_IKEY=721419bc-57d6-405d-ba8a-17c8532d4c49 -Dlogging.level.root=info -Dlogging.level.com.rs.mv.cm=info The table below describes the values set for the JAVA_OPTS environment variable:

Parameter Description -DTYPE MVIS mode to deploy. -DAZURE_ACCOUNT Azure account name. -DAZURE_ACCOUNT_KEY Azure account key. -DBUCKET_NAME Azure Blob storage. -DAZURE_SB_NAMESPACE Name of the Azure Service Bus. -DAZURE_SB_SAS_KEY SAS is the primary security mechanism for service bus messaging and guards the service bus based on authorization rules. These rules are configured on a namespace or messaging entity (relay, queue, or topic). -DCONFIG_NAME Configuration settings file. -Dlogging.level.com.rs.mv.cm=debug Checking detailed logs in MVIS admin. Dlogging.console.enabled=true Enables console logging. -DCLOUD_LOGGER Specifies cloud logging options such as AWS/ AZURE. -DLOG_GROUP Group of log streams used to store monitoring, access control settings and other logs. If not specified, the default log group name will be cm. -DLOG_STREAM Name for a sequence of separate log streams which share the same source. If not specified, the default log stream name will be cm-main- logs. DAWS_CW_NAMESPACE Creates a custom namespace. If not specified, then the CM_PERFORMANCE_STATISTICS (created in the CloudWatch > Metrics section) is used for checking performance statistics metrics.

94 Setting up an MVIS Kubernetes cluster in Azure

3. To confirm the creation of the pods and that all pods are running, run the following command: kubectl get pods

4. To get all pods, their deployments and svc, run the following command: kubectl get all

95 Chapter 11: Using MVIS in the cloud

5. To get the External-IP which will allow you to access MVIS from anywhere, run the following command: kubectl get svc

6. Copy the cmadmin external-IP and port number and then open MVIS admin in the browser by entering the external-IP and port number in the browser's address bar as illustrated below:

7. Copy the cm external-IP and paste it in the Host text box.

8. Run the following command (where 6739 is the port for the Redis service): kubectl port-forward redis-0 6379:6379 9. Use either of the links below to download and install the Redis database application which you can use to update the data. ▪ Redily :- https://www.softpedia.com/get/Internet/Servers/Database-Utils/Redily.shtml ▪ Redislabs:- https://redislabs.com/blog/so-youre-looking-for-the-redis-gui/ For information on creating a connection in Redily, see Deploying using Redis as a shared storage and notification server. For information on creating vanity endpoints when using Docker Redis cache, see Creating vanity endpoints when using Docker Redis cache.

Tip: To view your MVIS logs in CloudWatch, go to CloudWatch → Log Groups and then enter the log group and log stream names you specified when creating the JAVA_OPTS environment variable for your cm.yaml above (-DLOG_GROUP and -DLOG_STREAM).

96 Logging to Application Insights on Windows

Logging to Application Insights on Windows

Configure MVIS to send log records to Application Insights. 1. To enable logging to Application Insights, navigate to the installation directory and open the start-cm.bat file. 2. Using a text editor, modify the start-cm.bat file to contain the following code: java -DTYPE=MVCM^ -DCLOUD_LOGGING=AZURE\^ -DAPPLICATION_INSIGHTS_IKEY=^ -jar cm.jar Your program will now send a copy of the log to Application Insights. Note, if a user enables performance statistics from the MVIS Web Admin UI with these Java options specified, performance statistics will also be sent to Application Insights.

Logging to Application Insights on Linux/UNIX

Configure MVIS to send log records to Application Insights. 1. To enable logging to Application Insights, navigate to the installation directory and open the start-cm.sh file. 2. Using a text editor, modify the start-cm.sh file to contain the following code: $ java -DTYPE=MVCM\ -DCLOUD_LOGGING=AZURE\ -DAPPLICATION_INSIGHTS_IKEY=\ -jar cm.jar Your program will now send a copy of the log to Application Insights. Note, if a user enables performance statistics from the MVIS Web Admin UI with these Java options specified, performance statistics will also be sent to Application Insights.

Sending performance statistics to Application Insights on Linux/UNIX

Application Insights is an application performance management (APM) service that can be used to monitor live web applications and detect any performance issues. Configure MVIS to send performance statistic entries to Application Insights. 1. To send performance statistics to Application Insights, navigate to the installation directory and open the start-cm.sh file. 2. Using a text editor, modify the start-cm.sh file to contain the following code: $ java -DTYPE=MVCM\ -DAPPLICATION_INSIGHTS_IKEY=\ -jar cm.jar 3. Using a web browser, open the MVIS Web Admin UI. 4. From the MVIS Web Admin UI, select Administration → Performance Statistics, and then click Start. Your program will now send performance statistic entries to Application Insights.

97 Chapter 11: Using MVIS in the cloud

Configuring MVIS and the MVIS Admin for Azure Blob storage

MVIS can store its configuration data in Azure Blob storage. This is especially useful when running a cluster of MVISs that should all share a common configuration. To configure MVIS and the MVIS Admin to store data in Azure Blob storage, complete the following tasks: • Configuring MVIS for Blob storage on Linux/UNIX MVIS can be configured to use Blob storage as its configuration store by specifying additional Java system properties when starting MVIS. The properties identify which Azure storage account to use, what container name to store the configuration files under, the name of the main configuration file, and the Azure storage account key to use. • Configuring the MVIS Admin for Blob storage on Linux/UNIX Configure the MVIS Admin to use Blob storage to store MVIS configuration files. This includes the main MVIS configuration file and your U2 REST definitions. • Configuring MVIS for Blob storage on Windows MVIS can be configured to use Blob storage as its configuration store by specifying additional Java system properties when starting MVIS. The properties identify which Azure storage account to use, what container name to store the configuration files under, the name of the main configuration file, and the Azure storage account key to use. • Configuring the MVIS Admin for Blob storage on Windows Configure the MVIS Admin to use Blob storage to store MVIS configuration files. This includes the main MVIS configuration file and your U2 REST definitions.

Configuring MVIS for Blob storage on Linux/UNIX

MVIS can be configured to use Blob storage as its configuration store by specifying additional Java system properties when starting MVIS. The properties identify which Azure storage account to use, what container name to store the configuration files under, the name of the main configuration file, and the Azure storage account key to use.

About this task

For more information on how to create an Azure storage account, see the Azure documentation at https://docs.microsoft.com/en-us/azure/.

Procedure

1. To configure MVIS to use Blob storage, navigate to the installation directory and open the start-cm.sh file. 2. Using a text editor, modify the start-cm.sh file to contain the following code: $ java -DTYPE=MVCM\ -DAZURE_ACCOUNT=\ -DAZURE_ACCOUNT_KEY=\ -DAZURE_SB_NAMESPACE=\ -DAZURE_SB_SAS_KEY=\ -DBUCKET_NAME=\ -DCONFIG_NAME=\ -jar cm.jar Parent topic: Configuring MVIS and the MVIS Admin for Azure Blob storage

98 Configuring the MVIS Admin for Blob storage on Linux/UNIX

Configuring the MVIS Admin for Blob storage on Linux/UNIX

Configure the MVIS Admin to use Blob storage to store MVIS configuration files. This includes the main MVIS configuration file and your U2 REST definitions.

About this task

The properties identify which Azure storage account, container name to store the configuration files, name of the main configuration file, and which Azure storage account key to use. For more information on how to create an Azure storage account, see the Azure documentation at https://docs.microsoft.com/en-us/azure/.

Procedure

1. To configure the MVIS Admin, navigate to the installation directory and open the start- admin.sh file. 2. Using a text editor, modify the start-admin.sh file to contain the following code: a. From the Command Prompt, enter the following command: $ java -DTYPE=MVCM\ -DAZURE_ACCOUNT=\ -DAZURE_ACCOUNT_KEY=\ -DAZURE_SB_NAMESPACE=\ -DAZURE_SB_SAS_KEY=\ -DBUCKET_NAME=\ -DCONFIG_NAME=\ -jar cm-admin.jar Parent topic: Configuring MVIS and the MVIS Admin for Azure Blob storage

Configuring MVIS for Blob storage on Windows

About this task

For more information on how to create an Azure storage account, see the Azure documentation at https://docs.microsoft.com/en-us/azure/.

Procedure

1. To configure MVIS to use Blob storage, navigate to the installation directory and open the start-cm.bat file. 2. Using a text editor, modify the start-cm.bat file to contain the following code: java -DTYPE=MVCM^ -DAZURE_ACCOUNT=^ -DAZURE_ACCOUNT_KEY=^ -DAZURE_SB_NAMESPACE=^ -DAZURE_SB_SAS_KEY=^ -DBUCKET_NAME=^ -DCONFIG_NAME=^ -jar cm.jar Parent topic: Configuring MVIS and the MVIS Admin for Azure Blob storage

99 Chapter 11: Using MVIS in the cloud

Configuring the MVIS Admin for Blob storage on Windows

Configure the MVIS Admin to use Blob storage to store MVIS configuration files. This includes the main MVIS configuration file and your U2 REST definitions.

About this task

The properties identify which Azure storage account, container name to store the configuration files, name of the main configuration file, and which Azure storage account key to use. For information on how to create an Azure Service Bus namespace and a shared access signature, see the Azure documentation at https://docs.microsoft.com/en-us/azure/.

Procedure

1. To configure the MVIS Admin to use Blob storage, navigate to the installation directory and open the cm-admin.xml file. 2. Edit the arguments element in the cm-admin.xml file to look like the following: cm-admin Connection Manager Admin This service runs CM-ADMIN system. java -DTYPE=MVCM -jar -DAZURE_ACCOUNT= -DAZURE_ACCOUNT_KEY= -DAZURE_SB_NAMESPACE= -DAZURE_SB_SAS_KEY= -DBUCKET_NAME= -DCONFIG_NAME="%BASE%\ cm-admin.jar" rotate %BASE%\logs Parent topic: Configuring MVIS and the MVIS Admin for Azure Blob storage

Configuring MVIS and the MVIS Admin for Azure Service Bus

MVIS can store configurations in cloud-based data stores, such as Azure Blob storage. In these scenarios, the MVIS Admin saves configuration changes directly to the cloud-based data stores. When a configuration change is saved, the MVIS Admin also publishes a message to a cloud-based message broker that indicates a configuration change occurred. MVIS waits for such messages and, if it receives such a notification, will reload its configuration. A cluster of load-balanced MVISs will all receive the messages published from the MVIS Admin. This allows a clustered set of MVISs to act in unison to the changes published by the MVIS Admin. The following configuration changes will take effect immediately in the running MVIS: ▪ Any newly added accounts will have their connection pools started. ▪ Any removed accounts will have their connection pools shutdown. ▪ Certain changes to an existing account will cause that account's pool to be restarted with the new parameters. To configure MVIS and the MVIS Admin to use Azure Service Bus, complete the following tasks: • Configuring MVIS for Azure Service Bus on Linux/UNIX

100 Configuring MVIS for Azure Service Bus on Linux/UNIX

MVIS can be configured to use Service Bus as its message broker by specifying additional Java system properties when starting MVIS. The properties identify which Service Bus namespace and Service Bus shared access signature key MVIS uses. • Configuring the MVIS Admin for Azure Service Bus on Linux/UNIX The MVIS Admin can be configured to use Service Bus as its message broker. These properties identify which Service Bus namespace and shared access signature key the MVIS Admin uses. • Configuring MVIS for Azure Service Bus on Windows MVIS can be configured to use Service Bus as its message broker by specifying additional Java system properties when starting MVIS. The properties identify which Service Bus namespace and Service Bus shared access signature key MVIS uses. • Configuring the MVIS Admin for Azure Service Bus on Windows The MVIS Admin can be configured to use Service Bus as its message broker. These properties identify which Service Bus namespace and shared access signature key the MVIS Admin uses.

Configuring MVIS for Azure Service Bus on Linux/UNIX

About this task

For more information on how to create a Service Bus namespace and shared access signature, see the Azure documentation at https://docs.microsoft.com/en-us/azure/.

Procedure

1. To configure Service Bus as the message broker for MVIS, navigate to the installation directory and open the start-cm.sh file. 2. Using a text editor, modify the start-cm.sh file to contain the following code: $ java -DTYPE=MVCM\ -DAZURE_SB_SAS_KEY=\ -DAZURE_SB_NAMESPACE=\ -jar cm.jar Parent topic: Configuring MVIS and the MVIS Admin for Azure Service Bus

Configuring the MVIS Admin for Azure Service Bus on Linux/UNIX

The MVIS Admin can be configured to use Service Bus as its message broker. These properties identify which Service Bus namespace and shared access signature key the MVIS Admin uses.

About this task

For more information on how to create a Service Bus namespace and shared access signature, see the Azure documentation at https://docs.microsoft.com/en-us/azure/.

Procedure

1. To configure the MVIS Admin, navigate to the installation directory and open the start- admin.sh file. 2. Using a text editor, modify the start-admin.sh file to contain the following code:

101 Chapter 11: Using MVIS in the cloud

$ java -DTYPE=MVCM\ -DAZURE_SB_NAMESPACE=\ -DAZURE_SB_SAS_KEY=\ -jar cm-admin.jar Parent topic: Configuring MVIS and the MVIS Admin for Azure Service Bus

Configuring MVIS for Azure Service Bus on Windows

About this task

For more information on how to create a Service Bus namespace and shared access signature, see the Azure documentation at https://docs.microsoft.com/en-us/azure/.

Procedure

1. To configure Service Bus as the message broker for MVIS, navigate to the installation directory and open the start-cm.bat file. 2. Using a text editor, modify the start-cm.bat file to contain the following code: java -DTYPE=MVCM^ -DAZURE_SB_SAS_KEY=^ -DAZURE_SB_NAMESPACE=^ -jar cm.jar Parent topic: Configuring MVIS and the MVIS Admin for Azure Service Bus

Configuring the MVIS Admin for Azure Service Bus on Windows

The MVIS Admin can be configured to use Service Bus as its message broker. These properties identify which Service Bus namespace and shared access signature key the MVIS Admin uses.

About this task

For more information on how to create a Service Bus namespace and shared access signature, see the Azure documentation at https://docs.microsoft.com/en-us/azure/.

Procedure

102 AWS overview

3. Restart the MVIS Admin service for your changes to take effect. Parent topic: Configuring MVIS and the MVIS Admin for Azure Service Bus AWS overview

Amazon Web Services (AWS) is a secure cloud services platform. When working with AWS, the following definitions are used: Amazon CloudWatch Amazon CloudWatch is a monitoring service that supports centralized logging against a cluster of MultiValue Integration Servers. Simple Notification Service (SNS) SNS is a service that provides event notifications that users subscribed to and allows MVIS clusters to communicate via messaging. Simple Storage Service (S3) An object storage service that is used to hold MVIS configuration files. Parent topic: Using MVIS in the cloud

Setting up an MVIS Kubernetes cluster in AWS

Perform the following steps to deploy Redis, cmadmin and cm on an AWS cluster.

Procedure

1. Create a statefulset deployment of Redis in the Kubernetes cluster. 2. The following JAVA_OPTS environment variable as illustrated below should be used when creating the mvis and mvisadmin pods in k8: env: - name: JAVA_OPTS value: >- -DTYPE=MVCM -DCONFIG_NAME=cm.ini -DCONSOLE_LOGGING=1 -DREDIS_HOST=redis -DAWS_ACCESS_KEY=xxx -DAWS_SECRET_KEY=xxx -DAWS_REGION=us-west-2 -Dlogging.level.com.rs.mv.cm=debug -Dlogging.console.enabled=true The table below describes the values set for the JAVA_OPTS environment variable:

Parameter Description -DTYPE MVIS mode to deploy. -DCONFIG_NAME Configuration settings file. -DREDIS_HOST The name specified in the redis.yaml file. -DAWS_ACCESS_KEY AWS access key. -DAWS_SECRET_KEY AWS secret key. -DAWS_REGION AWS region. -Dlogging.level.com.rs.mv.cm=debug Checking detailed logs in MVIS admin.

103 Chapter 11: Using MVIS in the cloud

Parameter Description Dlogging.console.enabled=true Enables console logging. -DCLOUD_LOGGER Specifies cloud logging options such as AWS/ AZURE. -DLOG_GROUP Group of log streams used to store monitoring, access control settings and other logs. If not specified, the default log group name will be cm. -DLOG_STREAM Name for a sequence of separate log streams which share the same source. If not specified, the default log stream name will be cm-main- logs. DAWS_CW_NAMESPACE Creates a custom namespace. If not specified, then the CM_PERFORMANCE_STATISTICS (created in the CloudWatch > Metrics section) is used for checking performance statistics metrics. 3. To confirm the creation of the pods and that all pods are running, run the following command: kubectl get pods

104 Setting up an MVIS Kubernetes cluster in AWS

4. To get all pods, their deployments and svc, run the following command: kubectl get all

5. To get the External-IP which will allow you to access MVIS from anywhere, run the following command: kubectl get svc

6. Copy the cmadmin external-IP and port number and then open MVIS admin in the browser by entering the external-IP and port number in the browser's address bar as illustrated below:

105 Chapter 11: Using MVIS in the cloud

7. Copy the cm external-IP and paste it in the Host text box.

Logging to Amazon CloudWatch on Windows

106 Logging to Amazon CloudWatch on Linux/UNIX

▪ Log Group: A log group is a group of log streams that share the same retention, monitoring, and access control settings. You can define log groups and specify which streams to put into each group. There is no limit on the number of log streams that can belong to one log group. If not specified, the default log group name will be cm. ▪ Log Stream: A log stream is a sequence of log events that share the same source. Each separate source of logs into CloudWatch Logs makes up a separate log stream. If not specified, the default log stream name will be cm-main-logs. Specify these options by adding the code below: java -DTYPE=MVCM^ -DCLOUD_LOGGING=AWS^ -DAWS_REGION=^ -DAWS_ACCESS_KEY=^ -DAWS_SECRET_KEY=^ -DAWS_LOG_GROUP=^ -DAWS_LOG_STREAM=^ -jar cm.jar Your program will now send a copy of the log to Amazon CloudWatch.

Logging to Amazon CloudWatch on Linux/UNIX

Amazon CloudWatch is a monitoring service for AWS and your applications that run on AWS. Use Amazon CloudWatch to monitor your performance and react to changes in your AWS resources. 1. To enable logging to Amazon CloudWatch, navigate to the installation directory and open the start-cm.sh file. 2. Using a text editor, modify the start-cm.sh file to contain the following code: $ java -DTYPE=MVCM\ -DCLOUD_LOGGING=AWS\ -DAWS_REGION=\ -DAWS_ACCESS_KEY=\ -DAWS_SECRET_KEY=\ -jar cm.jar 3. You can also add logging configuration options to distinguish between log sources: ▪ Log Group: A log group is a group of log streams that share the same retention, monitoring, and access control settings. You can define log groups and specify which streams to put into each group. There is no limit on the number of log streams that can belong to one log group. If not specified, the default log group name will be cm. ▪ Log Stream: A log stream is a sequence of log events that share the same source. Each separate source of logs into CloudWatch Logs makes up a separate log stream. If not specified, the default log stream name will be cm-main-logs. Specify these options by adding the code below:

$ java -DTYPE=MVCM\ -DCLOUD_LOGGING=AWS\ -DAWS_REGION=\ -DAWS_ACCESS_KEY=\ -DAWS_SECRET_KEY=\ -DAWS_LOG_GROUP=\ -DAWS_LOG_STREAM=\ -jar cm.jar Your program will now send a copy of the log to Amazon CloudWatch.

107 Chapter 11: Using MVIS in the cloud

Sending performance statistics to AWS CloudWatch on Windows

CloudWatch is an application performance management (APM) service used to monitor live web applications and detect performance issues. 1. To configure MVIS to send performance statistics to AWS CloudWatch, navigate to the installation directory and open the start-cm.bat file. 2. Using a text editor, modify the start-cm.bat file to contain the following code: $ java -DTYPE=MVCM^ -DAWS_REGION=^ -DAWS_ACCESS_KEY=^ -DAWS_SECRET_KEY=^ -jar cm.jar 3. You can also add CloudWatch namespaces, which contain metrics. If not specified, the default namespace will be CM_PERFORMANCE_STATISTICS. For example: $ java -DTYPE=MVCM^ -DAWS_REGION=^ -DAWS_ACCESS_KEY=^ -DAWS_SECRET_KEY=^ -DAWS_CW_NAMESPACE=^ -jar cm.jar 4. Open the MVIS Web Admin UI. 5. From the Administration menu, select Performance Statistics. 6. Click the Start button to start logging performance statistics. The program will now send performance statistic entries to AWS CloudWatch.

Sending performance statistics to AWS CloudWatch on Linux / UNIX

CloudWatch is an application performance management (APM) service used to monitor live web applications and detect performance issues. 1. To configure MVIS to send performance statistics to AWS CloudWatch, navigate to the installation directory and open the start-cm.sh file. 2. Using a text editor, modify the start-cm.sh file to contain the following code: $ java -DTYPE=MVCM\ -DAWS_REGION=\ -DAWS_ACCESS_KEY=\ -DAWS_SECRET_KEY=\ -jar cm.jar 3. You can also add CloudWatch namespaces, which contain metrics. If not specified, the default namespace will be CM_PERFORMANCE_STATISTICS. For example: $ java -DTYPE=MVCM\ -DAWS_REGION=\ -DAWS_ACCESS_KEY=\ -DAWS_SECRET_KEY=\ -DAWS_CW_NAMESPACE=\ -jar cm.jar 4. Open the MVIS Web Admin UI. 5. From the Administration menu, select Performance Statistics. 6. Click the Start button to start logging performance statistics. The program will now send performance statistic entries to AWS CloudWatch.

108 Configuring MVIS and the MVIS Admin for Amazon S3 storage

Configuring MVIS and the MVIS Admin for Amazon S3 storage

MVIS can store its configuration data in Amazon S3 storage. This is especially useful when running a cluster of MultiValue Integration Servers that should all share a common configuration. To configure MVIS and the MVIS Admin data in Amazon S3 storage, complete the following tasks: • Configuring MVIS for Amazon S3 storage on Linux/UNIX MVIS can be configured to use Amazon S3 storage as its configuration store by specifying additional Java system properties when starting MVIS. These properties identify what AWS access key, secret key, and AWS region that MVIS will use. • Configuring the MVIS Admin for Amazon S3 storage on Linux/UNIX The MVIS Admin can be configured to use Amazon S3 storage. These properties identify what AWS access key, secret key, and AWS region MVIS will use. • Configuring MVIS for Amazon S3 storage on Windows MVIS can be configured to use Amazon S3 storage as its configuration store by specifying additional Java system properties when starting MVIS. These properties identify what AWS access key, secret key, and AWS region that MVIS will use. • Configuring the MVIS Admin for Amazon S3 storage on Windows The MVIS Admin can be configured to use Amazon S3 storage. These properties identify what AWS access key, secret key, and AWS region MVIS will use.

Configuring MVIS for Amazon S3 storage on Linux/UNIX

MVIS can be configured to use Amazon S3 storage as its configuration store by specifying additional Java system properties when starting MVIS. These properties identify what AWS access key, secret key, and AWS region that MVIS will use.

About this task

For more information on Amazon S3, including how to set up AWS access keys, secret keys, and AWS regions, see the AWS documentation at https://aws.amazon.com/documentation/.

Procedure

1. To configure MVIS to use Amazon S3 storage, navigate to the installation directory and open the start-cm.sh file. 2. Using a text editor, modify the start-cm.sh file to contain the following code: $ java -DTYPE=MVCM\ -DAWS_ACCESS_KEY=\ -DAWS_SECRET_KEY=\ -DAWS_REGION=\ -DBUCKET_NAME=\ -DCONFIG_NAME=\ -jar cm.jar Parent topic: Configuring MVIS and the MVIS Admin for Amazon S3 storage

Configuring the MVIS Admin for Amazon S3 storage on Linux/UNIX

The MVIS Admin can be configured to use Amazon S3 storage. These properties identify what AWS access key, secret key, and AWS region MVIS will use.

109 Chapter 11: Using MVIS in the cloud

About this task

For more information on Amazon S3, including how to set up AWS access keys, secret keys, and AWS regions, see the AWS documentation at https://aws.amazon.com/documentation/.

Procedure

1. To configure the MVIS Admin, navigate to the installation directory and open the start- admin.sh file. 2. Using a text editor, modify the start-admin.sh file to contain the following code: $ java -DTYPE=MVCM\ -DAWS_ACCESS_KEY=\ -DAWS_SECRET_KEY=\ -DAWS_REGION=\ -DBUCKET_NAME=\ -DCONFIG_NAME=\ -jar cm-admin.jar Parent topic: Configuring MVIS and the MVIS Admin for Amazon S3 storage

Configuring MVIS for Amazon S3 storage on Windows

About this task

For more information on Amazon S3, including how to set up AWS access keys, secret keys, and AWS regions, see the AWS documentation at https://aws.amazon.com/documentation/.

Procedure

1. To configure MVIS to use Amazon S3 storage, navigate to the installation directory and open the start-cm.bat file. 2. Using a text editor, modify the start-cm.bat file to contain the following code: java -DTYPE=MVCM^ -DAWS_ACCESS_KEY=^ -DAWS_SECRET_KEY=^ -DAWS_REGION=^ -DBUCKET_NAME=^ -DCONFIG_NAME=^ -jar cm.jar Parent topic: Configuring MVIS and the MVIS Admin for Amazon S3 storage

Configuring the MVIS Admin for Amazon S3 storage on Windows

The MVIS Admin can be configured to use Amazon S3 storage. These properties identify what AWS access key, secret key, and AWS region MVIS will use.

About this task

For more information on Amazon S3, including how to set up AWS access keys, secret keys, and AWS regions, see the AWS documentation at https://aws.amazon.com/documentation/.

110 Configuring the MVIS Admin for Amazon S3 storage on Windows

Procedure

1. To configure the MVIS Admin, navigate to the installation directory and open the cmadmin.xml file. 2. Edit the arguments element in the cm-admin.xml file to look like the following: cm-admin Connection Manager Admin This service runs CM-ADMIN system. java -DTYPE=MVCM -jar -DAWS_ACCESS_KEY= -DAWS_SECRET_KEY= -DAWS_REGION= -DBUCKET_NAME= -DCONFIG_NAME= "%BASE%\ cm-admin.jar" rotate %BASE%\logs 3. Restart the MVIS Admin service for your changes to take effect. Parent topic: Configuring MVIS and the MVIS Admin for Amazon S3 storage

111 Chapter 12: Enabling security for MVIS

To enable security for MVIS, complete the following tasks: • Encrypting the password for the MVIS Web Admin UI and MVIS Admin The MVIS Admin and MVIS Web Admin UI are protected by credentials that are stored in the application.properties configuration file. By default, the user and password are both admin. These can be changed by editing the application.properties file and encrypting the password. • Setting up SSL The following three areas of MVIS communication can be secured using SSL: • REST server security configuration You can create HTTP users and define access controls to secure specific subroutines, data resources, vanity endpoints or an entire REST server account. Once secured, users will need to provide valid credentials to access the subroutine, data resource, vanity endpoint or REST account. • Setting-up OAuth authentication OAuth provides delegated authorization for REST/APIs which enables apps to obtain limited access to a user's data without defining new users. It essentially decouples authentication from authorization. Parent topic: MultiValue Integration Server User Guide Encrypting the password for the MVIS Web Admin UI and MVIS Admin

The MVIS Admin and MVIS Web Admin UI are protected by credentials that are stored in the application.properties configuration file. By default, the user and password are both admin. These can be changed by editing the application.properties file and encrypting the password. About this task

The MVIS Admin and the MVIS Web Admin UI are protected with HTTP BASIC authentication. The credentials are stored and encrypted in the application.properties file under the [Auth] section. The user name is stored under the auth.user property and the encrypted password is stored under the auth.password property, as shown in the following example: application.properties ... [Auth] auth.user=admin auth.password=TdH7VWfzmuie9cFPVLHlKQ== ... Note, without the -i, clear characters are echoed on the screen. When a carriage return is enter, the encrypted password is shown.

Procedure

To encrypt the password, use the hazify command, as shown is the following example: c:\u2\cm> java -jar hazify.jar -i Enter password: Enter password again: Encrypted password is: SBDwStnkNF5WSmMH0oCrfQ== Parent topic: Enabling security for MVIS

112 Setting up SSL

Setting up SSL

The following three areas of MVIS communication can be secured using SSL: • Security between the client and the MVIS Admin The browser requires the signing certificate in its trust store. Generally, this is not necessary, as most common CA certificates are available in their truststore. If you are using self-signed certificates, you will need to install your certificate in their trusted root certificate authorities store. • Security between applications and MVIS Secure your application and MVIS using the cm.ini file. • Security between MVIS and the database To secure the connection between your data server and MVIS, you must first configure your database connection with the MultiValue Integration Server for SSL. This entails creating or obtaining a certificate for client and one for the server. The signing certificate should be placed in your truststore on the MVIS side. The server certificate is referenced by the database. See either your UniVerse or UniData Security Features guide for additional instructions on creating a certificate on the database. Parent topic: Enabling security for MVIS

Security between the client and the MVIS Admin

The browser requires the signing certificate in its trust store. Generally, this is not necessary, as most common CA certificates are available in their truststore. If you are using self-signed certificates, you will need to install your certificate in their trusted root certificate authorities store.

Procedure

1. Obtain a valid certificate and private key to secure the connection between the MVIS Admin and your web browser. Specific instructions for creating or obtaining a certificate are outside the scope of this documentation. 2. Place the certificate and the private key from Step 1 into your keystore. Specific instructions for adding a certificate into the java keystore is outside the scope of this documentation. 3. In the [SSL] section of the application.properties file, make the following changes to enable an HTTPS connection between the MVIS Admin and the client: a. In the server.port field, designate the server port to be used for secure access to the MVIS Admin. The default is 7043. b. In the server.ssl.key-store field, enter the path to the keystore referenced in Step 2. c. In the server.ssl.key-store-password field, enter the password for your keystore. Note that this password should be hazify encrypted. d. In the server.ssl.key-password, enter the password for your keystore. Note that this password should be hazify encrypted. 4. Save the application.properties file. 5. If the MVIS Admin is already running, you must restart it to make these changes effective. 6. Verify that your secure connection is working by opening your web browser and entering https://MVIS Admin:port where: ▪ MVIS Admin is the DNS name or IP address of the server where the MVIS Admin is running. ▪ port is the server port number specified for the server.port field in step 3a.

For example: https://localhost:7043

113 Chapter 12: Enabling security for MVIS

Parent topic: Setting up SSL

Security between applications and MVIS

Secure your application and MVIS using the cm.ini file. Prerequisites

You need a certificate, and you can use the same one created in Security between the client and the MVIS Admin, on page 113.

Procedure

1. Open the cm.ini file in a text editor. a. In the [Default] section, set httpsEnabled to true. b. Add the sslKeyStorePath= property and append the path to your keystore. For example, sslKeyStorePath=C:\certs\den-tci009.jks c. Add the sslKeyStorePassword= property and append the password for your keystore, for example sslKeyStorePassword=abcd. Note that this password should be hazify encrypted. 2. Save the cm.ini file. 3. 3. If MVIS is running, restart MVIS to make your changes effective. Parent topic: Setting up SSL

Security between MVIS and the database

To secure the connection between your data server and MVIS, you must first configure your database connection with the MultiValue Integration Server for SSL. This entails creating or obtaining a certificate for client and one for the server. The signing certificate should be placed in your truststore on the MVIS side. The server certificate is referenced by the database. See either your UniVerse or UniData Security Features guide for additional instructions on creating a certificate on the database.

Prerequisites

▪ Add an account. ▪ Have the root.cer certificate for the client side and the server certificate signed by root.cer. ▪ Create a security context record and configure the data server using XAdmin. For information on creating a Security Context Record and configuring the data server with XAdmin, see the Rocket DBTools User Guide.

About this task

Note: For UniData 8.2.1.9116 and 8.2.2 implementations, to ensure secure only connections from MVIS to the database, you must define a secure flag for that Unirpc port. See Chapter 5: Secure UniRPC Features in the UniData Security Features Guide.

114 REST server security configuration

Procedure

1. From the MVIS Web Admin UI, select Configuration → Security, and complete the following steps: a. In the Use Trust Store field, select Enabled. b. If you are not using the default truststore, in the SSL Trust Store Path field, enter the path to the truststore where your client certificate is located. c. If you are not using the default truststore, in the SSL Trust Store Password field, enter the password for the truststore. 2. From the MVIS Web Admin UI, select Configuration → Accounts, and then click the Edit icon. 3. From the Server details tab, complete the following fields:

Field Action

SSL connection(s) to MV Select this check box to activate SSL mode for the account. server

SSL hostname validation Select this check box to compare the server name in the account configuration to the server name in the MVIS property that is used for the server-side certificate.

4. Select one of the following options: ▪ To start MVIS, in the MultiValue Integration Server Status section, click Start. ▪ To restart your account, from the Accounts section, click Restart Account.

If the server name in the cm.ini file and the server certificate match, your server name connection pools for the account are created successfully. If the sever name and server certificate do not match, a Bad connection... error is displayed. Parent topic: Setting up SSL REST server security configuration

You can create HTTP users and define access controls to secure specific subroutines, data resources, vanity endpoints or an entire REST server account. Once secured, users will need to provide valid credentials to access the subroutine, data resource, vanity endpoint or REST account. To enable security for a REST server, complete the following tasks: • Defining HTTP users You can create HTTP users and assign them to specific roles to secure access to REST subroutines, data resources, vanity endpoints or the REST account itself. Complete these steps to define a new HTTP user. • Defining access control Set up MVIS to secure specific subroutines, data resources, vanity endpoints or an entire REST account. Once secured, users will need to provide valid credentials to access the subroutine, data resource, vanity endpoint or REST server. Parent topic: Enabling security for MVIS

Defining HTTP users

You can create HTTP users and assign them to specific roles to secure access to REST subroutines, data resources, vanity endpoints or the REST account itself. Complete these steps to define a new HTTP user.

115 Chapter 12: Enabling security for MVIS

To enable authentication for REST services running under MVIS, select Configuration from the Administration menu, and open the Security section. In the HTTP Authentication drop-down, select either http-basic or http-digest authentication.

1. From the MVIS Web Admin UI, select Administration → REST Server, and then expand the REST Server Security Configuration section. 2. Expand the Define HTTP Users section. 3. Click the Add HTTP User button. 4. On the Define HTTP Users dialog box, enter a user name and password for the HTTP user.

Note: The name and password entries are independent from user names and passwords stored in other configuration files in this product.

5. Choose a role for the new user from the Roles list by selecting the appropriate check box. Note that a user can have multiple roles.

Tip: To create a new role, click Add Role, type a name for the new role and select the role's check box to apply the role to the new HTTP user.

6. Click OK. 7. Restart MVIS for your changes to take effect. The new HTTP user is added to the list of defined HTTP users. Parent topic: REST server security configuration

Defining access control

Set up MVIS to secure specific subroutines, data resources, vanity endpoints or an entire REST account. Once secured, users will need to provide valid credentials to access the subroutine, data resource, vanity endpoint or REST server.

Caution: When working with a vanity endpoint that has an access control set on it from the MVIS admin, changing the vanity endpoint definition requires that you recreate the access control on it. Note that the original vanity endpoint and associated access control are not automatically deleted when the vanity endpoint definition is changed. If you want to remove them, they will need to be explicitly deleted.

1. From the MVIS Web Admin UI, select Administration → REST Server, and then expand the REST Server Security Configuration section. 2. Expand the Define Access Control section. 3. Click the Add Path button. 4. In the Define Access Control Path dialog box, select the account or specific subroutine or data resource to secure from the Path drop-down and then click OK. 5. In the Define Access Control section, click the Roles and Methods drop-down and select the GET, POST, PUT and DELETE methods to allow for users assigned to any of the roles listed in the Any Role column.

116 Setting-up OAuth authentication

Tip: ▪ Select the top-most check box for any of the GET, POST, PUT or DELETE methods to allow that method for all defined roles. ▪ To create a new role, click Add Role, type a name for the new role and select the GET, POST, PUT or DELETE methods to require that a logged-in user be a member of the specified group to be granted access to the end point(s). Note that your changes are immediately saved.

6. Restart MVIS for your changes to take effect. Parent topic: REST server security configuration Setting-up OAuth authentication

OAuth provides delegated authorization for REST/APIs which enables apps to obtain limited access to a user's data without defining new users. It essentially decouples authentication from authorization. To enable OAuth authentication, the MVIS based application must be registered on the OAuth Authorization server and OAuth Security aspects must be selected and configured on the MVIS based application. ▪ The MVIS based application should be registered on the OAuth Authorization server. ▪ The Public Key Certificate issued during the configuration of the MVIS client on the OAuth Authorization server should be converted to PKCS12 format (use an online certificate conversion tool to convert to this format) and should be placed in a directory of your choosing on the same machine where MVIS is installed. ▪ The Public Key Password, which is set during the above-mentioned online certificate conversion, will also be required. ▪ The keystore provided for OAuth configuration can have only one certificate. Complete these instructions to enable OAuth authentication on MVIS:

1. Click Security from Configuration screen. 2. Select OAuth from the HTTP Authentication drop-down and click OK. 3. Enter the path to the public key certificate issued during the configuration of the MVIS client on the OAuth Authorization server in the OAuth Public Key Path field. 4. Enter the public key password set during the conversion of the certificate in the OAuth Public Key Password field. 5. Click OK. 6. Define the appropriate access roles and path. Note that the names of the roles must match the claim section defined in the OAuth token. Below is an example of an OAuth token: //Claims { "iss": "auth0.com", "exp": 1426420800, "company": "RocketSoftware", "scope": [ "AllowedMemberAccess" ] "awesome": true } As per the example above, define a role named AllowedMemberAccess. See Defining access control for instructions. Parent topic: Enabling security for MVIS

117 Appendix A: cm.ini file properties

The cm.ini file contains many of the parameters used to configure MVIS.

Important: Although you can use the cm.ini file to configure many of the MVIS configurable parameters, it is recommended that you perform such configurations using the MVIS Web Admin UI.

[LogLevel] section

The [LogLevel] section of the cm.ini file contains parameters for the types of information to write to the mvis.log file. The following example shows the [LogLevel] section: [LogLevel] logging.level=ERROR The following table lists the available logging levels. Each level, with the exception of \, enables the logging level selected and every logging level beneath the selected level should be sent to the mvis.log file. For example, selecting the Logging level INFO includes logging at the INFO, WARNING, and ERROR logging levels. Selecting DEBUG includes DEBUG, INFO, WARNING, and ERROR logging levels.

Logging level Description ERROR Logs errors only. WARNING Logs warnings and errors. INFO Logs informational messages and above. DEBUG Logs debug messages and above. TRACE Logs everything. OFF Disables Logging.

[Default] section

The following table describes the properties in the [Default] section:

Property Description connectionManagerPort The port number on which MVIS accepts UO requests. The default is 7870. connectionTracingEnabled If set to true, detailed connection activity from MVIS to the data servers is logged. excludedCipherSuites Specifies the list of cipher suites that should be rejected by MVIS. The cipher suites should be delimited by a space. The default is empty. excludedProtocols Specifies the list of SSL protocols that should be rejected by MVIS. The protocols should be delimited by a space. The default is empty. gracefulShutdownEnabled Specifies whether the http server should be given time to gracefully shutdown before stopping MVIS. The default is false. gracefulShutdownTimeout The timeout to use for the graceful shutdown of the http server, in milliseconds, if gracefulShutdownEnabled is set to true. The default value (if enabled) is 30000 milliseconds (30 seconds). httpAuthentication Specifies authentication to be used for the http server. Can be http-basic, http-digest, OAuth or none.

118 cm.ini file properties

Property Description httpIdleTimeout Number milliseconds before an idle http connection from a REST client times out. The default is 30000 (30 seconds). httpsEnabled Specifies whether to use SSL protocol on the http port httpPort. The default is false. httpPort The port to use for the http server. The default is 7171. idleConnectionCheckInterval The number of milliseconds to wait before checking for and removing backend data server connections whose idle time has exceeded the idleConnectionTimeout. The default is 60000 milliseconds (60 seconds). idleConnectionTimeout The number of milliseconds that a connection to a backend data server can remain idle before it is flagged for removal. The default is 60000 milliseconds (60 seconds). logPath The full path to the main log file (e.g. C:\U2\CM\logs \mvis.log or /opt/cm/logs/mvis.log. maxConnectionAttempts Maximum number of attempts to create a connection pool for an account before the account is suspended. The default is 0.

Note: When set to 0, if an account is created in MVIS with an incorrect password or if a password is changed for an existing account, MVIS will continue to attempt creating the connection pool for that account, which can result in the user account being locked. If set to a positive number, MVIS will only attempt to create the connection pool the specified number of times. If connection pool creation is still unsuccessful after the specified number of attempts, the account will be suspended (not locked), allowing the administrator to update the password and restart the account. maxPoolRestartWaitTime Specifies the maximum times in second to retry the restarting or deletion of an account, if connections in the account are found to be busy when the restart or deletion is requested. The default is 60 seconds. monitorPort The port number on which MVIS accepts monitor and maintenance requests made from the MVIS Admin. The default is 7871. openSessionTimeout For a given account, specifies the maximum amount of time to wait for a response from a data server connection before timing out. Default is 300 seconds. It is important to note that when MVIS is unable to connect to the server, a second attempt to connect will automatically be made before suspending further attempts. This means that a openSessionTimeout of 10 seconds will effectively take 20 seconds before timing out. Clients who utilize this timeout in multi-tier environments where UniRPC sits between the server and MVIS should take this behavior into account when setting up their openSessionTimeout value. restMaxRequestBodySize The maximum size in bytes of a request payload for rest endpoints. The default is 200000 (200K bytes).

119 Property Description servicesCacheSize The number of services that will be cached by the running MVIS after they are loaded from disk or other configuration storage. Services are grouped together based on their definition file, and cached after they are loaded. servicesCacheSize dictates how many of such service definition files are cached. A servicesCacheSize of 0 indicates no caching will be done. This is useful during development, but can affect performance as all services files will need to be loaded with each service- based request. If service files are stored in cloud storage, this will require a network round-trip. The default is 50. sslKeyManagerPassword Optional use by the Jetty http server in MVIS – the password (if any) for the specific key within the key store. The password used to create this and the certificate should be encrypted using the hazify.jar. sslKeyStorePassword The password to the Java keystore specified in sslKeyStorePath. The password should be encrypted using the hazify.jar. sslKeyStorePath The path to the Java keystore. sslTrustStorePassword Specifies the password to the Java truststore specified in sslTrustStorePath. The password should be encrypted. sslTrustStorePath If left unspecified, the default truststore is employed. Otherwise,specifies the path to the truststore to employ. startPerfStatsLoggingEnabled Specifies whether to log performance statistics. Performance statistics are written to the log file specified in statisticsLogPath. The default is false. trustStoreEnabled If set to true, this property specifies that the truststore is enabled. This property must be enabled to create a secure connection to the MV Server. The default is false. uoClientConnectionTimeout Specifies the number of milliseconds that sockets servicing UO clients can be left open with no activity before they timeout on the listening thread. The default is 28800 (8 hours). uoMaxServerRequestQueue Number of requests that can be queued on the listening socket when accepting connections from UO clients. The default value is 50 requests.

[Account] section

The following table describes the [Account] section properties:

Property Description accountEnabled If set to true (default), enables the account in the cm.ini file. If set to false, disables the account in the cm.ini file. accountpath The path to the MV account on the data server. avgRespTimeThresholds Triggers monitor warnings when the overall average request response time for this account exceeds these values. The average covers the period since MVIS was last started. Two space-delimited values are required for this property. The first value is the amount of time in milliseconds which will cause the monitor to display warning status. The second value is the amount of time in milliseconds which will cause the monitor to display critical status.

120 cm.ini file properties

Property Description connectionString The entry from the unirpcservices file on the system where the specified account resides, used when connecting to the account. devModeEnabled For a given account, setting this value allows all requests to get the latest version of compiled code, instead of using a cached version of the object code. devModeEnabled causes database processes to restart after each method call. While allowing newly compiled code to be picked up, this mode carries a performance overhead as the associated database processes terminate and are recreated after each method call, and is not recommended for live production use for this reason. The default is false. encoding For a given account, specifies the encoding for the pooled connections. executionTimeout For a given account, specifies the maximum amount of time to wait for a response from a data server connection before timing out. Default is 300 seconds. maxPoolSize The maximum number of connections maintained in the connection pool for a given account. minPoolSize The minimum number of connections maintained in the connection pool for a given account. mvServer The name or IP address of the data server where the account is located. mvServerConnectionTimeout For a given account, specifies the maximum amount of time to wait for a response from a data server connection before timing out. Default is 300 seconds. mvServerKeepAliveEnabled For a given account, specifies if a mvServerKeepAliveEnabled ping should be sent at a recurring interval. Enabling this allows MVIS to actively check for problematic connections to the data servers. This active ping allows MVIS to detect a wider class of network-related problems. If MVIS detects a problem with a connection in its pool, it will attempt to replace the problematic connection. mvServerKeepAliveInterval For a given account, specifies the number of milliseconds to wait between keep alive ping requests for the account. The default, if mvServerKeepAliveEnabled is true, is 60000 (60 seconds). mvServerPort For a given account, specifies the port on the data server to which MVIS will connect. The default is 31438 password For a given account, specifies the password to the operating system-level user ID that will be used to connect to the data server. The password should be encrypted. protocol Specifies the protocol that this account should use when being accessed via a client. ▪ UNIRPC: Use UO protocol for this account (default). ▪ REST: Use http for this account.

121 Property Description requestsQueuedThresholds Triggers monitor warnings when the number of requests for this account waiting to be served exceeds these values. Two space-delimited values are required for this property. The first value is the number of requests which will cause the monitor to display warning status. The second value is the number of requests which will cause the monitor to display critical status. respTimeThresholds Triggers monitor warnings when the average response time for this account exceeds these values. The average covers a single monitor refresh interval. Two space-delimited values are required for this property. The first value is the amount of time in milliseconds which will cause the monitor to display warning status. The second value is the amount of time in milliseconds which will cause the monitor to display critical status. sbPassword The password for the SB+ user to use in REST calls that require an SB+ environment. sbSysId The name of the SB+ system id to use in REST calls that require an SB+ environment. sbUserId The SB+ user id to use in REST calls that require an SB+ environment. Note that this user must have a default terminal definition of DEFAULT.TERM. Without this terminal definition, the connection could get assigned to the wrong connection type and cause the MVIS connection to hang. serverSideLoggingEnabled Enables como files for the account. The default is false. slowRequestThreshold Triggers monitor warnings when any requests exceed this value for the given account. soapPort The port number on which MVIS accepts SOAP requests for this account. soapTimeout For a given account, specifies the timeout, in milliseconds, for the SOAP worker thread when it reads data from the socket. The default is 5000. sslHostnameValidationEnabled When set to true, this specifies that the SSL connections, from MVIS to the data server, for the account require the hostname on the data server's SSL certificate match the server name for the account. By default, this is set to false. uoClientTCPKeepAliveEnabled Enables the TCP keep alive option on UO client requests for this account into MVIS. The default is false. uoClientValidationEnabled Validates credentials passed in through UO clients, unless set to false. The default is false. uoSSLEnabled Specifies whether to use the SSL protocol when communicating with the data server, for this account. The default is false. Note that trustStoreEnabled must be set to true to enable this flag. userId For a given account, specifies the operating system-level user ID that will be used to connect to the data server.

Parent topic: MultiValue Integration Server User Guide

122 Appendix B: MVIS Java options

Use Java options to supply configuration parameters on the command line to either MVIS or the MVIS Admin.

Note: The Java option properties listed in this section should never be deleted from the application.properties file. Doing so can cause errors with MVIS installations and upgrades or cause the MVIS application to fail.

Note: Any property in the application.properties file can be overridden on the command line by specifying the equivalent Java option for the MVIS Admin. For example, to override the auth.user property found in the application.properties file, use the - Dauth.user= Java option.

Cloud

The following table describes the Java properties that you can use to configure cloud environments:

Property Description -DAWS_ACCESS_KEY= AWS access key. -DAWS_SECRET_KEY= AWS secret key. -DAWS_REGION= AWS region name. -DAZURE_ACCOUNT= Azure storage account name. -DAZURE_ACCOUNT_KEY= Azure storage account key. -DAZURE_SB_NAMESPACE Azure service bus namespace. -DAZURE_SB_SAS_KEY= Azure service bus shared access signature -DBUCKET_NAME= Name of the container storage to hold the MVIS configuration files.

Miscellaneous

The following table describes the Java properties that is used miscellaneously:

Property Description -DTYPE=MVCM (always required to be MVCM)

Configuration

The following table describes the Java properties that you can use to configure MVIS and the MVIS Admin:

123 Property Description -DFS_DIR= reading from the file system, use FS_DIR to specify what directory you can find the configuration files. -DCONFIG_NAME= Name of the main MVIS configuration file. -DACCOUNTS_CONFIG_NAME= MVIS can optionally store its account sections in a separate configuration file from the main configuration file.

Logging

The following table describes the Java properties that you can use to configure logging:

Property Description -DCLOUD_LOGGING=AZURE|AWS Specifies logs to be sent to Azure Application Insights or AWS CloudWatch. -DAPPLICATION_INSIGHTS_IKEY= Required for Application Insights. If set, and performance statistics logging is turned on in the MVIS Web Admin UI, performance statistics will be sent to Application Insights. -DAWS_LOG_NAME= AWS log group name. -DAWS_LOG_STREAM= AWS log stream name. -DCONSOLE_LOGGING=1 Sends all log data to the console and any additional log targets. -DLOG_LEVEL=ERROR| Specify the starting log level when WARN|INFO|TRACE|DEBUG|OFF writing to the startCM.log file. The startCM.log file is a bootstrap log file that is written to when MVIS first starts and before the main log file has been set in the configuration file. -DROLLOVER_ON_START=1 Roll over the log files each time MVIS starts.

Parent topic: MultiValue Integration Server User Guide

124 Appendix C: Limitations

The following limitations exist in the current version of MVIS.

Swagger

If an endpoint.yaml file contains two or more endpoints with identical paths, then only one of those endpoints will be available for execution in Swagger.

Parent topic: MultiValue Integration Server User Guide

125