On-Premise Data Miner - Deployment Guide - Viva Engage (Yammer)

Please let us know via a support ticket when you have created the app, but do not send us the Client ID and/or Secret for this app.

 

Generic instructions for creating a Viva Engage app are available from here: https://docs.microsoft.com/en-us/rest/api/yammer/app-registration 

 

2.  Viva Engage Application Creation for Analytics Engine

In order for the user to log into SWOOP, an additional app needs to be created for end-user authentication.  

To create a Viva Engage application:

1. Login as a verified administrator.

2. Got to https://www.yammer.com/client_applications

3. Select 'Register New App'. Fill in all fields with sensible value (they will only been seen by the data miner operator). The 'Redirect URI' must be set to 'https://yourname.swoopanalytics.com' 

4. Click on the 'Basic' info for App end enter 'https://yourname.swoopanalytics.com' into Javascript Origins where 'yourname' is your allocated swoop analytics domain.

Please provide the Client ID and your Viva Engage Network (normally your corporate domain name) to us via a support ticket.  For security reasons do not include the 'Client Secret'.

 

In order to install the miner your instance will need to be created. We will do this on receipt of your 'Client ID' and let you know to proceed to step 3.

 

Configuration Parameter	Value
NAME	Your allocated SWOOP Analytics domain name (typically https://[clientname].swoopanalytics.com)
CLIENT_ID	Viva Engage application 'Client ID'  that has permission to access network.  This is also needed by the SWOOP Analytics Engine for access to the Javascript API
CLIENT_SECRET	Matching secret for ClientID above. Only used for miner.
REDIRECT	URL to your server.  This must also be configured as your 'Expected Redirect' for the Viva Engage Application identified by the 'Client ID'.  This must include 'https:'.
PROXY	Blank for none or host and address for HTTPS proxy in format 'host:port'.
OS	Either 'AWSLINUX', 'RHEL' (for Redhat Enterprise 7), 'RHEL8' (Redhat Enterprise 8)  or 'OTHER' if you want to try your luck (must support yum).
PASSPHRASE	A passphrase provided separately to decode the content contained in the script. Please Note: The code provided contains the credentials to update the SWOOP Analytics server. Keep it secure.

This script is design to work as a cloud init script but may also be run as user root as an install script.  When you run the script it will perform the following action (see comments in script):

1. Install package groups to support application ('Web Server' and 'PHP Support')
2. Configure PHP
3. Install files necessary to run the application
4. Install log rotator for miner
5. Install miner configuration file
6. Install miner scheduler (runs hourly)
7. Install miner code downloader in web server.

These options can be changed by editing the '/var/www/html/config.php' at a later stage.

You may like to allocate a separate mount point (on separate disk) for the miner data (so you can snapshot and restore separately).   All the data is stored by default in '/data' for AWSLINUX and '/var/www/storage' for RHEL.

Please also change firewall settings (for network and machine) to allow access to the web server on your server (e.g. for RHEL   firewall-cmd --zone=public --permanent --add-service=http;firewall-cmd --reload ).

Miner Installation for AWS Linux

These instruction describe the critical configuration required to spin up the miner in AWS:

1. Launch a new instance in AWS using the 'Amazon Linux' 64 bit  AMI - Next.
2. Selection instance size (minimum t.2small) - Next.
3. On step '3' copy/paste (or upload) the completed (with configuration parameters filled in) installation script into 'User Data' - Next
4. On step '4' add a new volume on device '/dev/sdb'.  This will become your data disk. - Next
5. Complete the rest of the process as required.

Once the miner has spun up you can look at /var/log/cloud-init-output.log to determine progress.

Miner SSL configuration

Viva Engage requires that the SSL be configured on the miner to support authentication.  

There are two options:

1. Rely on the certificates (self signed) installed on the server and ignore the errors you get in the browser.
2. Install your own certificates base on the host name.

In the case of option 2 you will need to add the certificates to the server.   The relevant files are as follows:

• SSL configuration file - /etc/httpd/conf.d/ssl.conf
• Certificate key file - /etc/pki/tls/private/localhost.key
• Certificate file - /etc/pki/tls/certs/localhost.crt
• CA Bundle file -  /etc/pki/tls/certs/ca-bundle.crt

All the files are in PEM format and the certificate key file should not be password protected.

If you are using the 'CA Bundle file'  you will need to uncomment it out in '/etc/httpd/conf.d/ssl.conf'  by removing the '#' (i.e. change '#SSLCACertificateFile /etc/pki/tls/certs/ca-bundle.crt' to 'SSLCACertificateFile /etc/pki/tls/certs/ca-bundle.crt').

Firewall Configuration

To report mining progress and check for maintenance tasks, the miner will need to be given outgoing access to port 8443 and the domain admin.swoopanalytics.com.  

Miner Operation

Once you have installed the script you will need to login with a Viva Engage user that has network admin permissions. This should be a dedicated account for the miner as it may affect the users' day-to-day operation of Viva Engage.

To do this, start up the root page by going to the 'REDIRECT' Url from above.

This will:

1. Download the latest version of the Viva Engage miner from the SWOOP Analytics engine (this is transparent). If your proxy is not configured properly you will find out here.
2. Request permissions for access to Viva Engage.
3. Test the Viva Engage connection and display a message that updates can proceed.

Updates will then be scheduled on an hourly basis and no other action is required.

Enabling and Configuring Sentiment and Keyword Analysis

Enabling Sentiment Analysis

If your SWOOP subscription includes sentiment analysis, then add the following configuration for the miner by editing the '/var/www/html/config.php' file:

$config->SentimentEnabled = 'Yes';
$config->SentimentAPI = 'https://<generated>.cognitiveservices.azure.com/text/analytics/v3.0/sentiment';
$config->SentimentAPISubscription ='<32 character subscription key>';

Obtain Azure Cognitive Services '32 Character Subscription Key' via the Microsoft Azure Portal. Click on "Show Access Keys" and then look at the hex value in "Key1".

Enabling Keyword Analysis

If your SWOOP subscription includes keyword analysis, then add the following configuration for the miner by editing the '/var/www/html/config.php' file:

$config->KeywordsEnabled = 'Yes';
$config->KeywordsAPI = 'https://<generated>.cognitiveservices.azure.com/text/analytics/v3.0/keyPhrases';
$config->KeywordsAPISubscription = "<32 character subscription key>";

Obtain Azure Cognitive Services '32 Character Subscription Key' via the Microsoft Azure Portal. Click on "Show Access Keys" and then look at the hex value in "Key1".

...

After the miner setup is completed, Sentiment and Keyword Analysis can be tested with the following commands (from the directory where index.php is installed, which is usually "/var/www/html".

php index.php --sentiment "Alexander of Macedon, and he that dressed his mules, when once dead both came to one.
php index.php --keyword "Alexander of Macedon, and he that dressed his mules, when once dead both came to one.

In both cases, if configured correctly, a short report summarising the sentiment and keywords in the quotation will be displayed.

 

5. Updating the Miner

Please select one of the options below depending on convenience:

Option 1 - Configuring automatic updates (recommended)

Tick the checkbox under Update Option and then click Save Changes.

If the above Update Option doesn't exist then your miner may be too old and need to be updated manually before automatic updates can be configured.

Option 2 - Via the web browser

The miner can be updated by logging on to the miner and clicking the 'Update Software':

The new version of the miner will be shown when the screen refreshes.

Option 3 - Via the server console or ssh

If you are on the server console the miner can be updated with the following sequence of commands: