Invarosoft Deployment Guide

Modified on Mon, Oct 2, 2023 at 8:06 AM

Obtaining the Agent Installer
Our Activation Process
User Authentication Process
- Activation & Authentication Response Codes
- Removal/Uninstallation of Agent
  - Uninstall & Remove ITSupportPanel Configuration
  - Complete uninstall & configuration wipe

Obtaining the Agent Installer

Invarosoft supplies a CDN download for our agent installer, this ensures both quick access to our agent installer and ensures you are always using the latest version of our agent installer for your deployments.

Base Download URLs

Our most basic format of download URLs are as follows, these will deliver an MSI or EXE file installer.

MSI Install	https://goto.invarosoft.com/?id=latest-win-msi
Bootstrapped EXE	https://goto.invarosoft.com/?id=latest-win-exe

Pre-named MSI Installer

The following download URL format is used to pre-configure the name of the installer for automatic activation.

https://goto.invarosoft.com/?id=latest-win-msi&code=<activationcode>

e.g. https://goto.invarosoft.com/?id=latest-win-msi&code=ABCDEFGHIJ

You can read more about our activation procedures on Page 5.

Storing Our Installer Locally

If you wish to store our installer on your server and/or on client file shares this option is available to you, however, please ensure you put a process in place to ensure you keep these installers up to date as future changes to our code may cause older installers to present errors/failures.

Our Activation Process

The first step post installation of our agent is to activate the agent. Agent activation associates the agent with both your Invarosoft partner record as well as attaching it to the appropriate client in your partner account

Activation Codes

Invarosoft activation codes are a 10 character alpha value; these are globally unique for each client record across our entire partner base. An activation code will never change once it has been created & assigned to a client record in our system.

Activation during Installation

There are two methods available to activate our agent as part of the MSI installation, these two options are provided to give you flexibility in your deployment scripting;

MSI Parameter

Our MSI installer will collect the parameter ACTIVATE when the MSI is being used with msiexec.exe, in order to use this method write your deployment script to format the following process execution;

msiexec.exe /i <msi file> /q ACTIVATION=<code>

e.g. msiexec.exe /i c:\installers\itsp.installer.msi /q ACTIVATION=ABCDEFGHIJ

MSI File Name

Our MSI installer will collect the activation code from the MSI file name, in order to use this method, include the activation code in the name of the msi file as follows;

itsp.installer_<code>.msi

e.g. itsp.installer_ABCDEFGHIJ.msi

See “Pre-named MSI Installer” on page 2 above for instructions on how to pre-name the downloaded file with the activation code for use in this method.

NOTE These methods will not work to re-activate or change the activation of an agent. Please use

these methods for install & activation of a new agent only.

Activating after Installation

To activate after the agent has been installed you can issue the following command against our service executable;

itsp.windows.service.exe activate <activationcode>

e.g. itsp.windows.service.exe activate ABCDEFGHIJ

Deactivating after Installation

To deactivate after the agent has been installed you can issue the following command against our service executable;

itsp.windows.service.exe deactivate

e.g. itsp.windows.service.exe deactivate

NOTE Our agent bin directory is registered to the windows PATH variable, for this reason command

line commands can be issued from any path in the windows operating system.

User Authentication Process

After the agent has been activated, the next step is to ensure the agent is signed is as the appropriate user. User Authentication allows a personalised experience for that individual user.

All features of our agent that do not require a user will function, this helps engage your end users into the Invarosoft experience.

If the user attempts to use a function that requires user identification the user will at that time be prompted to register or login.

Authentication Methods

We provide a number of methods to our partners to facilitate getting your users logged into our agent. These methods are;

AD Harvester (Fully Automated)
First Ticket Log Identification
Manual Registration (User Interactive)
Assignment (both to agent & agent user contexts)
Agent Locked User
Client Locked User

Following is an explanation of each method.

AD Harvester

The AD Harvester allows for the auto authentication of users when the agents are running in a Microsoft Active Directory managed network. This method requires establishment of an AD Harvester on the networks domain controller.

When setup users are automatically logged in based on a relationship established between the windows user account and the PSA user/contact record.

For more information about the AD Harvester please see the resources available in the Invarosoft Portal.

First Ticket Log Identification

This method follows the same logic as the Manual Registration below with one key difference.

When the user is completing their first ticket, they will be asked for their first name, last name & email, if the manual registration method would have been successful the ticket is processed into our system and a confirmation email is dispatched to the email address used asking the user to confirm their identity.

Once the user confirms their identity, two things occur;

The ticket being held in our system is released to the PSA.
An “Assignment – Agent User Assign” is executed thus logging in the user’s agent.

To outline this please see the following flowchart;

Manual Registration

Our manual user registration method will check the user against the user list available in Invarosoft for the client. To explain the verification process here please see the following flowchart;

The registration email contains the information the user then needs to enter into the login screen of the agent.

We don’t recommend this method since it involves more work from the client’s users.

Assignment – Agent Assign

Using the “Assign” button under the “Users” column on the agent screen in the Invarosoft portal will “queue” the user selected for collection by the agent.

If there is more than one instance of the application running on the agent endpoint then it is on a FIFS (First-In- First-Served) basis, for this reason, we recommend only using this method on single-user profile agents.

NOTE This is NOT permanent on the server side, once an assignment has been consumed on the agent side it becomes unset server side. See “Agent Locked User” below for locking an agent to a specific user.

Assignment – Agent User Assign

Using the “Manage” button under the “Users” column on the agent screen will take you to a sub-screen listing out the users who have been witnessed on that particular agent. This list is populated with user records when the agent has run for the first time for that user on the agent in question.

