PigCHAMP Knowledge Software

P I G C H A M P , L L C

J U N E 2 0 2 0 E D I T I O N

Client Hosted APP (CHA) for Mobiles

Installation and Setup Manual

2

© PigCHAMP Knowledge Software 1531 Airport Rd Suite 101

Ames, IA 50010 Phone (515) 233-2551• Fax (515) 233-7187

3

Table of Contents

Chapter 1 ................................................................................................................... 4

PigCHAMP CHA Overview ..................................................................................... 4

Chapter 2 ................................................................................................................... 5

PigCHAMP Setup .................................................................................................... 5

Chapter 3 ................................................................................................................... 7

Remote Desktop Services (RDS) ............................................................................. 7

Internet Information Services (IIS) ........................................................................... 7

Domain - URL/SSL Setup ........................................................................................ 7

Chapter 4 ................................................................................................................. 12

CHA Web Service - Installation and Configuration ................................................ 12

Chapter 5 .................................................................................................................. 20

Testing and Troubleshooting .................................................................................. 20

4

1 P I G C H A M P

Chapter

Note PigCHAMP Enterprise version 8.7.1 or higher is needed to support CHA operation.

PigCHAMP Client Hosted

APP (CHA) Overview

igCHAMP Client Hosted App (CHA) is a set of software components that allows the PigCHAMP Mobile app installed on Android or iOS to communicate with a locally hosted PigCHAMP installation. It requires several components: PigCHAMP Enterprise Program licensed for mobile users, CHA web service, Microsoft Remote Desktop Services (RDS), and Microsoft Internet Information Services (IIS). This guide assumes that the hosting environment includes one Windows Server (OS 2012 or higher) configured as an app or web server and another Windows Server (OS 2012 or higher) configured as a SQL server.

PigCHAMP software uses Microsoft SQL Server as its database. Versions of Microsoft SQL Server supported by PigCHAMP include SQL 2014 and higher. When licensing the PigCHAMP program to support CHA , an additional database called PigOnline will be created in the same instance as your PigCHAMP database for CHA interfaces.

P

P I G C H A M P

5

2

Chapter

PigCHAMP Setup

igCHAMP Enterprise version 8.7.1 or higher must be installed prior to CHA setup. CHA is a licensed addition to PigCHAMP. If you do not currently have any mobile users licensed, you will have to purchase and receive a new PigCHAMP license that includes mobile users.

You can check if the PigCHAMP program is currently licensed for mobile users by going to Help > About and Registration. The Licensing Information tab will show number of mobile users licensed in the Other Features section as shown below.

P

P I G C H A M P

6

When you import the PigCHAMP license with mobile users, PigCHAMP will check for the existence of a database called PigOnline in the same instance as the PigCHAMP database. If it does not exist, PigCHAMP will create it. The PigOnline database handles authentication and connection tokens for authorized CHA mobile users. It is populated by the PigCHAMP program and the CHA web service. In the PigCHAMP program, you may now set up PigCHAMP users that have been assigned mobile access. To grant a PigCHAMP user mobile access, go to Users > User Account Administration and check the box for Mobile User. You can only establish as many simultaneous mobile users as you are licensed for. Note: This step may be performed later in the process, but users will not be able to connect via mobile until set up in PigCHAMP.

P I G C H A M P

7

3 Chapter

Remote Desktop Services (RDS)

Internet Information Services (IIS)

Domain - URL/SSL Setup here are several steps that must be completed to allow connection from your mobile device to your app or web server. These are all standard Microsoft products and configuration. Screenshots are from Microsoft Windows Server 2016.

Remote Desktop Services (RDS)

Note: If Remote Desktop Services are already configured, you may skip this step.

• Start Server Manager on the app server.

• Under Configure this local server, choose Add Roles and Features.

T

P I G C H A M P

8

o Installation Type: Remote Desktop Services Installation

o Deployment Type : Quick Start

o Deployment Scenario: Session-based desktop deployment

o Server Selection: choose server to install role on

