Installation Guide-V3

PostedSeptember 17, 2020

Installation Guide

1 Prolaborate Architecture

Here is an overview of the components involved in setting up Prolaborate:

2 Pre-requisites

2.1 App Server Specifications

The following are the minimum requirements. The deployment will depend on usage and other environmental factors.

Memory	8.0GB
CPU	2.4 GHz x 4
Disk Space	20 GB

If you think the number of concurrent users will be more than 100, recommended memory and CPU is 16.0 GB and ‘2.4GHz x 8’ respectively.

2.2 Database Server specifications

Memory	4.0 GB
CPU	2.4 GHz x 4
Disk Space	20 GB

2.3 Supported Operating Systems

Windows Server 2012
Windows Server 2012 R2
Windows Server 2016
Windows Server 2019
Windows 7 – SP1 Required
Windows 8 +
Windows 10

Note:

An user with admin privileges is needed.

Windows Server is recommended for larger organizations.

2.4 Supported Enterprise Architect Databases

SQL Server 2008 R2 and above
SQL Server Express 2008 R2 and above
MySQL Server 5.6 and 5.7
Oracle Server
Postgres SQL Server
MariaDB server

We don’t support Firebird database as of now.

Note:

An EA user with appropriate permissions should be present for each EA database. Note that Active Directory credentials cannot be used.

If you are using Postgres database, run the following query in all the repositories:
create extension hstore

2.5 EA Database Drivers

The following driver versions need to be used for optimal performance:

32-bit ODBC driver between versions 5.2.4 and 5.3.6 for MySQL databases (Read More)
V10.00 for Postgres SQL databases (Read More)
OLE/DB driver for Oracle databases (Read More)

2.6 Pro Cloud Server Configuration

Only Pro Cloud Server versions above V4.0 are supported.

If you are using Microsoft SQL database, you need to use SQL server credentials; Active Directory credentials cannot be used.

2.7 Supported Prolaborate Databases

SQL Server 2008 R2 and above (recommended)
SQL Server Express 2008 R2 and above
MySQL Server 5.6 and above

The following details of Prolaborate database should be readily available before the installation:

Server Name/IP Address
Database name
Username
Password

Refer to Appendix to learn about setting up SQL or MySQL servers.

‘SQL Server Authentication’ mode is preferred. Active Directory logins are not supported.

2.8 Software

The softwares that are needed are

Internet Information Service (IIS) 7.5 and above
Microsoft .Net Framework 4.5 and above.

It is recommended to install the .NET Framework after installing IIS. If you install IIS after installing .Net Framework, you will probably need to register ASP.Net for use with IIS Ports and protocols. Please refer Appendix for more details.

Enable required Features in Windows

Go to Control Panel > Programs > Programs and Features > Turn Windows features on or off.
Click next on Installation Type and Server selection steps
In Server Roles step, select Web Server. Click on Add Feature in the popup.
In Features step, select ASP.NET 4.5
In Role Services step, select Application Development and all the options under it. Click on Add Features if prompted.

Installation will fail if these softwares are not installed.

2.9 Firewall / Port requirements

The following ports should be open:

Port of EA database(s); Pro Cloud Server (PCS) should be able to access the EA database(s)
Port of PCS; Prolaborate and Enterprise Architect should be able to connect to PCS. Default port (Http) is 804
Port of Prolaborate database; Prolaborate application should be able to connect to its database.
Port of Prolaborate application; End-users should be able to access Prolaborate website. You will be asked for an open port during installation of Prolaborate.
Port of WebSocket application; End-users should be able to receive real-time in-app notifications from Prolaborate application. You will be asked for an open port during installation of Prolaborate.WebSocket application establishes connection from the end-user’s browser to Prolaborate to let it send in-app notifications.

2.10 Supported Browsers

Prolaborate is compatible with following browsers:

Chrome 44 or above (recommended)
Firefox 38 or above
Safari 9 or above
Microsoft Edge 75 or above

A minimum screen resolution of 1280×720 is required for the best use of Prolaborate.

2.11 Optional Requirements

Enable HTTPS in Prolaborate Read more.
Enable SSL for EA Models. Check section 3.3 below.
Active Directory (AD): AD server should be accessible from Prolaborate. AD port should be opened Read more.
Mailer Configuration (SMTP): SMTP server should be accessible from Prolaborate. SMTP port should be opened Read more.
Confluence Integration: Prolaborate website should be accessible from Confluence i.e, it should be whitelisted in your security policies Read more.
Jira Integration: Prolaborate website should be able to connect with Jira i.e, it should be whitelisted in your security policies Read more.

Looking for cloud options to eliminate infrastructure woes? Learn more here .

3 Setup – Install and Configure Pro Cloud Server

3.1 Install Pro Cloud Server

The Pro Cloud Server installer is a standard Microsoft Installer; double click on it to start the installation and follow the onscreen steps.

3.2 Create License Request

Kindly follow these steps to configure the Pro Cloud Server:

Open Pro Cloud Config Client. Shortcut can be found in the desktop
Enter the Server Address as “localhost:803” and Password as “pcsadm1n” (default password) and click on OK
Click on Licensing
Click on Create Request and fill the details as per this link. Click on OK and save the license request file
Send the ‘License Request’ file to our Sales Team at sales[at]sparxsystems[dot]com

3.3 Install License

Our Sales Team will sign your request and return a License Certificate
Open Pro Cloud Config Client and go to Licensing window
Click on Add
Select and Open the License Certificate and the license will be added. Ensure the details are fine.

3.4 Configure Pro Cloud Server

Open Pro Cloud Config Client
Click on Add in the window and Add Database Manager window will pop up.
Click on Browse icon near the Connection String field and Data Link Properties window will popup. Select an option based on your EA database and complete the Configuration. (Refer to Appendix to read more about the configuration)
Give an Alias to the database you have just configured (Please give an appropriate name). You will need this Alias to connect to this EA database from EA and Prolaborate. Click on OK.
Click on the Database Manager just created and then click Edit
Enable Enabled and Enable Pro Features
Enable Require a secure and authenticated connection if SSL is enabled for your EA models. Leave it as unchecked if not. Click on OK

3.5 Connect with EA Models over HTTPS

.pfx file from your SSL certificate provider with its password and OpenSSL utility

To connect to your models over secured HTTPS connection, please do the following:

Place .pfx file in the bin folder (Typically located at C:\OpenSSL-Win32\bin\)
From the same bin folder, run OpenSSL.exe with administrative privileges and run the following command:
pkcs12 -in [certificate].pfx -out server.pem -nodes
[certificate] refers to the name of your .pfx file.
Enter password of the .pfx file when prompted.
server.pem will be generated in the same folder location
Copy the server.pem file and paste it in this folder
C:\Program Files (x86)\Sparx Systems\Pro Cloud Server\Service
Open SSProCloud.config file from the above mentioned path with edit privileges and update the second occurrence of SERVER_PORT from 805 to 443 (Standard port number of HTTPS connection) and REQUIRE_SSL to 1. If you want to disable HTTP connections, comment the first occurrence of SERVER_PORT by adding # at the start of the line
Restart “Sparx Systems Professional Cloud” service from the Task manager

4 Install Prolaborate

Please note that Prolaborate database needs to be created before you proceed with the installation.

4.1 Check Status Of Prerequisites

To start the installer, administrator privileges are required. Run “Setup.exe” as administrator. The installer will check the status of important components and show you the status. Click on “Next”

In the next dialogue box that appears, click on ‘Next’ to proceed.

4.2 Accept License Agreement

Please accept the terms in the license agreement to proceed with the installation.

4.3 Set Installation Mode

Choose the installation mode:

Choose Automatic and click on Next. The steps described further in this article are part of the Automatic installation process.

Automated Installation includes installation of Prolaborate components and required configurations (IIS setup, Database setup, Registry entry and configuration file setup).

In Manual Installation, only Prolaborate components will be installed but configuration (IIS setup, Database setup, Registry entry and configuration file setup) needs to be done manually.

Manual installation is not recommended unless there are some critical restrictions.

4.4 Set Installation Path

Choose a path to install Prolaborate.