This method is not affected by multi user environments. This is because the assignment is targeted at the particular user context not the agent as a whole.

Agent Locked User

This setting is available under the “Edit” screen of the agent, when set it will force login to the selected user for any instance of the agent running on that endpoint.

NOTE You cannot logout the agent when using this method, any attempt to logout will result in the

immediate re-login

Client Locked User

This setting is available under the “Edit” screen of the client, when set it will force login to the seected user for any agent activated against the client.

NOTE You cannot logout the agent when using this method, any attempt to logout will result in the

immediate re-login.

Activation & Authentication Response Codes

To help understand the outcome of activation, registration & login failures we have a set of response codes that will explain to our partners the exact problem encounter that returned the error to the end user. In most cases these response codes will allow you to resolve the issue without involvement of the Invarosoft support team.

Activation Response Codes

The following response codes will be returned to unsuccessful attempts to activate an agent;

[ACT-0]	This response code means an unhandled exception has occurred on our server. For further diagnosis, please send an email to [email protected] including the GUID presented in brackets shortly before the [ACT-0] code.
[ACT-1]	This response code means the request received by our server was malformed/corrupted. Ensure there is nothing (firewall filtering/AV/etc) interfering with the HTTPS POST event being sent to our API server (https://api.itspservice.net).
[ACT-2]	This response code means the activation code supplied is invalid. This will generally indicate a mis-key of the activation code by the user.
[ACT-3]	This response code means the clients user directory is not available. This is a server side fault with the clients setup. Please raise a request to [email protected] providing the activation code used along with the fact it generated a [ACT-3] error.
[ACT-4]	This response code means the creation of the agent on our platform failed. Please try again and if the problem persists raise an email to [email protected] for assistance.

Registration Response Codes

The following response codes will be returned to unsuccessful attempts to register a user;

[USU-1]	This response code means the user registration was successful but an error occurred when attempting to dispatch the registration email to a newly created user. We recommend trying again and if the problem persists, reach out to [email protected] giving us the agent name & email address used.
[USU-2]	This response code means the user creation failed (record did not return). We recommend trying again and if the problem persists, reach out to [email protected] giving us the agent name & email address used.
[USU-3]	This response code means the email address provided failed domain validation against other users in the same client. This will typically mean the user is using a non-company email address to attempt registration. To resolve simply manually create the user.
[USU-4]	This response code means an unhandled exception has occurred on our server when trying to create a user. For further diagnosis, please send an email to [email protected] including the GUID presented in brackets shortly before the [USU-4] code.
[USU-5]	This response code means the request received by our server was malformed/corrupted. Ensure there is nothing (firewall filtering/AV/etc) interfering with the HTTPS POST event being sent to our API server (https://api.itspservice.net).
[USU-6]	This response code means an unhandled exception has occurred on our server. For further diagnosis, please send an email to [email protected] including the GUID presented in brackets shortly before the [USU-6] code.
[USU-7]	This response code means the user registration was successful but there was a failure attempting to issue a password for the user. We recommend trying again and if the problem persists, reach out to [email protected] giving us the agent name & email address used.
[USU-8]	This response code means the user registration was successful but an error occurred when attempting to dispatch the registration email to an existing user. We recommend trying again and if the problem persists, reach out to [email protected] giving us the agent name & email address used.
[USU-9]	This response code means we located a user record for the email address supplied but the record is in an inactive state either in the PSA or Invarosoft Portal. To resolve this focus on ensuring the desired user record is active.
[USU-10]	This response code means we found multiple user records for the email address supplied. To resolve this focus on ensuring the desired user record is active.

The following response codes will be returned to unsuccessful attempts to login to an agent;

[USO-1]	This response code means the user credentials being supplied do not exist for the client the agent is activated against, in this instance the verification is excluding inactive users.
[USO-2]	This response code means the credential check returned more than one user record. This should not happen, please raise an email to [email protected] providing the email address used as a username as well as the agent name the response occurred on.
[USO-3]	This response code means the user credentials being supplied do not exist for the client the agent is activated against, in this instance it also includes inactive users.
[USO-4]	This response code means the user credentials being supplied exist but the user is inactive in the PSA.
[USO-5]	This response code means the user credentials being supplied exist but the user is inactive in the Invarosoft Portal.
[USO-6]	This response code should never occur (else statement in code path), if it does please email [email protected] with the agent name & email address used for us to review.
[USO-7]	This response code means that more than one inactive user was found. To resolve this focus on ensuring the desired user record is active.
[USO-8]	This response code means the request received by our server was malformed/corrupted. Ensure there is nothing (firewall filtering/AV/etc) interfering with the HTTPS POST event being sent to our API server (https://api.itspservice.net).
[USO-9]	This response code means an unhandled exception has occurred on our server. For further diagnosis please send an email to [email protected] including the GUID presented in brackets shortly before the [USO-0] code.

Removal/Uninstallation of Agent

In the unfortunate case you wish to uninstall ITSupportPanel from your agents please use the following methods;

Uninstall & Remove ITSupportPanel Configuration

The following command will uninstall ITSupportPanel leaving behind the configuration data. Use this method if you wish to run a new install maintaining the configuration;

itsp.windows.service.exe remove

NOTE Our agent bin directory is registered to the windows PATH variable, for this reason, command line commands can be issued from any path in the windows operating system.

Complete uninstalling & configuration wipe

The following command will uninstall ITSupportPanel & wipe the configuration (activation/etc) at the same time;

itsp.windows.service.exe removeclean

NOTE Our agent bin directory is registered to the windows PATH variable, for this reason command line commands can be issued from any path in the windows operating system