Sharperlight – Instance Management Command Line Automation

Instances allows Sharperlight to run multiple times with different Client Settings and DataModels on the same computer.  This is most often setup on a Sharperlight Application Server where the Clients are then setup to remotely connection to one or more of the Service Instances.

Multi-tenancy in the cloud on for example Azure or AWS would be another example where Instance Management would be used.  To assist with the automation of new Sharperlight Instances Sharperlight allows command line creation and deleting of instances.  When creating new instances all the required configuration setting can be set a parameter file.  One can use PowerShell or JavaScript for example to modify or create the parameter file with all the new details of the Client including the namespace, security and licenses.

Other related posts Instance Management Setting up multiple Service Instances and Instance Management Monitoring Health and Status

 

Create Instance

Create a new Instance 1618 command Line example

Delete Instance 1618 command Line example

Download

Parameter File Example

Recommendations

It’s best to create a template Sharperlight database that contains all the common database related settings. A template Sharperlight database is created by connecting Sharperlight to a template database and then running Site Setup and Publisher to create a baseline.  For example in Site Setup you may setup default users for admin and support and user groups and then set default product setting.  Sometimes you may want to base the users on a Datamodel and so you would set Site Setup to sync with the desired Datamodel so users and password would be driven by that external system.

Before running the command line to create the new instance one could use Powershell to then restore the template Sharperlight database with the desired name.  Then the command line would be run with just the required settings in the parameter file to override client specific Site Setup details and to set the Instance and Client Setup details which are not held in the database.

Active Directory Accounts – Single Sign On

Note: If a virtual or synced Active Directory AD (Office 365 AD)  is used in the Cloud the Sharperlight Application Server can still validate and sign-in these accounts just like it was hosted locally.  The sign-in will need to be in the style of domain\username not username@staging-sharperlight-com.stackstaging.comdomain.com.  Also please ensure the Sharperlight Application Server has joined the Active Directory domain otherwise it will not work.

Command Line Account Permissions

To create a new instances one will require Windows admin elevated permissions. In addition to this you will need to setup a single sign on user account in Site Setup with admin permissions in the default/primary install of Sharperlight.  It is possible to put user name and password details into the command line for non-windows accounts but it’s recommended one sets up single sign on.  Once the new instance is created Sharperlight then tries to logon to the new Instance using it’s Database users.  It will try the same single sign on windows account and if that is not trusted, it will then try the user and password on the command line and then fall back to the default admin with not password account.  For this reason it’s best to trust your windows account in both the default/prime Sharperlight install and in the template Database that was used for the new Instance.

Instance ID

A four character unique ID is required when creating a new Instance and when left blank  instanceID: a new ID will be automatically assigned.  The file is a simple text file which name and value pairs that define the most relevant settings related to creating new Instances.

User Details

As outlined above it’s best to setup single sign on for a Window account in Site Setup in both the default/primary Sharperlight install and the Sharperlight template database.  In this way one can avoid having user and password details on the command line.

 

Example of the Parameter File

 

Feedback and Errors

There are two ways you can get the status of the command line execution.  One is a status file and the other is the Application Event Log.  Use the parameter “statusfile:filepath” to save the status to a file with will be basic text

The status file will contain the following if completed successfully

InstanceNew Complete Instance: 1618

The Application Event Log shows Information and any error during execution.  PowerShell or even Sharperlight Scheduler for example can be used to read the Window Application Event log and by the Source and Event ID determine if there were any errors or when the task is complete.  An example of an error would be the user account running the command line does not have admin permissions or the file can not be found.  If the command line successful completes the creation of a new Instance then Event ID 982 will appear in the Event Log.

Parameter File Format

The parameter file is a simple text file with name and value pairs.  For example  Instance.Description=Red Ribbon Instance.  Line comments start with the character #. Use PowerShell or some other language to modify a existing template file or create one from nothing.

Supported types of Settings

• All main Instance details such as the ID, Code and Description
• Client Setup – Datamodel Database Connection settings
• Client Setup – Service Details such as Authenication, Protocol and public domain name
• Client Setup – Email details used for user password reset etc
• Client Setup – Security Allow Remote Setup
• Site Setup – Company Details
• Site Setup – License file to import
• Site Setup – System Datamodel Settings such as Allow Scheduler Server Side
• Site Setup – General Datamodel Settings as defined by the Datamodel
• Site Setup – Whitelisting IP Addresses
• Site Setup – Create or Update User Group Basic Settings
• Site Setup – Create or Update User Basic Settings
• Service – Start the Sharperlight Windows Service after creation

 

Instance Manager File Settings

These are the core Instance settings.  Please take care to keep the Instance Code short and without special characters.   Also the Instance Description should be keep within 50 characters otherwise the window Service may fail due to this description being too long

 

Notice the parameter names will be very similar to the labels that appear in various Windows such as Instance Management, Client Setup and Site Setup.

 

Client Setup – Service File Settings

The Service details such as Authentication, Protocol, Ports and domains names.  Valid protocol setting would be http, https and tcp.  If https is used then you will need to setup the SSL certificate in IIS.

 

Client Setup – Datamodel Database Connection File Settings

Database Connection Details can be set by combining the Datamodel Code and the Property Description with the prefix Client.Setup.Connect.

When there are multiple Connection types use the .Index=# to set the ordinal position of the Connection Type in the list you wish to override.

 

Site Setup – Company Details File Settings

Site Setup – Whitelisting File Settings

Use a comma delimit to define the Whitelisted IP Addresses that will have access to the system. Leave blank if you don’t want to activate Whitelisting.

 

Site Setup – Product Settting File Settings

Each Product / Datamodel can have various global settings that may require setting. In this case the System Datamodel has various security related settings that you may want to set to False.  The settings are based on the Datamodel Code and the Property Description prefixed by Site.Setup.Settings.

Site Setup – User Groups File Settings

New User Groups can be created or existing User Groups updated in this section.  Use the prefix Site.Setup.Group. in combination with the User Group code followed by :: then the Property description.  If the User Group specified does not exist if it will be created otherwise it will update the existing User Group details

Site Setup – User File Settings

New Users  can be created or existing Users updated in this section.  Use the prefix Site.Setup.User. in combination with the User code followed by :: then the Property description.  If the User code specified does not exist if will be created it otherwise it will update the existing User details.

It is recommend that you add the current Window Account as a administrator so that the admin user on the Application Server can always get into Site Setup.  The special tag {_WindowsUserCurrent} can be used to pick up the current account.

Site.Setup.User.{_WindowsUserCurrent}::Disable=False
Site.Setup.User.{_WindowsUserCurrent}::Administrator=True

 

 

Start Sharperlight Windows Service

Start or Stop the Sharperlight Windows Service if all actions are done without errors.  If you want to leave the Service unchanged comment out this row.  Note that when creating or delete a Instance the Service will always be stopped to preventing it from blocking the process.