Setup Checklist for Mobile App

The mobile app is an Android/iOS client for Desigo CC. This checklist summarizes the steps necessary to set up an existing Desigo CC project to work with the mobile app. For background information see the reference section. Mobile App Deployment Architectures.

If the IIS web server is installed on a separate computer from the Desigo CC server, refer also to Working with a Website and Web Application Management on a Remote IIS System.

Deployment Information

Required Extensions

The only extension required to support the mobile app is Web Services. This is a mandatory extension, now included by default in Desigo CC projects.

Optionally, the Connectivity > Push Notifications extension can be added to enhance the notification functionality of the mobile app. See Push Notifications Extension.

 

Local or Remote IIS

Web applications such as Web Services, Flex Client, and Advanced Reporting are hosted on an IIS web server, which can run on the same computer as the Desigo CC server (local IIS) or on a separate computer (remote IIS) dedicated to that purpose.
The latter solution allows for enhanced security and segregation.

  • For a local IIS setup you only require the Desigo CC server station, with IIS enabled on it.
  • For a remote IIS setup, in addition to the Desigo CC server station you must configure a separate Installed Client or FEP station, and enable IIS on that machine.

 

Website for the Mobile App

This section covers how to configure the parent website that supports the mobile app web service. The host certificate set for this website must be recognized by the mobile devices running the app.

About the Website Host Certificate for the Mobile App