o Confirm the options selected and click on Deploy.

• Reboot the server.

P I G C H A M P

9

Internet Information Services (IIS)

Note: If Internet Information Services are already configured, you may skip this step.

• Start Server Manager on the app server.

• Under Configure this local server, choose Add Roles and Features. o Installation Type: Role-based or feature-based installation o Server Selection: Select app server o Server Roles: Add the following roles/features if not already enabled

o Roles

Web Server

o Common HTTP Features

▪ Static Content

▪ Default Document

▪ Directory Browsing

▪ HTTP Errors

▪ HTTP Redirection

o Application Development

▪ ASP.NET

▪ .NET Extensibility

▪ ISAPI Extensions

▪ ISAPI Filters

o Health and Diagnostics

▪ HTTP Logging

▪ Logging Tools

▪ Request Monitor

▪ Tracing

▪ ODBC Logging

o Security

▪ Windows Authentication

▪ Request Filtering

o Performance

▪ Static Content Compression

o Management Tools

▪ IIS Management Console

o Features

.NET Framework 3.5 Features

o .NET Framework 3.5

o WCF Activation

▪ HTTP Activation

▪ Non-HTTP Activation

P I G C H A M P

10

.NET Framework 4.6 Features

o .NET Framework 4.6

o ASP.NET 4.6

o WCF Services

▪ HTTP Activation

▪ TCP Port Sharing

P I G C H A M P

11

Purchase a domain name URL and add an SSL

• Purchase a domain name URL used to connect your mobile device to the web service (i.e. online.yourcompany.com)

• Purchase an SSL Certificate for your URL (for secure connection) o SSL certificates are available from many domain registrars. One example is

Namecheap:

▪ https://www.namecheap.com/security/ssl-certificates/

▪ https://www.namecheap.com/support/knowledgebase/article.aspx/97

53/14/generating-a-csr-in-iis-10

▪ https://www.namecheap.com/support/knowledgebase/article.aspx/97

54/33/installing-an-ssl-certificate-on-iis-10

o You will receive a *.pfx file with the SSL certificate you purchased

• Start Server Manager on the app server.

o Click on Remote Desktop Services in left panel

▪ Go to Overview > Deployment overview > Tasks > Edit Deployment Properties

▪ Repeat the following steps for each installed role under ‘Certificates’:

• Choose Select existing certificate

• Browse to the .pfx file location

• Enter the password you chose when creating the .pfx file

• Enable Allow the certificate to be added to the Trusted Root Certification Authorities certificate store on the destination computers

P I G C H A M P

12

4

Chapter

CHA Web Service - Installation and

Configuration igCHAMP has a setup file that installs the PigCHAMP CHA web service files and Microsoft SQL Native Client software (if not previously installed). After these components are installed, additional configuration is required.

CHA Installation

Run PigCHAMP – CHA Setup executable file on the app/web server.

The first screen will ask which language the setup file will display. Choices are shown below. Select the language for the setup and click OK.

P

P I G C H A M P

13

PigCHAMP CHA setup will check for the existence of Microsoft SQL Native Client software. If Microsoft SQL Native Client 2012 has not previously been installed on the server, it will be installed now. Click through the screens using defaults as shown. You are required to accept the licensing agreement before you can complete the installation.

Once Microsoft SQL Native Client 2012 is installed, the installation process will automatically proceed to installing the CHA web service components.

P I G C H A M P

14

Choose where you want the CHA web service files installed on the computer. You may choose the default, browse to an existing location or type in a new folder name. If the folder name does not exist, the CHA setup will create it. Click Next.

Select the CHA web service components you want to install or upgrade. Both the DLL and Web Service are required for operation. Languages chosen on this screen determine which language will be available on the mobile app.

P I G C H A M P

15

Type in the location of the server\instance where the PigOnline database is located. The PigOnline database is created by the PigCHAMP application when licensed for CHA in the same server\instance location as the main PigCHAMP database.

