Provision the new Add It page in existing Atlas workspaces

The new Add It page is not added automatically to the existing workspaces during the upgrade to 4.1, or any subsequent releases so that, current processes are not forced to change in existing Atlas workspaces. We recommend a script to be run on demand which will provision this new Add It page in all existing Atlas workspaces as well as alter the tenant property to ensure new Add It is applied to any new workspaces provisioned.

Due to related dependencies the existing workspaces need to first be at least version 4.1. Other Atlas workspaces are skipped. Hence before running this script, ensure that the 4.1 update has been completed successfully.

• Provision Atlas.ConneX API Client AAD application
• Manual changes to the Atlas.ConneX API Client AAD application
• Install PowerShell dependencies
• Preparing the script
• Running the script

Temporary Alternative to script

The script is our recommended approach, but if you have a delay in running the script, 2x tenant properties can be altered which will introduce a work around for users so that they can reach a new version of Add It.

Atlas.UseQuickAddit is a tenant property that when enabled will provision new Add It in any new workspaces.

 Atlas.QuickAddit.Url. will also need to be updated, which will send the user selecting Add It to another workspace where New Add It is configured. So although users can use new Add It, they will be taken outside of their current workspace and in to the centralised 'URL' to use Add It. This is the reason this is not a permenant solution and we recommend running the script below.

The re-directs looks like this. This is the URL produced when I select add it quick access logo from the main menu. You can see that I have landed in the Atlas Configuration site to use the 'quick Add It' (new add it), although the workspace that appears in Add It will display the previous workspace (in the URL below, TemujinLtd.

https://atlasdw.sharepoint.com/sites/atlasconfiguration/SitePages/Quick-Add-it.aspx?url=https://atlasdw.sharepoint.com/sites/TemujinLtd/

ScriptPre-Requisites

To work on the next steps, you must have access to the Azure Active Directory and have a role that allows to register applications and apply modification to security groups. It is usually recommended that a Global Administrator of the tenant performs these steps.

Provision Atlas.ConneX API Client AAD application

The script authenticates using the Atlas.ConneX API Client AAD application. If this application is not created, please refer to this article to provision the AAD application before running this script.

Manual changes to the Atlas.ConneX API Client AAD application

A number of additional manual changes are required to the new Atlas.ConneX API Client AAD application.  Please follow the following steps:

• Ensure that 'Allow public client flows' is enabled
  • Go to the Atlas.ConneX API Client Azure AD application 
  • Go to Authentication from the left menu
  • Click yes to enable 'Allow public client flows'
  • Click Save

• Upload the Atlas Certificate
  • Go to the Atlas.ConneX API Client Azure AD application 
  • Go to Certificates & secrets from the left menu
  • Click on the Certificates tab
  • Click Upload Certificate
  • Browse for the certificate file with the .cer extension and click add. The certificate file can be found in the installation folder you used when applying the last Atlas upgrade ("DeploymentFolder]\scripts\certificates\AtlasSelfSignedCertificate.cer").

• Add 'Sites.FullControl.All' permission
  • Go to the Atlas.ConneX API Client Azure AD application 
  • Go to API Permissions from the left menu
  • Click on Add a permission
  • Select SharePoint
  • Then select Application Permissions and browse for 'Sites.FullControl.All'
  • Select 'Sites.FullControl.All' and click Add permissions at the bottom of the screen.
  • Finally remember to 'Grant admin consent' for the newly added permission.

Install PowerShell dependencies

The script makes use of these 2 PowerShell modules which need to be installed before running the script.

1. PnP.PowerShell
2. JWTDetails

Use the 'Install-Module' command to install these PowerShell modules.

• Install-Module -Name "PnP.PowerShell" -RequiredVersion 1.7.0
• Install-Module -name "JWTDetails"

Note: For the script to be compatible with the Atlas deployment script it is required to run this script using PnP.PowerShell version 1.7.0.  If you have updated Atlas in your environment you may already have this version of PnP.PowerShell installed on your device.

Preparing the script

Ask your CSA/Implementation Consultant about these required files:

• Provision-QuickAddItPageInAllWorkspaces.ps1
  • This is the script file
• provision-quick-addit-page.xml
  • This is an input file with the page template required for provisioning the new page.

You will find the above files in a Compressed Folder provided by your CSA/Implementation Consultant.  Open your preferred PowerShell program to run the script. 

In order to retrieve all Atlas workspaces, the script needs to be executed by a user in the Atlas ConneX Enterprise Administrators group.

It is always suggested to run PowerShell as Administrator.

Running the script

The script uses the ConneX API to retrieve existing Atlas workspace and the SharePoint PnP Framework to provision the new page.

It authenticates using the Atlas ConneX API Client AAD application, which uses the resource from the Atlas ConneX API AAD application to consume the ConneX API.

The following input parameters are required to run the script:

TenantId	This is the Tenant ID of your Office 365 tenant where Atlas is installed.  This can be found by accessing the Azure Portal - Opening the Azure Active Directory - Overview
TenantName	This is the Name of the tenant. If the SharePoint tenant URL is https://clearpeople.sharepoint.com then the value for tenant name is 'clearpeople'.
ClientId	This is the Application (client) ID value of the Atlas.ConneX API Client AAD application where Atlas is Installed.  This can be found opening the Azure Portal - App Registrations - All Applications.
ServiceId	This is the Application (client) ID value of the Atlas.ConneX API AAD application where Atlas is Installed.
APIurl	This is the full URL of the ConneX API of the App Service. As an example, the value can be https://app-atlas-api-clearpeople-dev.azurewebsites.net The API Url can be retrieved from the Azure Resource Group where you instance of Atlas is deployed by following these steps: Go to the Azure Resource Group where your Atlas instance is deployed. Click on the App Service resource which should be in the following format: app-atlas-api-[ClientName]-[EnvironmentName] Find the API URL from the overview tab, as shown below
InputFilePath	This is the full local path including the filename where the xml file with the PnP template can be found. e.g. "C:\New Add It\New Quick Add It pages\provision-quick-addit-page.xml"
AtlasCertificateFilePath	This is the full local path including the filename where the file with the Atlas pfx version of the certificate is located. This can be found in the deployment files provided when deploying Atlas. Normally can be found in the following path: [DeploymentFolder]\scripts\certificates\AtlasSelfSignedCertificate.pfx
EncryptedPasswordFilePath	This is the full local path including the filename where the txt file containing the encrypted password. This can be found in the deployment files provided when deploying Atlas. Normally can be found in the following path: [DeploymentFolder]\scripts\certificates\encrypted.txt
SecureKeyFilePath	This is the full local path including the filename where the txt file containing the secure key. This can be found in the deployment files provided when deploying Atlas. Normally can be found in the following path: [DeploymentFolder]\scripts\certificates\key.txt

Finally, the script can be executed using all of the parameters as described in the table above.

While running, the scripts output the actions completed one workspace after the other:

Important:  Will have to sign-in via a URL and code that appears when executing the script (first yellow line in the above image).  May also require additional sign-in information:

• Email 
• Password
• MFA

You will also be asked to confirm that you are signing in to Atlas.ConneX API Client.