ARBUTUS WebConnect Software Installation Guide

ARBUTUS WebConnect Software

Copyright

Copyright © 2023 Arbutus Software Inc. All rights reserved.
This manual may contain dated information. Use of these materials is based on the understanding that this manual may not contain all the information, or the most current information, relevant to an intended application. Support and update services are available by separate written agreement.
Published December 2023 by:

Arbutus Software Inc.
270 – 6450 Roberts Street Burnaby, British Columbia Canada V5G 4E1
Phone: +1-604-437-7873
Fax: +1-604-437-7872
E-mail: Info@ArbutusSoftware.com
Web: www.ArbutusSoftware.com

“Arbutus”, Analyzer, “ConnectPlus”, “Smart Link for SAP”, and “WebConnect” are registered trademarks of Arbutus, or one of its subsidiaries or licensors. Use of a term in this manual should not be regarded as affecting the validity of any trade or service mark.

About this Guide

This guide is provided to licensed users of Arbutus WebConnect to provide quick instructions on installing and configuring it.
For more information about our products and services, visit our web site at: www.ArbutusSoftware.com

Need Help?
Contacting Us
If you have suggestions for improvements or if you can not find a solution to a problem, you can contact technical support for assistance. Please include:

• Your serial number.
• A description of what you were doing when the problem occurred.
• The error message, if any encountered.

Support Center

• Global Help Desk
  • Phone: +1-604-437-7873 or +1-877-333-6336 ext. 333
  • Fax: +1-604-437-7872
  • E-mail: support@ArbutusSoftware.com
• Or write to us at:
  • Arbutus Software Inc. 270 – 6450 Roberts Street Burnaby, BC Canada V5G 4E1

INSTALLING ARBUTUS WEB CONNECT

This section describes how to install and update Arbutus WebConnect. WebCon- nect requires installation of the corresponding version of the Arbutus Hub Server.

WebConnect Installation (Windows)
Arbutus does not currently use a MSI based installer but rather a zip file of all the parts required, which are in turn ‘installed’ and configured via a simple DOS batch file. If necessary this DOS batch file and corresponding httpd.conf file may be edited before running install.bat to ensure maximum compatibility with your system and network environment. It should be noted that if you have no existing Web Server running on port 80 on the same machine used to install WebConnect and you are OK with the default install location, you will still be required to edit the IP address and hostname of the Web Server in httpd.conf. Please ask your network administrator for appro-priate information. To ensure the most efficient install, it is recommended that WebConnect is installed on a machine that is not already running another web server.

Installation
To install WebConnect, perform the following simple steps:

1. Download WebConnect from the Arbutus downloads page: https://www.arbutussoftware.com/en/download-software
2. Create a folder and copy EMandWCInstaller.zip to this folder
3. Unzip EMandWCInstaller.zip
4. Navigate to …\EMandWCInstaller\InstallFiles
5. Right-click on the install.bat and choose ‘Run as Administrator’
   Note: You could also open an Administrator command prompt and CD to the install.bat location and run it from the command prompt.
   Note: Python 3.5 (32bit) will only be installed if it is not on your system. (“Python 3.12 – 32 Bit”

Once WebConnect is installed you should be able to navigate to both: http://<hostname/IP>:port//webconnect and http://<hostname/IP>:port//admin

You will be required to configure WebConnect via the admin port before your user can use it. Please review the “Configuring Arbutus WebConnect” on page 7 for more details.

Updating an Existing Installation
When updating an existing installation, you must first run the uninstall.bat Running the uninstall.bat will create a backup of your existing configuration and database settings. Running the install.bat will restore these settings once the install is complete.

Configuration
If you do required modifications, the files that can be edited by the administrator of WebConnect are:

• install.bat
• httpd.conf
• uninstall.bat
• settings.py

Install.bat

The default install location on the server is defined in the variable WEBAPPS_ BASE in the file install.bat, and has a default value set to “C:\Arbutus”. You may change this path, however if you do so, you must use a path that has NO spaces in it. This in turn will assist in defining the variable WEBAPPS_HOME (i.e. WEBAPPS_HOME=%WEBAPPS_BASE%\WEBAPPS). For example: WEBAPPS_HOME -> “C:\Arbutus\WEBAPPS”

Windows 10 Operating Systems
If the operating system of the machine is native Windows 10 or higher, these machines no longer contain a “Program Files (x86) folder (unless the operating system was upgraded from Windows 7 or 8 to Windows 10).
As a result, you will have to edit the install.bat to comment out the (x86) path for Python and un-comment the alternate Windows 10 Program Files path for Python – the end result should look like this:

set PYTHON_PATH=”C:\Program Files\Python312-32″
:: set PYTHON_PATH=”C:\Program Files (x86)\Python312-32”

Nothing else should require modification within the install.bat. There are various comments throughout the file to determine what each of the steps do.
Note: The value of the WEBAPPSHOME variable in httpd.conf and the value of WEBAPPS BASE variable in the uninstall.bat must be changed to match what is specified in the install.bat

Httpd.conf

Most sections in httpd.conf that may require modification include a comment line that starts with:
‘# ARBUTUS NOTE –‘

1. Change the WEBAPPS_HOME variable to match the full absolute path used in install.bat: Define WEBAPPS_HOME “C:/Arbutus/WEBAPPS” …
2. 2. Change the listening port (this is required if an existing web server is already installed and allocated to port 80): Listen 80
3. Change the network or WebConnect administrator email address: ServerAdmin admin@example.com …
4. If your localhost doesn’t have a registered DNS name, enter the host’s IP address as well as the port number (as entered in step 2 above): ServerName localhost:80 …
   There are other areas that can be fine-tuned in httpd.conf but should not be modified unless approved by the network administrator.
   Note: To determine if and what may already be listening on port 80 (HTTP) and/or 443 (HTTPS) you can open a command prompt as administrator and enter netstat –ab or netstat –ao.

HTTPS and Certificates
We highly recommend that you use HTTPS for secure communications between your user’s browsers and WebConnect. WebConnect will have both HTTPS and HTTP enabled with the Apache Web Server upon installation, however, you should contact your network administrator for assistance in an appropriate SSL certificate being configured and used to prevent browser warnings. Edit Extra \Httpd-ssl.conf accordingly.

Note: Without the use of HTTPS, when users log into WebConnect their login password will not be encrypted. This could compromise the security of your Windows server and/or net-work as the user’s user name and password will be transmitted insecurely from the user’s browser to the WebConnect Web server.1

Settings.py
This file can be found in: “…\WEBAPPS\App\connectanywhere\connectanywhere\”

The settings.py file can only be edited post installation, after making all neces-sary changes to the install.bat and the httpd.conf files. In the case where you have modified the ServerName in httpd.conf to something other than 127.0.0.1 or localhost, you will have to add ServerName value to the variable ALLOWED_HOSTS by appending your particular server name to the exist-ing list, for example: ALLOWED_HOSTS = [‘127.0.0.1’, ‘localhost’, ‘CustomServerNameOrIP’, ]

Uninstall.bat
Change the WEBAPPS_BASE variable to match the value used in the install.bat and update any other hard coded paths that were modified in the install.bat. If Python 3.12 (32 Bit) was installed by the install.bat and you no longer require it, you will have to manually remove it via Programs and Features. The uninstall.bat will always backup the following files: Settings.py, httpd.conf and the database file arbutus_db.sqlite3 in the WEBAPPS_BASE directory.
Note: To update an existing WebConnect installation, you must first uninstall the existing installation using the uninstall.bat

Python 3.12 – 32 Bit
Python 3.12 (32 Bit) is a requirement of the WebConnect Installation, however if install.bat detects that it is already installed, it will not re- install. It should be noted that the system Python will only have pip, virtualenv and vir-tualenvwrapper site packages added to it. All the WebConnect specific libraries will be contained in their own virtualenv located in Env\arbutus so as to alter the Python system installation as little as possible. Actually, besides Python, the com-plete WebConnect installation is all self-contained in the directory specified by WEBAPPS_HOME in the Install.bat.

CONFIGURING ARBUTUS WEBCONNECT

Logging In
Navigate to the hostname/IP of the Webconnect website with “admin” as the sub URL path. For example: http://webconnect_demo.com/admin/
The authentication details for administration default to a username of ‘admin’ and a password of ‘adminpassword’ After successfully logging in you will be redirected to the administration section of WebConnect, where you, as the administrator of WebConnect, provide the necessary meta data required for WebConnect and its users to successfully com-municate with the commissioned WebApp Server.

Configuring Tables
There are five primary configuration tables that are required to be populated with relevant data:

• Global configs
• Server profiles
• Shared folders
• User profiles
• Variable descriptions

All of these tables can be added to, edited or deleted. ‘Global configs’ is a special case in that there is only ever one instance (record) that can be edited.

Global Configurations
You must add a GlobalConfiguration model and save it, even if you do not require modifying any of the available default options.

User Prepended Prefix
The first item to be edited in the ‘Global configs’ table is the User Prepended Pre-fix – this specifies a an optional default prepended prefix that can be used as the default prefix for all users. The advantage of this prefix is that it requires very little user specific setup, and makes WebConnect available quickly to users with just some minor folder setup conventions on the server file system. For example, as the administrator, if you specify a prepended prefix of ‘C:\tmp’ then all users will by default inherit a user prefix of ‘C:\tmp\’, where is the username used for authentication. The only prerequisite of this is that you have in advance created all the necessary folders with appropriate permissions on the server. For example, using our example of a User Prepended Prefix of “C:\tmp”:

• C:\tmp\dewey
• C:\tmp\huey
• C:\tmp\louie

Where dewey, huey and louie are usernames that will be authenticating with WebConnect.

• Corporate Logo
  WebConnect allows the option to upload and display your corporate logo centered on WebConnect’s web pages. Simply click Choose File to select the logo image to be displayed.

• Show Data Tables
  This option shows tables in the users shared folder. By default this is set on. Turn off if you do not want to display tables.

• Show Private Folders
  This option displays the users private shared folder. By default this is set on. Turn of if you do not want to display the users private shared folder.

Server Profiles
The ‘Server profiles’ table should be edited to:

• specify the default ‘Webapp Server’ for communication with WebConnect.
• specify the server profiles that WebConnect uses to communicate with any Arbutus servers that are referenced in your procedures.
• allow necessary server profiles to populate an internal server profiles file
  Note:Currently, only one ‘WebApp server’ can be specified at this time. In a future release, we may support multiple WebApp servers being made available to WebConnect.

Users
The Users table should be edited to specify the list of active directory users who will access the specified server profiles and the related content (table and pro-cedures) when logged into WebConnect.
If an active directory user does not exist, you can create them by clicking the ‘+’ icon. The created user can then be added to have access to specified server pro-files.
Note: You can hold the CTRL key to mass select and associate multiple users to the specified server profile.

User Details

• Server Type – the list of supported Arbutus Server types. Select the appro-priate platform type where your Arbutus Server is installed.
• Name – the server profile name label for the specified Arbutus Server.
• Port – the port number that the specified Arbutus Server is listening on for connections
• Timeout – the number of seconds that Arbutus Server will be idle before timing out
• Encryption – the level of encryption for data sent between WebConnect and Arbutus Server.
• Compression – the level of compression for data sent between WebCon-nect and Arbutus Server.
• WebApp server – see comments above, only one WebApp server can be designated at a time.

Shared Folders
The Shared Folders table lists all shared folders that are located on the WebApp Server to which are that an Arbutus Server and its users are associated. This is typically common folder locations shared among many users, or it could be restricted to a sub-group of users.
From the users perspective, the shared folders will dictate what the user will see in the left hand tree view when they log into WebConnect. As long as all users associated with the shared folder have the correct file permissions, they will see all folders, tables and procedures contained within each shared folder.

When selected:

• tables will be viewable in a scrollable grid view
• procedures will display an explanatory note (if any) on running the pro-cedure and any required inputs, plus text boxes to enter any required vari-ables (and to display any previously assigned values). Users can accept the pre-assigned values (if any) or enter relevant values
• procedures can be run by highlighting the procedure name and clicking the RUN button on the bottom of the left hand tree view

Shared Folder Details

• Users – a list of active directory users who will see this shared folder and its contents when logging into WebConnect. If an active directory user does not exist, you can create them by clicking the ‘+’ icon. The created user can then be added to have access to specified server profiles.
  Note: You can hold the CTRL key to mass select and associate multiple users to the specified shared folder.

• Name – is the label that will be displayed in WebConnect for this shared folder

• Path – is the physical file path on the specified Arbutus Server

• Default – If selected, all newly added users will have this shared folder auto-matically associated with them

• Server Profile – displays selected server profile, allows choice of server pro-file and allows addition of new server profile. Also allows user to edit exist-ing server profile.

Variable Descriptions
The variable descriptions table lists all global variable names that are made avail-able to all assigned users and can be referenced in procedures run by users. Vari-ables can be added and default values edited. When running a procedure, users can change a variables value as needed. Variables will display their prior values to aid efficiency.

Variable Details

• Column name – is not editable and is automatically assigned by WebCon-nect
• Column description – is the label for the variable and how it is to ref-erenced within procedures
• Column title – is an optional descriptive title to display in place of the column description
• User editable – defaults to ON. When set to ON, the user is able to change this value when they select the procedure in WebConnect. If set OFF, they are unable to edit the variables value that was assigned by the admin-istrator
• User viewable – defaults to ON. If set ON, the user is able to view this value when they select the procedure in WebConnect. If set OFF, they are unable to view it or edit the variables value that was assigned by the administrator
• Batches: If list is empty, all procedures will have access to this variable. If a procedure or list of procedures (separated by commas) are entered then ONLY those specified procedures will have access to this variable

There is also a special internal variable that can be referenced in procedures without being added to the variable descriptions shown below. It is called ‘user_prefix’ and is automatically populated from the value entered in the user profile prefix – see “User Profile Details” on page 11 for more details. This allows you convenient access to each users output prefix value without hav-ing to set it up again in variable descriptions.

common situation when you might want to use this variable is where the Notify command is used in a procedure and you need to specify the full attach-ment path for an output file, perhaps an exported file, that has been saved to the users output prefix folder.

ASSIGN attachment_path=user_prefix+”\EXCELFILE.XLSX”
NOTIFY SENDER “AUser@arbutussoftware.com” MAILBOX “localhost” PORT 25 ADDRESS “%batch_address%” SUBJECT “%batch_subject%” MESSAGE “%batch_message%” ATTACHMENT “%attachment_path%”

User profiles
The User Profiles table lists all valid users. Users can be added to this list or their information edited. A user will automatically be added to the user profile table if they successfully authenticate with the Arbutus server. Once authenticated, a user will be able to see any default Shared Folders they have been granted access to by the admin-istrator. The administrator can also manually add users in advance of them logging into the WebConnect system successfully for the first time. This would allow the administrator to setup a customized shared folder and environment for them before they login.

User Profile Details

• Username – must be the exact same username that is their Active Dir-ectory Windows Server login. This is either entered upfront by the admin-istrator or will be automatically populated if the user has already successfully logged in.

• Prefix – the private folder on the Arbutus Windows Server where all output from procedures run by the user will be placed by default. This is the user’s private sandbox.
  Note: If the admin has previously setup the Global configs with a prepended prefix, this value can remain blank. However if you want more granular control over each users private folders, the administrator can specify a private folder prefix here and it will be used instead.

• The remaining items are a list of variables and their corresponding values that the user has permission to view and/or edit.

Setting up the Arbutus Server
For more detailed information on establishing Server Profiles for users and set-ting up Enterprise Shared Folders, see the following associated documentation:

• Analyzer Help
• Analyzer Installation Guide
• Arbutus Hub Server Installation Guide

Setting up Procedures (Scripts) For Use in WebConnect
There are some basic steps in setting up procedures (scripts) for use in WebCon-nect.

Adding User Variables To Procedures
Once you have established the variable inputs that are to be provided to the users (editable or not), these variable names must be referenced in the pro- cedure for their values to be utilized. So the administrator must edit the pro-cedures that are to use these variables and substitute in the variable names directly or via macro susbtitution as required to enable their usage. It is important to note that the use of variable inputs is the intended best prac-tice for user input in WebConnect.

Configuring A Single Simple Dialog Command In Procedures
Use of a single simplified Dialog command is allowed in WebConnect but is not a best practice. User Variables are the recommended best practice for user input. Procedures in Web Connect are treated like scheduled jobs, so though a single simplified Dialog command is supported in a procedure, the Dialog command must be at the top of the procedure surrounded by Schedule Start and Schedule End commands – see the Analyzer Help for specific details.
Note: Accept and Pause commands are not supported in WebConnect scripts. These com-mands must be removed from any scripts you intend to use in WebConnect.

References

• Arbutus Analytics
• Arbutus I Download Software

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>