4.5 Configure Prolaborate Database

Choose the Database server on which the Prolaborate database has been created.

Choose the installation mode to proceed further:

Choose Run Schema if this is a new installation. Choose Skip this step if you are trying to reinstall Prolaborate.

Choosing Fresh Installation while trying to reinstall Prolaborate will remove all Prolaborate configuration.

If you have chosen Microsoft SQL Server or MySQL, fill the details as below:

Password should not contain semicolon.

4.6 Configure Prolaborate Web App

4.6.1 IIS Server Setup

Port Number: Ensure that the Port is available and opened in the firewall settings.

Set the Site URL to either the IP address or DNS. Do not use “localhost”.

4.6.2 Setup Push Notifications

IP Address/ Host name : Machine IP or Machine name should be given

Port: Ensure that the Port is available and opened in the firewall settings.

4.6.3 Install Prolaborate

Please note down the login credentials shown in the installer. These are Super Admin credentials, with which you can login to Prolaborate.

Click on ‘Install’ to install Prolaborate.

Once the Installation is complete, the following screen will appear:

Select ‘Finish’ to complete the installation.

4.7 Troubleshoot Installation

Refer to this guide to troubleshoot issues with the installation

4.8 Set Session Timeout

Follow these steps to set the time you want the Prolaborate sessions to be active:

Open IIS Manager
Click On Application Pools
Select Prolaborate application
Click on Advanced Settings
Set your session time out using Idle Time-out. For example, enter 480 if you want to set the time out to 8 hours

5 Create Data Cache

Enabling and creating Data Cache is an one-time activity. Prolaborate relies on this data cache to show live diagrams and linked documents to its users.

EA 13.0 or earlier versions

Open Pro Cloud Config Client.Click on a Database Manager > Edit.

Enable Periodically Generate Diagram Images for WebEA & Prolaborate option.

Click on Configure and enter the following information.

Port	Select the Port which you are using to connect to this EA repository
Model User	Enter a valid repository user. Ignore if model security is not enabled
Model Password	Enter the password for the repository user. Ignore if model security is not enabled
Interval (seconds)	Set the default value is 30 seconds

Click OK.

Restart the Sparx Systems Professional Cloud service from the task manager.

EA 13.5

Click on Options in the Configure tab. In the popup that opens up, under Data Cache, check the two check boxes and click on Create.

EA 14, 15 or above

Click on Options in the Configure tab. Click on Cloud, check both the options under Data Cache and click on Create. Click on Create again.

6 Getting Started with Prolaborate

In order to get started with Prolaborate, please follow the below guides.

Install License – You will need to have the right licenses installed, for your users to have complete access to the application.

Add Repositories – A repository is the first thing you see once you login to your account. Prolaborate users can only manage repositories which they have access to; New Repositories can be created by the Prolaborate administrator only.

Configure Sections – You will need to define which packages from the EA are to be accessed through Prolaborate.

Set up Access Permissions – An admin can use this feature to give controlled access to users or groups in Prolaborate, the web platform for Enterprise Architecture.

Set up Guest Access – The guest sign-up feature allows anybody to quickly sign up and gain a read-only access to the application.

Configure SMTP – Emails for Activations, Notifications, Reviews, etc. are sent out from Prolaborate through the SMTP server. Thus, in order to receive emails without any issues, SMTP should be properly configured.

Setup Active Directory – The Active Directory feature enables the users, configured in your Active Directory, to login to Prolaborate with the same credentials.

Add Users – Users are the participants working together in a particular repository. Users can view and configure the repository as per their individual access rights provided by the Prolaborate administrator.

7 Appendix

7.1 Register Asp .Net Libraries

Run Cmd prompt in admin mode
32-bit Windows
1. %windir%\Microsoft.NET\Framework\v4.0.30319\aspnet_regiis.exe –i
64-bit Windows
1. %windir%\Microsoft.NET\Framework\v4.0.30319\aspnet_regiis.exe –i
Restart IIS Server (using IIS Manager)

7.2 Enterprise Architect and Pro Cloud Server Compatibility Report

The following report gives details of the compatibility based on our extensive tests.

	Server	Server	Server	Client	Client	Client	Client