You can also set the timeout value (in minutes) for the mobile app. Default is 30 minutes before mobile user is automatically logged off.

Click Next.

One more screen will allow you to review the settings you have entered and install the CHA web service. You can go back to change entries or cancel out of the setup at any time.

P I G C H A M P

16

CHA Configuration

RDS/IIS/URL configuration must be completed before proceeding.

Open IIS Manager

▪ Right click on Sites > Add Website

▪ Fill out the information corresponding to the web service. The Physical path must match where you installed the PigCHAMP CHA web service. The hostname is the domain URL you purchased (see Chapter 3).

Click OK.

P I G C H A M P

17

▪ If you purchased an SSL and want the connection from mobile app to server to be secure, you can also set up the bindings to include https.

▪ On the main IIS Manager window, highlight the site in the left column and click on Bindings in the right column

i. Click the Add button and add the https binding

• On the main IIS Manager Screen, highlight the site you just created, and click on MIME Types in the main window, in the IIS section

o Click on add in the right windowpane

o Add

▪ File name extension: .lng

▪ MIME Type: text/plain

▪ Click on OK.

▪ In main IIS Server window, click on Application Pools. You will see an application pool with the site name you just created.

o Right click on the site name and choose Advanced Settings.

o In the General section, set Enable 32-Bit Applications to True

P I G C H A M P

18

o Note that in the Process Model section, the Identity is set to ApplicationPoolIdentity. This is a secure way to restrict the users that can access the server via the web service, and is recommended.

o In the Process Model section, set the Idle Time-out to match your timeout value you set when installing CHA.

o Click OK when finished.

▪ If you chose to use Identity = ApplicationPoolIdentity in the previous step

o Open Windows Explorer and navigate to the location where the web service files were installed (e.g. C:\inetpub\wwwroot\PigchampWeb ).

o Right click on the folder name (e.g. PigCHAMPWeb ) and choose Properties > Security > Edit > Add

o In the “From this location” box, click the Locations button and choose the local computer name (app server).

o In the ‘Enter the object names to select’ box, enter:

▪ “IIS AppPool\PigCHAMPWeb”

• Do not include the quotation marks – these are just to show the string that must be used

• Use the correct app pool name for your installation and click on Check Names.

• Check Names should resolve to PigCHAMPWeb

• Click OK.

P I G C H A M P

19

o Make sure your new user has full rights to this folder:

▪ Click Apply and then OK.

▪ Go back to IIS Manager

o Highlight the site name > Click Restart on the right panel

o Highlight the application pool > Click Recycle on right panel

P I G C H A M P

20

5

Chapter

Testing and Troubleshooting Im,e to see if it all works.

Testing - Web Service Front End Open a web browser and type in the URL for your website (e.g. online.yourcompany.com) that you purchased and set up in IIS. If everything is working correctly, you should see a page that says: Welcome to PigCHAMP Webservices.

This shows that the front end of the web service appears to be set up correctly.

Troubleshooting - Web Service Front End If this fails

• Make sure that your firewall is allowing port 80 (for http) and/or port 443 (for https)

• Make sure the World Wide Web Publishing Service is started

• Recheck that all configuration/installation/setup in Chapters 3 and 4 is complete.

T

P I G C H A M P

21

Testing – Mobile App Install the PigCHAMP Mobile CHA application on your Android or iOS phone.

o Start the app. o Click on the vertical ellipsis menu in the top right corner

• Choose Configuration

o Type in the URL for your web service

▪ Click Save

▪ Note: Reset will set the value to ‘online.pigchamp.com’ o Enter account number, username, password and choose language from dropdown

list o Account number: PigCHAMP account number used to license

PigCHAMP o Username: Username in PigCHAMP that has Mobile User capability box

checked in User Management o Password: Password for Username in PigCHAMP

Troubleshooting – Mobile App

• All the previous setup must be completed.

• If it says “Server not responding” after saving the Configuration URL, check entry in Configuration – spelling, etc.

• If an error occurs that says: “Username does not exist”, make sure the account number and username are correct