The mobile app requires a secure (https://) connection to the website and web service application, hosted on the IIS web server. You can use:

  • A public CA host certificate (purchased from a commercial certification authority): this is publicly trusted and so does not require installing anything on the mobile device.
  • A private CA host certificate (created with the SMC): this will require installing the corresponding root certificate on the mobile device.

NOTE: Self-signed certificates cannot be used. Certificates created using the Simple Authority tool will not work.

The host certificate for the website must be configured on the computer that is running the IIS web server:

- In the case of a local IIS deployment, this will be the Desigo CC server computer.

- In the case of a remote IIS deployment, this will be the separate computer (Installed Client / FEP) that hosts the IIS web server.

 

Option 1 - Public (Commercial) CA Host Certificate

To use a public CA host certificate, purchased from a commercial certification authority such as Comodo (recommended):

  • Import the purchased certificate file into the Personal store of the computer running the IIS web server. The Subject Name/Certificate Issued To field must match the computer name of the IIS web server computer.
  • Because this type of certificate is publicly trusted, it will be automatically recognized as valid by the mobile app without having to install any certificates on the mobile device.

Select this public CA host certificate when you create the parent website for the mobile app web application.

 

Option 2 - Private (SMC-Created) Host Certificate

As an alternative to a purchased CA host certificate, you can used a host certificate created in SMC.

1 – On the IIS Web Server Computer, Create a Root Certificate, Import it into the TRCA Store, and Set it as Default

  1. On the IIS web server computer, start SMC.
  1. In the SMC tree, select the Certificate node.
  • The Certificates tab displays. This shows the currently configured default certificates for this Desigo CC installation.
  1. In the Certificates toolbar, click Create Certificate and select Create Root Certificate (.pfx).
  • GMS Root Certificate automatically displays in the Subject Name field.
  1. Change the subject name to a descriptive name, for example RootCertificate_MobileApp.
  1. Enter the root certificate (.pfx) and (.cer) file names, password, and path on disk into the remaining fields.
  1. Click Save .
  • The root certificate files are created and saved at the specified path.
    NOTE: Keep a copy of these root certificate files and write down the password for use in the next steps.
  1. In the Certificates toolbar, click Import , select the Root certificate certificate type.
  1. Browse to the (.cer) root certificate file created above, and select Set as default.
  1. Click Save .
  • The root certificate is imported into the TRCA store of the IIS web server computer, and set as the default. You will later need to import this same root certificate into the mobile device as well.

 

2 – On the IIS Web Server Computer, Create a Host Certificate for the IIS Web Server, Import it into the Personal Store, and Set it as Default

  1. In the Certificates toolbar, click Create Certificate and select Create Host Certificate (.pfx).
  1. In the Root certificate field, browse to the (.pfx) root certificate file created above and enter its password.
  • The full computer name of the IIS web server is automatically entered in the Subject Name field.
  1. Enter the (.pfx) and (.cer) host certificate file names, password, and path on disk.
  1. Click Save .
  • The server host certificate files are created and saved at the specified path.
  1. In the Certificates toolbar, click Import select the Host certificate certificate type.
  1. Browse for the (.pfx) host certificate file created above and enter its password.
  1. Select Set as default and Key is exportable.
  1. Click Save .
  • The host certificate is imported into the Personal store of the IIS web server computer.

Select this host certificate when you create the parent website for the mobile app web application.

 

3 – Install the Same Root Certificate on the Mobile Devices

The root certificate created in Step 1 must be installed on all the mobile devices where you plan to use the mobile app. For instructions see 2 – Install Certificate on the Mobile Device. If you do not do this now, you must do it when you install the app on the mobile device.

 

Configure the Website for the Mobile App

In this step you will set up a parent website for the web service that supports the mobile app. Websites are hosted on the computer where the IIS web server is running.

  • For a local IIS deployment, do these steps on the Desigo CC server station.
  • For a remote IIS deployment, do these steps on the separate Client/FEP station that hosts the IIS server.
  1. In SMC select the Websites node, and on the toolbar click Create website .
    (or, to modify an existing website, select it and click Edit)
  1. In the Host name field, enter the computer running the IIS web server. This field is prefilled to the machine on which you are running SMC.
  1. Click Browse... to select the website User, and enter that user's Password.
    If that user is not already a member of the IIS Users group, you will later be prompted to add it.
    NOTE: In case of a remote IIS deployment, the website user must exist on the Desigo CC server as well as on the Desigo CC Client/FEP station that hosts the IIS server.
  1. Next to the Certificate issued to field, click Browse and select whichever host certificate (private CA or public CA) you prepared previously in Prepare Certificates for the Mobile App.
  • The selected certificate must be Issued to the computer specified in Host name (computer hosting the website).
  • If a private CA certificate is used here, the corresponding root certificate must be installed on the mobile device as well
  1. When finished click Save , and click OK to start creating the website.
  • The website is generated and its URLs display in the expander. Note that before these URLs will work you must also Start the website if it was stopped.

 

Start and Test the Website
  1. In the SMC tree, select Websites > [website].
  1. In the Management tab toolbar, click Start .
  • If the website start fails, check whether there are any other running websites that use the same ports. If so, either Stop the other websites or change the conflicting port numbers.
  1. Copy the website URLs from the Details expander and test them in a browser. Check that the https:// website is accessible from the same computer running the IIS web server, and also from other computers:
  • The website may be accessible over the Internet or only within an intranet, depending on the network configuration of the host computer.
  • If the website is not accessible from other computers, see the section Configure Firewall Ports below.
  • If the website uses an SMC-generated host certificate, you may get a certificate error when browsing the https:// URL from computers that do not have the corresponding root certificate installed. See Prepare Certificates for the Mobile App.

Configure Firewall Ports to Make the Website Accessible

Configure the network and computer firewalls so that, on the IIS web server computer, the HTTPs port that you selected for the website is enabled for inbound and outbound communication. Note that:

  • If the website is only accessible inside an intranet, the mobile app will likewise only be able to connect from within that same intranet.
  • If you want the mobile app to connect over the Internet, the website on the IIS web server must be accessible over the internet.

 

Web Services Communication

The Desigo CC project needs to have Web Services Communications configured in SMC. Note that the certificates here are only required for a remote IIS deployment. (By contrast, the website certificate configured in the preceding section is always required).

Certificates for Web Services

Web Services certificates are required if you have a deployment configuration with a remote IIS web server, in order to secure communication between the IIS web server computer and the Desigo CC server computer.
Do these steps to configure the Host certificate that you will select for Secured communication in the Web Services Communication expander of SMC.

NOTE: If you have a local IIS web server, you can skip these steps.

1 – On the Desigo CC Server Computer, Create a Root Certificate, Import it into the TRCA Store and Set it as Default

  1. On the Desigo CC server computer, start SMC.
  1. In the SMC tree, select the Certificate node.
  • The Certificates tab displays. This shows the currently configured default certificates (if any) for this Desigo CC installation.
  1. In the Certificates toolbar, click Create Certificate and select Create Root Certificate (.pfx).
  • GMS Root Certificate automatically displays in the Subject Name field.
  1. Change the subject name to a descriptive name, for example RootCertificate_WebServices.
  1. Complete the remaining fields to specify the root certificate (.pfx) and (.cer) file names, password, and path on disk.
  1. Click Save .
  • The root certificate files are created and saved at the specified path.
    NOTE: Keep a copy of these root certificate files and write down the password for use in the next steps.
  1. In the Certificates toolbar, click Import , select the Root certificate certificate type, browse to the (.cer) root certificate file created above, and select Set as default.
  1. Click Save .
  • The root certificate is imported into the TRCA store of the Desigo CC server computer, and set as the default.
    You will later need to import this root certificate into the TRCA store of the remote IIS web server computer. See Step 3 below.

 

2 – On the Desigo CC Server Computer, Create a Host Certificate for the Server, Import it into the Personal Store, and set it as Default

  1. In the Certificates toolbar, click Create Certificate and select Create Host Certificate (.pfx).
  1. In the Root certificate field, browse to the (.pfx) root certificate file created above and enter its password.
  • The full computer name of the server is automatically entered in the subject name field.
  1. Specify the (.pfx) and (.cer) host certificate file names, password, and path on disk.
  1. Click Save .
  • The server host certificate files are created and saved at the specified path.
  1. In the Certificates toolbar, click Import select the Host certificate certificate type.
  1. Browse for the (.pfx) host certificate file created above and enter its password.
  1. Select Set as default and Key is exportable.
  1. Click Save .
  • The server host certificate is imported into the Personal store of the Desigo CC server computer.

 

3 – On the Remote IIS Web Server Computer, Import the Previously-Created Root Certificate into the TRCA Store, and Set it as Default

  1. On the IIS web server computer, start SMC.
  1. In the SMC tree, select the Certificate node.
  1. In the Certificates toolbar, click Import .
  1. Select the Root certificate certificate type.
  1. Browse to the (.cer) root certificate file created in Step 1 above, and select Set as default.
  1. Click Save .
  • The root certificate is imported into the TRCA store of the IIS web server computer, and set as default.

NOTE: This must be the same root certificate that you imported into the TRCA store of the Desigo CC server computer.
Importing this certificate is necessary for the remote IIS web server to recognize the private CA host certificate of the Desigo CC server, which secures the communication between it and the IIS web server.

 

Web Services Communication in SMC Project

For all deployments (local IIS or remote IIS), perform this step on the Desigo CC server station.

  1. In SMC, Stop and Edit the project.
  1. Click Next to reach the page with the Web Services Communication expander.
    NOTE: Do not confuse this with the Communication Security expander on the first page. The Web Server Communication section there is not required for Web Services and can be left Disabled.
  1. In the expander, locate the communication instance you want to use (each one is on a separate row), or click Add to create a new one.
  1. Set the Communication field of the instance as follows:
  • If the IIS web server is on the same computer as the Desigo CC server, set Local. (You do not need a certificate for this.)
  1. Enter a distinct instance name and adjust the port if required.
  1. Click Next to reach the final page, and Save the project.

 

Web Service Application for Mobile App

Now, the final step is to set up a Web Services application to which the mobile app will connect, and link it to the previously configured project with Web Services Communications instance.

Create Web Services Application

In this step you will set up the web services application that the mobile app connects to, and link it to a project with Web Services capability.

  • For a local IIS deployment, do these steps on the Desigo CC server station.
  • For a remote IIS deployment, do these steps on the separate Client/FEP station that hosts the IIS server.
  1. In SMC, select Websites > [website], and in the toolbar select Create Web Services Application. 
    (or, to modify an existing web service app, select it and click Edit.)
  1. If you are working on the Desigo CC server station (local IIS deployment):
  • The Server name is a read-only field, showing the name of this computer.
  • Select the Project name, and underneath it shows the configuration done previously in the Web Services Communication expander of the project.
  • Select the Instance to use, if more than one was configured in the project.
  1. If you are working on the Client/FEP station (remote IIS deployment):
  • Next to the Server name field, enter the host name of the Desigo CC server computer, or use the Browse... button.
  • Click Projects... and, from the dialog that opens, select the project for which you configured Web Services Communication (see above), and click OK.
  • The Project information: Web Services Communication expander is populated with the information pertaining to the selected project.
  • Select the communication Instance to use, if more than one was configured in the project.
  1. In the Web Application Details expander:
  • Assign a Name to the web service.
  • The user/password fields are prepopulated with those of the website user.
  1. Click Save .

 

Test the Web Services for the Mobile App

Do this procedure to check that the web application was correctly set up and is accessible.

  • In the SMC tree, select Websites > [parent website] > [web services app].

Check that the Web Services URL is Accessible

  1. In the Web Application Details expander, check that the Status is Accessible. If the Status is Website stopped, go back and start the parent website.
  1. Check the URL the mobile app will connect to: Use a browser to check that the topmost URL (the one beginning with https://) in the Web Application Details expander is accessible from other computers. This is the URL that you will use to log in from the mobile app.
  • The URL may be accessible over the Internet or only within an intranet, depending on the network configuration of the IIS web server computer.
  • If the parent website uses an SMC-generated host certificate, you may get a certificate error when browsing the https:// URL from computers that do not have the corresponding root certificate installed.
  • Otherwise, you should be able to establish a secure connection (https:// with no browser warnings) to a page that displays: URL not supposed to be displayed in a browser but entry point for API access.
  • Configure the firewall of the computer running the IIS web server so that the HTTPs port that you selected for the parent website is enabled for inbound and outbound communication.

(Optional) Test the Web Services Interface APIs

  • (Optional) Test the APIs provided by the Web Service Interface:
  • Use a browser such as Chrome, Firefox, or Internet Explorer (disable compatibility mode) to navigate to the Help URL provided in the Web Services Details expander.
  • The Web Service Interface test page displays. Here you test the different APIs provided by WSI. (Note that some APIs require authenticating with username and password). Username : defaultadmin and its password (for example, defaultadmin:a).
  • To test any API, expand it and access it using the Try it out button.

 

Try Connecting from a Mobile Device

As a final step, check if you can use the mobile app.

  1. Install the mobile app on a mobile device.
  1. If the parent website uses an SMC-generated host certificate, make sure to install the corresponding root certificate on the device as well.
  1. Start the app and sign in, and check that the app is able to connect to Desigo CC.

NOTE: For detailed instructions, see Installing and Connecting the Mobile App.