Case #	EA Worker Available	EA Availability	EA Version	EA Version 13.5	EA Version 13.1	EA Version 12	EA Version 11
1	Yes	Yes	13.5	Compatible	Compatible	Not Compatible	Not Compatible
2	Yes	Yes	13.1	Compatible	Compatible	Compatible	Compatible
3	Yes	Yes	12	Compatible	Compatible	Compatible	Compatible
4	Yes	Yes	11	Compatible	Compatible	Compatible	Compatible
5	No	Yes	13.5	Compatible	Compatible	Not Compatible	Not Compatible
6	No	Yes	13.1	Not Compatible	Not Compatible	Not Compatible	Not Compatible
7	No	Yes	12	Not Compatible	Not Compatible	Not Compatible	Not Compatible
8	No	Yes	11	Compatible	Compatible	Not Compatible	Not Compatible
9	Yes	No	Not Applicable	Not Applicable	Compatible	Compatible	Compatible

PCS version 2.0.15 was used for the analysis.

7.3 How To Open a Port

Make sure the firewall is enabled by confirming that “Firewall state” is set to ‘On’ and not to ‘Off’.

Step 1: Open the Server Manager from the task bar.

Step 2: In the right-hand side of the top navigation bar, click on ‘Tools’ and select Windows Firewall with Advanced Security.

Step 3: Select either of the Inbound Rules under Windows Firewall with Advanced Security on the left side of the management console.

Step 4: From the right side of the Inbound Rules tab click on ‘New Rule’. The new rule wizard launches.

Step 5: Select ‘PORT’ and click ‘Next’.

Step 6: Select ‘TCP’ and click ‘Next’.

Step 7: Select ‘Specific local ports’ and enter the Port number which needs to be opened and click on ‘Next’.

Step 8: Select ‘Allow the connection’ and click ‘Next’.

Step 9: Make sure all Domains, Private and Public are checked and click ‘Next’.

Step 10: Specify the Name and Description for the port and click ‘Finish’.

7.4 Setup Sql Server

7.4.1 Enable Sql Server Authentication

‘SQL server authentication’ must be enabled and an admin account must be created. The following settings must be accomplished

Step 1. Create a new Database called Prolaborate

Step 2. Create a new user by using the ‘New Login’ option under Security -> Login section

Step 3. Uncheck ‘Enforce password policy’

Step 4. Set the default database to ‘Prolaborate’

Step 5. Configure ‘Server Roles’, grant access to all admin privileges.

Step 6. ‘User Mapping’, maps the Prolaborate database to the new user.

Step 7. Configure ‘Status’ as shown below:

7.5 Setup MySQL Server

7.5.1 Prolaborate Database

Please follow the below steps:

Step 1. Open MySQL Workbench and create a new connection

Step 2. Open the new connection

Step 3. Create new database called Prolaborate and click on Apply

Step 4. Click on Apply

Step 5. Click on Finish

7.5.2 EA Repositories

Repeat steps 2 to 5 from the above section to create a database for EA model and run the below necessary scripts in the EA database

EA Schema_1220 (Download link here )
EA Base Schema 1220 (Download link here )

Do these steps after doing the above.

Step 1. Open ODBC Data Sources

Step 2. Click on System DSN an then on Add

Step 3. Select MySQL ODBC 5.2 Unicode Driver and click on Finish

Step 4. Now MySQL Connector/ODBC Data Source Configuration window will open.

Enter the following details

Field	Description
Data Source Name	Give a Name to the DSN. Example, EA model
TCP/IP Server	Server where EA database was created
Port	Port of the above server
User and Password	Credentials to login to the Database server
Database	Select the database created for EA model

Click on Test to test the connection. Correct the details or check the connectivity if the test is not successful.

Step 5. Click on Details Under Connection select the options as show in screenshot below:.

Step 6. Click on Cursors/Results and select the option show in screenshot below:

7.6 Setup Pro Cloud Server

7.6.1 Port Settings

