Installation Guide

Introduction

This section is dedicated to describe the process of installation and configuration of Platina Standard API (REST) on local, test or production environment. In this guide it is assumed that Platina Standard API will be hosted in IIS despite it is implemented on latest .NET tech stack and supports other hosting alternatives.

Prerequisites

Setup SQL Stored Procedure that is required by Platina Standard API

In order the Platina Standard API to operate correctly, it is necessary to install one stored procedure into Platina database:

  1. Open SQL Server Management Studio and connect to Platina database.
  2. Create a new Query and paste the following stored procedure content in Query Editor:
USE [platina]
GO
CREATE OR ALTER PROCEDURE [dbo].[pStructureObjectInfoGet]
	@propID INT
AS
	SELECT [propID], [objectID], [moduleID], [typeID] FROM tObjProperties
	WHERE [propID] = @propID
3. After successful execution, close the SQL Server Management Studio.

## Install Platina Standard API

Platina Standard API is shipped as a ZIP-package. When obtained an installation package please follow the next steps:
1. Unpack Platina Standard API ZIP-package to the destination folder.
2. Launch IIS Manager.
3. In IIS Manager choose a web site (e.g. "Default Web Site") where the Platina Standard API application will be hosted:

   IIS Choose Website
4. Create a new Application for the chosen web site, give it an alias (e.g. "api") and set its' physical path to the folder where Platina Standard API package was extracted:

   IIS Create API Application


**NOTE:** It is not recommended to create an API application as a sub-application of Platina, because this may cause exceptions related to not found references. This is caused because Platina sub-applications inherit configuration of Platina which may be redundant for them.
5. When IIS application for Platina Standard API is created, refer to the next section of this guide that describes configuration.

## Configure Platina Standard API

In order the Platina Standard API to function properly, it is required to perform basic configuration steps. The configuration is not complex and is limited by only defining environment variables and setting authentication for the Platina Standard API application in IIS.

### Configure Platina Standard API Environment Variables

Platina Standard API configuration is performed by setting corresponding environment variables for the application in IIS. Here is a list of supported environment variables:

| Environment Variable | Description | Comment |
|---|---|---|
| DB_SERVER | A database server instance that hosts Platina database. | e.g. _localhost_, _platina-db-server_ |
| DB_TRUSTED_CONNECTION | Instructs Platina Standard API to use trusted SQL connection when accessing Platina database. | _true_/_false_ |
| DB_USER | Used if DB_TRUSTED_CONNECTION is equal to _false_ or not specified. Stores SQL user name to connect to Platina database. | e.g. _sa_ |
| DB_PASSWORD | Used if DB_TRUSTED_CONNECTION is equal to _false_ or not specified. Stores SQL user password to connect to Platina database. | **NOTE:** password is stored in unencrypted form in configuration file. So, it is highly recommended to use DB_TRUSTED_CONNECTION whether possible. |
| PLATINA_API_USERNAME | Represents a user communicating with Platina, this must be a user in platina tUserSettings (e.g. _DOMAIN\Administrator_). This setting is similar to _StandardServiceAuthorizedUser_ of WCF-based Platina API. |
| PLATINA_API_BASE_URL | A base URL for Platina Standard API endpoint. It is a URL that consists of IIS website binding and application alias. | e.g. _/api_ if application name is 'api', or _/subapp/api_ if application is nested by some 'subapp' virual path for website. |

To setup environment variables for Platina Standard API web application follow these steps:
1. In IIS Manager select a Platina Standard API application and select "Configuration Editor" feature:

   IIS Select Configuration Editor
2. In the opened configuration choose `system.WebServer/aspNetCore` section and expand `environmentVariables` item:

   IIS API Configuration View
3. Use "Add" button to define new environment variables from the list above:

   IIS add Environment Variables
4. When environment variables are defined, do not forget to click "Apply" button to save the changes:

   IIS save Environment Variables

### Configure Platina Standard API Authentication

When hosted in IIS, Platina Standard API application supports the same standard authentication schemes as other IIS applications (e.g. Platina). In order to enable authentication for Platina Standard API, do the following:

1. In IIS Manager find and select a Platina Standard API application.
2. Choose "Authentication" feature:

   IIS Authentication feature
3. Disable "Anonymous" authentication.
4. Enable desired Authentication scheme (e.g. Windows Authentication):

   IIS Authentication schemes

## Summary

This guide provides all necessary steps to install and configure Platina Standard API on local, test or production environment.
When Platina Standard API is hosted, it exposes built-in Swagger endpoint by the URL: `#IIS_API_APPLICATION_URL#/swagger`, so for example if API is hosted for default web site with "https" binding in application with alias "api", then Swagger endpoint URL will be: [https://SERVER/api/swagger](https://SERVER/api/swagger).