Configuration: Unity

Overview

Unity is typically installed on a local server at each resort and Aspenware Service installs a test and production version. The test version is pointing to the customer’s test environment and production is pointing to the customer’s live environment. These two instances are typically installed on the same server and the server needs to be accessible from Azure if Unity is being used for Commerce or internally if Unity is being used for Aspenware Scanning. If being used for Commerce, the server is typically set up in a DMZ.

The instructions below outline the steps needed to install and configure Unity. The install process is manual so there is currently no installer. We also occasionally add new settings which would have to be added manually because our auto-deployment process does not update any config or json files which is where all the configuration is defined.

Prerequisites

Install IIS following RTP’s Server Install guide. These steps outline all the necessary server components to install.
Download and install .NET Core Runtime. After this install, you may or may not need to restart the server.
SQL Role Security - determine the SQL username and password that will be added to Unity and run scripts to grant select, update, insert, delete privileges. Some customers use an existing RTP username/password and grant these privileges to the RTPOneRole and others want us to create a new role to grant these privileges to. Aspenware has scripts to create a new role, username and password and the current list of SQL privileges can be found in Last Pass in this note, Aspenware-Unity SQL Security Privileges.

IMPORTANT: The minimum server requirements for Unity are:

Processors - 4(+) x 2.60GHz+ 64-bit
Installed memory (RAM) – 16 GB
Disk space – 158 GB

Detailed Setup Guide

1. Install Unity

Create directories, UnityTest and UnityProd. These can be created anywhere but we typically create in c:\inetpub\wwwroot
In IIS, create new Application Pools using all defaults
1. UnityTest
2. UnityProd
In IIS, under the website entry being used (typically Default Web Site) convert UnityTest/UnityProd to an application. Right click on UnityTest/UnityProd and select, ‘Convert to Application’.
1. Update Application Pool to match newly created application pool
2. Accept all other defaults
3. If you don’t you don’t see UnityTest listed in IIS, refresh the website list or create manually by right clicking on Default Web Site (or the website name being used) and selecting ‘Add Application’
  1. Define Alias as UnityTest or UnityProd
  2. Define Application Pool as UntiyTest or UnityProd
  3. Define Physical Path as C:\inetpub\wwwroot\UnityTest or C:\inetpub\wwwroot\UnityProd
  4. Click OK
In File Explorer, right click on UnityTest and select Properties
1. Give Full Control of directory to new IIS Application Pool user.
2. Go to Properties / Security tab on directory and click Edit
3. Go to Properties / Security tab on directory and click Edit
4. Click Add
5. Add new security user and define the Location to be the local machine. Enter object name in the format, IIS AppPool\<newapppoolname> (i.e. IIS AppPool\UnityTest)
6. If entered correctly, the user will be found after clicking ‘Check Names’:
7. Click OK and then give Full Control
8. Update the Unity app pool Advanced setting "Maximum Worker Processes" from 1 to equal to or greater than the number of logical processors (Minimum 4).
  1. Run this Powershell to check:
    1. (Get-CimInstance Win32_ComputerSystem).NumberOfLogicalProcessors

2. Configure Unity

Several configuration files need to be updated after the Unity install. Typically these files are located in, C:\inetpub\wwwroot\UnityTest (or UnityProd). Always recycle the IIS app pool after making changes.

Appsettings.json
1. Update these URL’s to match the customer server name
  1. "BaseUrl": "https://unityserver/UnityTest/",
  2. "IdentityUrl": "https://unityserver/UnityTest/"
  3. "PublicOriginUrl": "https://unityserver" **No trailing backslash or Unity app name