Setting	Description
SERVER_PORT	The port on which the server will listen for HTTP connections; each connection must be unique and not used by any other services on the machine. You must check that no firewalls are blocking this port on the client or server. You can use the standard HTTP port (80) or HTTPS port (443). When changing this, check firewall settings and other services using that port. Additionally, when the service is running on Wine you should not use privileged ports – those below 1024. Under Wine, most applications are only able to listen on ports above 1024.
REQUIRE_SSL	Should be set to 1 to enable HTTPS on this port; HTTPS should be enabled for all connections that are being exposed on public networks. HTTPS requires a private key file (server.pem), to be included in the same directory as the configuration file, before it will run. This unique file must be user-created. See Creating a Self-Signed Certificate using OpenSSL.
DEFAULT_MODEL	Allows a single model to be exposed on a port, making it possible to use a different port for each model. Model names are discussed further in the Connecting Enterprise Architect to a Cloud Server topic.
MODEL_AUTHENTICATION	Can be set to 1 to request HTTP authorization using the user security defined in the Enterprise Architect model being connected to. Passwords must be explicitly and individually assigned in that model using the Maintain Users procedure; the default administrator password and any passwords imported from Windows Active Directory do not work. Note that if you are not using SSL to connect, the usernames and passwords will be sent in plain text. If the model does not have security enabled, the Cloud user is not prompted for a password.This option is mutually exclusive with GLOBAL_AUTHENTICATION.
GLOBAL_AUTHENTICATION	Can be set to the name of an Enterprise Architect model with security enabled that will provide the list of users for all models accessed by the connection. This is helpful if you want to provide multiple models but only manage one list of users. Passwords must be explicitly and individually assigned in the reference model using the Maintain Users procedure; the default administrator password and any passwords imported from Windows Active Directory do not work.This option is mutually exclusive with MODEL_AUTHENTICATION.
OSLC_SUPPORT	Enabled by default. It allows models to be queried using the ‘Open Services for Lifecycle Collaboration’ standard. This is discussed further in the OSLC Requirements Management topic.Set to 0 to disable.

7.6.2 Cloud Services Configuration Client

Item	Description
Database Managers	This panel lists the defined repositories. Each row contains two columns of information – the database connection string of the repository and the number of active and available connections.
Refresh	Click on this button to reload the contents of the ‘Database Managers’ list.
Add	Click on this button to display the dialog on which you define a new database.
Remove	Click on this button to permanently delete the selected database from the Cloud Server.
Configure	Click on this button to display the dialog on which you change the settings for the currently selected database.
Server Options	Click on this button to display the dialog on which you change the Cloud Server global options.

7.6.3 Cloud Services Logon Screen

Cloud services log on:

Option	Description
Server Address	The Server Address format is:(ServerURI):(Port)The server URI can be ‘localhost’, an IP address, a DNS name or a machine name; for example, MyWebServer. If you are working on the web server, ‘localhost’ will be sufficient.
Password	Enter the password you defined in Management Client Connection Settings, in the Cloud Server Configuration topic. By default this password is blank; you can reset it to a new value, as described in the Help topic Global Server Options.
OK	Click on this button to log in to the Management Client.

7.7 Install .Net 4.5 Framework

Setup Microsoft .NET 4.5 Framework. Download the latest Microsoft .NET Framework 4.5 from Microsoft

This step is not needed if you are running versions higher than Windows 8.0 and Windows Server 2012

7.8 Enable required Features in Windows

7.8.1 Configuration

Step 1. Under Control Panel-> Programs -> Programs and Features -> Turn Windows features on or off.

Step 2. Click next on Installation Type and Server selection steps

Step 3. In Server Roles step, enable the following:

Step 4. In Features step, enable the following

Continue the steps and complete the installation.

7.8.2 Start IIS Server

Step 1. To start the server, type “inetmgr” in the Run Window and click on “Ok”.

Step 2. In the ‘Internet Information Service Manager’, select the Local host and click on ‘start’.

Step 3. Expand the server and under ‘sites’, you will find the option ‘Default Web Site’. Select this and click ‘Start’.

Step 4. After starting the site, select ‘Browse’. It should open the default website on the browser.

Step 5. Ensure that the Internet Information Services landing page is displayed in the default web browser.