Atria v12.11+ Deployment Guide

Atria v12.11+ Deployment Guide

Overview 

This article outlines the deployment procedure of Atria v12.11+.  This article will also refer to other articles that may assist with your installation or upgrade.
Alert:  In-place migration from any version of CloudPortal Services Manager earlier than V11.5 CU4 is not supported 

System Requirements 

If you are migrating from a CloudPortal Services Manager or deploying into a new environment, you MUST complete the prerequisite components noted in the following article: Atria v12.11+ System Requirements

Before any installation, migration or upgrade always ensure successful server and database BACKUPS and SNAPSHOTS have been taken. 

Introduction to Atria Packages 

  1. Each installed component is a NUGET package - herein referred to as "Packages"   
    1. The package contains a set of files and some PowerShell code which is run to perform an install, migrate or upgrade.  
    2. They use a technology called NUGET - this is a simple mechanism that allows packages to be published, versioned and downloaded systematically via command-line utilities.    
    3. We publish versions of the packages to a NUGET gallery - this is like a web server that hosts the NUGET files.  
  2. CORE components for the system are : 
    1. configservice  a shared component used to centrally access configuration information.   
    2. database  installs/upgrades the SQL server database used by Atria.   
    3. directoryws  installs the key web service used for active directory authentication.   
    4. provisioning  installs the provisioning engine.
    5. platformapi installs the platform api
    6. web  installs the main web application onto the web server which is split into 4 components
      1. WebForms
      2. AtriaProxy
      3. Atria
      4. ExternalApi
  3. For  Services  there are one or two packages for each service.  
    1. <servicename>  relates to the installer which pushes the service configuration into the Atria system.  
    2. <servicename>ws  is the name of a web service installer, for that service (some services may not have a ws as they don't require a web service to be deployed).   
    3. For example, Exchange has a package and a web service:  
      1. exchange  deploys the service, it's schema, UI elements, provisioning rules, etc into Atria 
      2. exchangews deploys the Exchange web service. 
  4. Additional Information: Package Action Types (Only the database is being flagged as Migrate during the install - the rest are either Install or Upgrade)
    1. Install - clean/fresh install of Atria v12
    2. Migrate - v11.5 CU4 to Atria v12 (note: existing config, app, branding, other custom settings)
    3. Upgrade - Atria v12 to Atria v12.x
  5. Atria Deployment Approaches
    1. Fresh install of Atria v12.x - Deployment of a new installation of Atria v12.11
    2. CPSM to Atria v12.x (in-place or sideways migration) - In-place migration from CloudPortal Services Manager v11.5 CU4
      1. If you need to migrate server operating systems as part of your upgrade plan or you are running on a version below 11.5 CU4, please refer to the following article: Sideways Migration Process for Atria v12.11+
    3. Atria v12.6 to Atria v12.x
      1. If you need to upgrade from an earlier version of Atria v12 going to Atria v12.11+, please refer to the following article: Early Atria v12 to Atria v12.11+ upgrade

Prerequisite for the Atria Setup

During the process, allow any install/config changes related to PATH Environment Variable Change, NuGet Provider, PSRepository
  1. [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
  2. Install-Script Atria.Tools.Setup-Bootstrap

Install Atria.Tools module from the script

  1. cd 'C:\Program Files\WindowsPowershell\Scripts'
  2. .\Atria.Tools.Setup-Bootstrap.ps1 -username 'any username' -PersonalAccessToken 'access token provided by Automate101'
      This will install 2 Atria modules: Atria.Tools and Atria.Platform
        
Repeat these steps to each server that you will run the Atria package installers. For the database, you can run the install on the provisioning server since we will pass database server parameters when running the command to install.
Connection to the Atria Feed is for each user profile. For other users to connect to the Atria Feed, use the below command
  1. Connect-AtriaFeed -UserName 'any username' -PersonalAccessToken 'access token provided by Automate101' -FeedUrl 'https://pkgs.dev.azure.com/Automate101/A101/_packaging/Atria-Releases@Current/nuget/v2'

Atria Packages

PowerShell Command: Get-AtriaPackage | select identity, tags

Components Package List

Identity
Tags
Atria.<version>
web,component
ConfigService.<version>
ConfigService,component
Database.<version>
database,component
DirectoryWS.<version>
atriadirectoryws,activedirectory,component
ExternalApi.<version>
web,component
PlatformApi.<version>
web,component
provisioning.<version>
Provisioning,component
Proxy.<version>
web,component
WebForms.<version>
web,component

Server Package List

Identity
Tags
AzureAD.<version>
service-package
BlackBerry5.<version>
service-package
Citrix.<version>
service-package
CRM2011.<version>
service-package
DNS.<version>
service-package
Exchange.<version>
service-package
FSS.<version>
service-package
HostedAppsAndDesktops.<version>
service-package
MailArchiving.<version>
service-package
MFA.<version>
service-package
MicrosoftAdfs.<version>
service-package
MSOL.<version>
service-package
MySQL.<version>
service-package
office365.<version>
service-package
Sharefile.<version>
service-package
SharePoint.<version>
service-package
SharePoint2010.<version>
service-package
Sharepoint2013.<version>
service-package
SkypeForBusiness.<version>
service-package
Sql2005Hosting.<version>
service-package
VirtualMachine.<version>
service-package
WindowsWebHosting.<version>
service-package

Web Service Component Package List

Identity
Tags
CitrixWS.<version>
CitrixWS,component
ExchangeWS.<version>
ExchangeWS,component
MicrosoftAdfsWS.<version>
MicrosoftAdfsWS,component
MsolWS.<version>
MsolWS,component
MySqlWS.<version>
MySqlWs,component
SharepointWS.<version>
SharepointWS,component
SkypeForBusinessWS.<version>
SkypeForBusinessWS,component
VirtualMachineWS.<version>
VirtualMachineWS,component
WindowsWebHostingWS.<version>
WindowsWebHostingWS,component
XenAppWS.<version>
XenAppWS,component
XenDesktopWS.<version>
XenDesktopWS,component

Provisioning Server

ConfigService Component

Requirement: Domain Admin Credential, additionally being signed into the Provisioning Server as a Domain Admin user.
  1. $creds = (Get-Credential)
  2. Install-AtriaComponent -ConfigService -Credential $creds

Before Installing/Updating Database

Required to be done starting from v12.13

Requirement for Registering  Atria (details for each parameter set)
      Environment: 'Staging' or 'Production'
      CRMId: CRM Deployment Id - to be provided by Automate101 Support
      Customer: Customer Name
      
  1. Set-AtriaRegistrationDetails -Environment  'Production' | 'Staging'  -CRMId 'CRMId' -Customer 'CustomerName'

Database Component

This step can be initiated on the Provisioning Server. 
  1. Install-AtriaComponent -Database -ServerInstance 'ATRIASQL\instance' -ServerPort 'sqlport' -UseWindowsAuth
instance is optional depending on SQL Server setup
If using Windows Authentication, make sure that the account has sysadmin role into the database

Provisioning Component

  1. Install-AtriaComponent -Provisioning -CreateScheduledTasks 

Directory Web Service Component

  1. Install-AtriaComponent -Directory

PlatformAPI Component

  1. Install-AtriaComponent -PlatformAPI

Web Server (New)

Web Component

This will install 4 components (WebForms, Proxy, Atria, ExternalAPI)
  1. Install-AtriaComponent -Web

If DMZ or non-domain joined server,
$creds is the local user account being used
$primarycreds is the domain admin account used with ConfigService
The web server should be allowed to pass-thru 8095 port traffic going to the provisioning server
  1. $creds = (Get-Credential)
  2. $primarycreds = (Get-Credential)
  3. Install-AtriaComponent -Web -Credential $creds -PrimaryLocationCredential $primaryCreds -PrimaryConfigServiceBaseURL 'http://atriaconfigservice:8095/configservice'

Finalize Primary Location Setup

FOR NEW INSTALL, THIS IS IMPORTANT BEFORE PROCEEDING!
Using your browser, navigate to the front-end website - default is http://atriaweb/

1. The default platform account created is <installercredential_asp> and the password will be the domain account password used during the installation
2. After logging in, on the Atria Menu, select Configuration > System Manager > Server Roles
      a. Assign domain controller server role to the servers that will be used by the platform
      b. Click on Save
3. On the Atria Menu, select CustomersYou will notice that the customer name is "Service Provider - Change This" 
      a. Expand this customer and select Edit Customer
      b. Input the Service Provider name
      c. Update the domain management according to your environment
      d. Update other customer details as needed.
      e. Save and Provision the Customer
6. Go to the Users of the current Customer. You will notice that the only user is the <installercredential_asp>
      a. Expand and Edit the user <installercredential_asp>
      b. Expand Account Settings and then click on Advanced Options
      c. Make sure that "Service Schema Administrator" is enabled for this user
      d. Update other user details
      e. Provision the User
7.  Validate if provisioning is working successfully through the provisioning logs
      a. On the Atria Menu, select Configuration > Provisioning & Debug Tools > Provisioning Requests
      b. Provisioning Requests Overview should show green status on all the made requests above
      c. If Provisioning Requests reports are NOT showing green statusReport it to Automate101 Support
                                                                      Core Components Installation (Migration Complete)                                                                                                

Remote Location Deployments

Requirements

1. Add DNS Aliases on the Remote DC 
      - PrimaryConfigService DNS entry (Host) pointing to the Primary ConfigService IP Address 
      - AtriaSQL DNS entry (Host) pointing to the Database IP Address

2. Add an entry on the Site Bindings where the ConfigService was installed (IIS > Atria Web Services > Edit Site Bindings). 
      New Site Binding
            - Host Name: PrimaryConfigService
            - Port: 8095
      

Do not remove other default site binding entries

3. Make sure that the step on Atria.Tools.Setup-Bootstrap has been completed on the Remote Location Provisioning Server

Remote Location Components

Run the following PowerShell command on the server that will host the Remote Config Service, this is typically the Remote Provisioning Engine Server.  The Config Service is required for new installations as well as upgrades from CPSM.
ConfigService should have the same server time with the PrimaryConfigService
  1. $creds = (Get-Credential)
  2. $primaryCreds = (Get-Credential)
  3. Install-AtriaComponent -LocationComponents -Credential $creds -PrimaryLocationCredential $primaryCreds -PrimaryConfigServiceBaseURL 'http://primaryconfigservice:8095/configservice'
This will install the location components ConfigService, Provisioning and Directory web service on the Provisioning Server.

For a New Remote Location Install - Setup Server Credentials, Roles and Connection

  1. Navigate to Configuration > System Manager > Credentialsadd the DirectoryWS service account credentials from the remote location. To retrieve the details of the account and password, run this command: C:\Windows\system32\inetsrv\appcmd.exe list apppool /name:"$=atria*" /text:* | findstr "name: userName: password:"
  2. Navigate to Configuration > System Manager > Servers, then select the credentials for the DirectoryWS, this will then be used as a bridge connection going to Active Directory to get the servers within the domain
  3. Navigate to Configuration > System Manager > Server Roles, then apply roles for the Domain Controller. Directory role is by default set on where the DirectoryWS is located.
  4. Validate server connection for DirectoryWS via Configuration > System Manager > Server Connection ---- Test Connection

For a New Remote Location Install - Provisioning of Reseller - <Remote Location> and <First Remote Customer>

  1. Navigate to Customers and on the service provider customer, open Services
  2. Expand Reseller - <Remote Location>, update what needs to be configured and then Provision
  3. Provision a new customer under the remote location
                                                                              Remote Location Installation/Migration Complete                                                              

Services

Deploying services includes installing and configuring services for resources such as Microsoft Exchange, Citrix Apps and Desktops, and Office 365. Before deploying any service, you must ensure the resources supporting the service are fully deployed in your network environment. For example, to deploy the Hosted Exchange service, Atria requires you have a working Exchange deployment in your environment. 

Services must be installed or upgraded to enable the functionality within the Atria platform.  Once installed and configured you can offer that service to resellers and customers.  

All services have a Schema/Service Configuration as listed in the table in the following section, these must be installed on the Provisioning Engine server.  In addition to the Schema, some services require a Web Service to be installed to enable management of that service, this will typically be installed on the server that hosts that service.  A table of available Web Services is listed in the following section.

The service installer requires a login account within Atria that has the Schema Administrator role.

Service Installers (Schema/Service Configuration)

Run the following PowerShell command on the PRIMARY LOCATION Provisioning Engine Server.
By default the service schema import will be done against http://atriaweb if this binding is removed from the AtriaProxy IIS bindings then we need to set the APIUrlBase to be used.
To set it, kindly run the following commands on PowerShell (admin)
  1. Set-AtriaApiUrlBase -urlBase 'atriaproxy url binding'
To query out the changes made:
  1. Get-AtriaApiUrlBase
Here's a sample of a changed APIUrlBase

After setting this, all service schema imports will be done against the new APIUrlBase

     
      Setup the Atria Schema Credential     
This is the account in Atria UI that has Schema Administrator role
  1. $atriacreds = (Get-Credential)
  2. Set-AtriaServiceSchemaCredential -AtriaPortalCredential $atriacreds
      Import the Atria Service Schema      
For list of Atria Service Packages - refer to Atria Packages section Tip: you may hit tab to see the service names.
Services can be comma separated on this command (i.e. Import-AtriaServiceSchema -Service Sharepoint,SkypeForBusiness,Exchange)
  1. Import-AtriaServiceSchema -Service servicename

IMPORTANT STEP: After importing Service Schema, reset IIS on both provisioning and web server

On your command prompt/powershell (run as admin)
  1. iisreset


Web Service Installers

Before proceeding
When performing a migration (from CPSM v11.5 CU4 to Atria v12), STOP the existing web service associated.
Target Server will be depending on the type of service.
For each target server, you are required to setup the Atria.Tools module.
Make sure that the service supports both PowerShell 5.1 and .NET 4.8 Framework
Run the following PowerShell command on the server that will host the Web Service, this is typically a server that hosts that service.
If not yet installed, then run the Install-AtriaComponent -WebServiceName
Some Web Service have extra parameter set. Please refer to the table below.
Web Service Components
PowerShell Command
ADFS
Install-AtriaComponent -Adfs
Citrix
Install-AtriaComponent -Citrix
Exchange
Install-AtriaComponent -Exchange -ExchangeVersion 'exchange version' (2013, 2016, 2019)
HostedAppsAndDesktops (XenDesktop or XenApp)
Install-AtriaComponent -HostedAppsAndDesktops -HostedAppsVersion 'XenApp' or 'XenDesktop'
Microsoft ADFS
Install-AtriaComponent -MicrosoftAdfs
Microsoft Online (MSOL)
Install-AtriaComponent -MSOL -CreateScheduledTasks
MySQL
Install-AtriaComponent -MySql
SharePoint
Install-AtriaComponent -Sharepoint
Skype For Business
Install-AtriaComponent -SkypeForBusiness
Virtual Machine
Install-AtriaComponent -VirtualMachine
Windows Web Hosting
Install-AtriaComponent -WindowsWebHosting

Web Service Configuration and Application Settings Configuration

IMPORTANT UPDATE for CPSM Customers - The consolidated Web Service Configuration (web.config) has been split. Application-specific settings have moved to a separate config file appsettings.config
When performing a MIGRATION (v11.5CU4 to Atria), the web.config and appsettings.config will both be in a default state (out-of-the-box configuration), to apply your previous customization into the config file, you may retrieve the configuration details from the old web.config file that is located in the folder of the web service. This also applies to an old appsettings.config. Apply accordingly the required parameters and configurations that are set.

We suggest using a text editor that has a compare functionality/plug-in to help manage this. (Notepad++, Beyond Compare, etc.)

Location of old config files:
      Old CortexWeb - C:\inetpub\Cortex Management\CortexDotNet\
      Old CortexAPI - C:\inetpub\Cortex Management\CortexAPI\
      Old Provisioning Engine - C:\Program Files (x86)\Citrix\Cortex\Provisioning Engine   
      Old CortexService - C:\inetpub\CortexServices\<web service>\

Apply the necessary configurations and customizations to the new config files 
      AtriaWeb - C:\inetpub\Automate101\Atria\AtriaWeb\
      AtriaAPI - C:\inetpub\Automate101\Atria\AtriaWeb\CortexAPI\
      Provisioning Engine - C:\Program Files (x86)\Automate101\Atria\Provisioning Engine\
      AtriaWebService - C:\inetpub\Automate101\Atria\Atria Web Services\<web service>\

Server Connections

Apply the new credentials for server connections for each web service that is updated into Atria. By default, the old web app pool service account should still work, but we recommend updating it into the new Atria generated web app pool service accounts for clean up purposes in the future.

Service Deployments

Some service like Hosted Exchange, needs to be re-saved in order to make sure that the Mail Store Databases will be picked-up during provisioning of customer and users.

Recommendations

Enabling MFA within Atria

MFA is now built in as a service within Atria, the service package "atriamfa" must be imported to enable the MFA features (see above). 
For further details about Atria MFA please refer to the follow article:  Atria MFA

Activate within Atria
  1. Navigate to Configuration > System Manager > Service Deployment
  2. Locate the "Multi Factor Authentication Service"
  3. Enable the service
Enable for each location
  1. For each Active Directory Location, you will need to enable the service
  2. Ensure that there is a single customer plan created - the MFA Provider property must be set to the "Atria Provider"
  3. Save and apply changes to enable the service


Enable for each reseller and customer
  1. For each reseller and customer, provision the MFA service with default settings to enable it for provisioning to end-users.
Enforcing MFA for a user
Once the MFA service has been enabled to a customer, provision the MFA service to each user to enforce MFA, this will come into effect the next time they log in to Atria.

Setup Process
Once the MFA service has been provisioned to a user – when they authenticate to Atria the following screen will be presented:



Scan the QR Code with your authenticator App, this should then display a token – which should look something like this:



Enter the QR code, and click register – you are now set up with MFA and will now be prompted every time you login to provide the token.

Resetting the MFA Token
There are some cases when you may want to reset a token
  1. Phone with the token has been lost or stolen
  2. Phone with the token has been wiped
  3. User has a new phone and needs to transfer the token
Essentially, if the token (the phone) has been lost, you may need to recreate it.  

Option 1 – Administrator reset
  1. Locate the user
  2. Deprovision the service from the user 
  3. Reprovision the service to the user
Option 2 – Self-reset (cannot be done without phone/token) 
  1. Log in and authenticate
  2. Click on your login name at the top of the screen – this will take you to the password reset page
  3. At the bottom of the page you will get the option to
    1. Display your current token again – this allows you to have the same token on another device, or 
    2. Reset the token – this will create a new token and force you to re-validate the setup.

Branding

  1. For a new install, follow the implementation procedure in the following article: How to setup Atria portal branding
  2. For migration from v11.x or v11.5.x, previous customization on the portal branding can be applied using your CSS files and resources. The files can be located in the old path of the CortexWeb site files (C:\inetpub\Cortex Management\CortexDotNet)
  3. We also recommend to update and configure the Help Link within Atria to point to the Service Provider's internal support who will assist  the users of the panel.

Upgrade

Performing an upgrade applies to Atria v12 upgrading to a higher version (i.e. Atria v12.11 upgrading to Atria v12.12), any version below 12.x will first need to perform a migration.
Package Action Type : Upgrade
For upgrade run the following commands for each component on the appropriate server. Upgrade does not require any additional parameters.
  1. Update-AtriaComponent -ComponentName (configservice, database, provisioning, directory, platformapi, web)
  1. Update-AtriaComponent -WebServiceName (exchange, hostedappsanddesktops, msol, etc.)
Changes to this upgrade process may occur as we progress on releases, please refer back to this guide prior to each upgrade.

Testing

Once you have completed a migration or upgrade it is always important to test, a simple test plan is available in the following article: Atria Post Upgrade Checklist

    • Related Articles

    • Atria API User Guide (CortexAPI)

      Overview The application programming interface (API) is a powerful interface that allows you to interact directly with Atria without using the ATRIA Web User Interface (UI).  The API grants a user, with some development knowledge, the ability to ...
    • Atria Billing Setup User Guide

      Objective This article describes how to configure Atria to utilize the latest billing features. This document outlines the billing setup attributes that should be configured.    Applies to Introduced in Atria version 12.0.0 Billing Setup Overview To ...
    • Atria v12.11+ System Requirements

      Overview  The following article provides the prerequisites necessary for the deployment of Atria v12.11+ into your environment.  System Requirements   Environment  Core servers for the platform should be domain joined. Before you can deploy Atria ...
    • Billing Rules Engine User Guide

      Objective This article describes how to use the Atria billing rules engine to identify specific Atria entities as non-billable.   Applies to Introduced in Atria version 12.0.0 Billing Rule Feature Overview Many entities - customers, services, users, ...
    • Display Patterns for Billing Line Descriptions

      Purpose: When generating billing data, two descriptions are generated for each billable item - Line description (detailed) and summary descriptions.   The Summary Description serves two purpose: Used as a template for your invoice lines and reporting ...