2. Update Log settings - depending on whether you want a lot of logging or the minimum, set appropriately based on the below settings.
  1. For more logging:
    "LogLevel": { "Default": "Debug" "RequestTracingEnabled": true,
  2. For less logging:
    "LogLevel": { "Default": "Warning" "RequestTracingEnabled": false,
3. Update Application Insights Key (get from dev ops)
```
  "ApplicationInsights": {
    "InstrumentationKey": "KEY-HERE"
```
nLog.config - contains more log settings and also the same Application Insights Key as the appsetting.json. Whenever you want to setup more logging, change these settings along with the above and then change them back when you want less logging.
1. For more logging
```
		
		<logger name="*" minlevel="Trace" writeTo="allfile" />
```
2. For less logging
```
		
		<logger name="*" minlevel="Warn" writeTo="allfile" />
```
3. Update or add Application Insights key
```
    <target xsi:type="ApplicationInsightsTarget" name="aiTarget">
      <instrumentationKey>KEY-HERE</instrumentationKey>
    </target>
```
4. Set minLevel to “Info' (search file for this as there are several entries that are very similar)
```
    <logger name="*" minlevel="Info" writeTo="aiTarget" />
```

identity-config.json - this files contains the Unity ClientID, ClientSecret and all the scopes Unity supports. We have a tool that can create the ClientSecret as a hash value so check with Kevin on this.

Update ClientID and ClientSecrets value

      "ClientId": "AWUnity", // a client credentials client
      "ClientSecrets": [
        { "Value": "7m3T***********************OYo=" }
      ],

Scopes - we don’t typically have to adjust these but we do occasionally add new ones. For example, when AW Payment Plans were added, we added the ‘service.payment’ scope so that needed to be added to each customer using this functionality.

      "Name": "service.payment",
      "Scopes": [
        { "Name": "service.payment" }
      ]
    }
    
    "AllowedScopes": [ "services", "service.user", "service.customer", "service.entitlement", "service.media", "service.product", "service.order", "service.itinerary", "service.worker", "service.access", "service.contact", "service.account", "service.loyalty", "service.payment" ],

Rtp-config.json – contains RTP database, server and SQL login info, as well as RTP admin settings. We occasionally add to the list of settings with new versions and these settings need to be added manually because we do not update the rtp-config.json file with each Unity auto-deployment. Below is a list of settings and descriptions.

"DBVersionNumber": "2014.2.0.14", //2016.1.1.7	Set to either, 2014.2.0.14 or 2016.1.1.7 depending on the version of RTP being used. This determines how credit cards are saved into RTP.
"SourceTag": "UNITY-PK-", "SourceId": "UNITY-PK",	Used to create the RTP Alternate ID Profile. Update ‘PK’ to whatever makes sense for each resort. Do not change after customers start logging in.
"RelativeRoleCode": 1035,	Set value to match the RTP RoleCode for a ‘relative'. This value can be found in RTP admin or the database in the Role table.
"PrimaryProfileTypeCode": 102, "AlternateIdProfileTypeCode": 102,	Set value to a newly created ProfileType code in RTP (always set these two settings to the same value). AW recommends creating a new Profile Type rather than using an existing on. After this is created, a new entry in RTP admin needs to be created in Profile Type for Profiles.
"SalesChannelCode": 1300,	Set value to the Sales Channel Code being used by the Commerce site.
"TempCustomerCode": 3010,	Set Value to the IPTypeCode for the Temporary Customer entry in the IPType table (usually 3010 but some customers are different)
"EncryptionToken"	No longer used. This setting can be removed.
"RetailInventoryLocationCode": 2500,	Set value to the RTP Inventory Location Code being used for RTP retail inventory sync.
"OrderProcessor": "Base",	Set value to Base is using Unity for Order Processing or Connect is using RTPConnect for Order Processing.
"RTPConnect": { "RTPConnectUrl": "https://unity.aspenwarecommerce.net/rtpconnect/supplierservice.asmx", "Security": { "SSLEnabled": true, "Name": "SupplierServiceSoap", "Mode": "Transport", "Transport": { "ClientCredentialType": "None", "ProxyCredentialType": "None"	These settings are only used if the above setting, “OrderProcessor” is set to Connect. If set to Connect, define the RTP Connect URL in the RTPConnectURL field and set SSLEnabled accordingly.
"AllowEntitlementPriceOverride": true,	Set value to true if AW Payment Plans are being used. If AW payment plans are not being used, this setting can be left as true or could be omitted from file.
"UseAlternateInventoryStoredProc": false,	Typically this should be set to false as the performance of RTP’s inventory stored procedure was improved in 2020. This setting was created to allow Unity to use an alternate version of RTP’s stored procedure which helped increase performance until RTP’s version was improved. Set to true if an alternate stored procedure is being used for RTP inventory pool inquires (i.e. AW_proc_publicGetProductInventoryPoolInventory.sql). Set to false (or remove setting) if the standard RTP inventory pool stored procedure is being used.
"VoucherProductHeaderCode": "evp", "VoucherPaymentMethodCode": 10, "StoredValueProductHeaderCode": "stv", "StoredValuePaymentMethodCode": 25, "GiftCardProductHeaderCode": "gcp", "GiftCardPaymentMethodCode": 501,	These settings are used in conjunction with AW Additional Payments. Define the general product header codes created for AW additional payment functionality along with the RTP Payment Method codes for voucher payments, gift cards and stored value.
"UserId": "awuser",	Define an RTP UserID that will be added as the OperatorID for anything created from the site (Customer Manager Profiles, Orders, Transactions, etc.)
"CurrencyCode": 1,	Define the RTP Currency Code being used by the site. Typically this is set to 1
"PaymentMethodCodeOrder": 4005, "PaymentMethodCodeFulfillment": 9999,	Set PaymentMethodCodeOrder to a newly created AW Clearing Payment Method code from RTP and set the PaymentMethodCodeFulfillment code to the RTP Deposit Applied Payment Method Code (typically 9999).
"SupplierCode": "1", "DistributorCode": "4",	If using RTPConnect, set SupplierCode to 1 and DistributorCode to the DisctributorCode being used by RTPConnect for Aspenware.
"ShippingFeeProductCode": "999899",	Set to the shipping fee product header code being used by the site (**This setting may not be used anymore)
"IPTypeCodeGuestCustomer":3014,	If using AW Guest Check-out, set value to the IPTypeCode for the Guest Checkout Customer Type entry in the IPType table
"ActivityBuffer": 10, "ActivityCutoffBuffer": 0,	If selling RTP Activities, these settings are used to determine if the RTP Activity lock has expired. So if the lock expires at 4:30:00 and it's set to 10 secs, then it will consider the lock is expired at 4:29:50 and try to get a new lock. This is to account for the amount of time after the order completes in AW but before it is processed into RTP by Unity.
"CanUpdateAlternateIdProfile": true,	Set Value to true. This allows a merged customer in RTP to get an updated Alternate ID Profile value.
"ConfigurationSettingCodes": [ { "Name": "SaleLocationCode", "Value": 1000 }	Leave this Value set to 1000. This is used to lookup the RTP Sale Location Code for various purposes.
Database": { "RTP": { // settings for RTP Database "ConnectionString": "Data Source=servernameORIP;Initial Catalog=databasename;Persist Security Info=True;User ID=sqluser;Password=sqlpassword;" }, "Support": { "ConnectionString": "Data Source=servernameORIP;Initial Catalog=databasename;Persist Security Info=True;User ID=sqluser;Password=sqlpassword;" }, "Arrivals": { "ConnectionString": "Data Source=servername;Initial Catalog=databasename;Persist Security Info=True;User ID=sqluser;Password=sqlpassword;MultipleActiveResultSets=true" }	Define database settings. There are three connection strings. RTP - define RTP database server, database name and SQL userID and password for accessing RTP. Support - define the same as RTP unless the customer has a ‘Custom’ database that stores validation stored procedures, alternate inventory pool stored procedures, etc. Arrivals - define Azure Arrival database server, database name and SQL userID and password for accessing the Arrival database. Get these values from DevOps.
"Stores": [ // store specific settings go in a "Store" config (1 to many stores) { "StoreName": "Peak", "SaleLocationCode": 1600, "AuditLocationCode": 1600, "SalesChannelCode": 1300, "ClientCode": 300, "DistributorCode": "4", "UsePaymentCardTokenTable": "true", "EncryptPaymentCardTokenValue": "false" }	Define Aspenware Commerce Store settings. There can be more than one Store in this section if there are multiple Stores on the same Nop instance (i.e. Peak Mountain, Peak Highlands, Peak Golf, etc.) Define values as follows. StoreName = define CompanyName from Nop Store table SaleLocationCode - define the RTP Sale Location Code attached to the ClientCode in this same section (look in RTP in Client admin). AuditLocationCode - define the RTP Audit Location Code attached to the ClientCode in this same section (look in RTP in Client admin). SalesChannelCode - define the Sales Channel Code being used by the site. The same setting is listed above outside of the Store section so set to the same. ClientCode - define the Client Code being used by the Store (can be different per Store). DistributorCode - define the RTP Distributor Code being used by RTP Connect (if using RTP Connect for Order Processing). UsePaymentCardTokenTable - only used if "DBVersionNumber": "2016.1.1.7". Set to ‘true’ if using Auth.NET or Payeezy. EncryptPaymentCardTokenValue - set to ‘true’ for Auth.NET and ‘false’ for Payeezy. These settings are not used for Square or Braintree.
"AllowPlaceholderAddress": false,	Set Value to false to prevent Unity from creating Address Profiles in RTP that do not contain full address information. This prevents Address Profiles from being created with only periods. Set to true to allow Address Profiles to be created with just a period in the address fields.
"LinkedRefundsEnabled": true,	Set Value to true to enable linked refunds for Square and Windcave. These are the only credit providers that supports this settings as of May of 2024. Set Value to false for other credit providers or do not have the setting added.
"ForceActivityProcessorToBase": true,	Set Value to true if customer is using RTPConnect to process orders. This allows for a faster search of activity availability on the PDP so recommend setting to true for all customers using Connect. The setting is ignored if using Base/Unity for order processing.
"MatchTaxCalculation": true,	When the MatchTaxCalculation setting is set to true, tax calculations in Unity will align with RTP calculations. RTP uses bankers rounding in most cases (see “Add a Penny Logic” exceptions below). This ensures a $0 balance when comparing orders in Unity and tax calculations in RTP.
"RentalOrderDescription": "AW Rental Order",	Optional setting that allows defining the RTP Order Header description for rental orders (orders that use a rental location). Without this setting, order descriptions will be the same as non-rental orders which is, ‘Aspenware Ecommerce Order’.