Integrating the Mobile App

Scenario: You want to configure the Desigo CC management platform to work with the mobile app.

 

Reference: For background information see the reference section. 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.

 

Workflow diagram:

 

Prerequisites:

  • You installed the Desigo CC software and started up a project, in a configuration that includes an IIS web server. For background information see Mobile App Deployment Architectures.

 

Steps:

1 – Install or Upgrade the Web Services Extension

Perform this procedure if the Web Services extension is not yet installed on the Desigo CC server, or if you want to upgrade it to a newer version.

  • You are logged into Windows with admin rights.
  1. In SMC, stop any started projects.
  1. Exit both Desigo CC and SMC.
  1. From where you have the full Desigo CC installation package stored, navigate to the InstallFiles directory, right-click the installer setup file, and select Run as administrator.
  • The Install Wizard displays.
  1. Click Next.
  1. An Upgrade Selection screen displays only when the installation package contains updated versions of already-installed extension modules:
    a. If the Web Services extension is listed here, leave it selected to update it. Also leave Connectivity selected.
    b. Deselect any other extensions you do not want to update.
    c. Click Next.
  • The Setup Type Selection screen displays.
  1. Click Modify alongside Feature Selection.
  1. In the Feature Selection screen:
    a. Expand the Connectivity extension suite.
    b. Select the Web Services extension check box.
    c. Click OK.
  1. Click Next and follow the on-screen prompts to finish installing or updating the Web Services extension.
  • When finished, the Installation Complete dialog box displays.
  1. Click Close.

 

2 – Add the Web Services Extension to a Project

Perform this procedure to check whether the Web Services extension module is present in a project, and to add it if needed.

NOTE: Once you have added an extension to a project you cannot remove it. Only add the necessary extensions to a project.

  • You are logged into Windows with admin rights.
  • The Web Services extension is installed.
  1. Exit Desigo CC.
  1. Launch the System Management Console (SMC).
  1. In the SMC tree, select Projects > [project].
  1. In the Project Settings tab, open the Extension Information expander and look for Web Services in the list of the project’s extension modules.
  • If Web Services is included in the list and its status is Updated, then the project already includes the necessary extension, skip to the end of this procedure. Otherwise continue with the steps below.
  1. If the Project status in the Server Project Information expander is Started, stop the project as follows:
    a. Click Stop .
    b. Click OK.
  • The status bar at the bottom of the screen displays Project is Stopping. Once finished, the Project status changes to stopped.
  1. If Web Services is listed in the Extension Information expander but its status is Outdated, click Upgrade .
  • The extension changes are applied to the project. This may take several minutes. Check the progress bar at the bottom of the screen. Once finished, Upgrade successful displays.
  1. If Web Services is not listed in the Extension Information expander, add it to the project as follows:
    a. Click (+) Add to project.
    b. In the Select Project Extensions dialog box, expand Connectivity.
    c. Select the Web Services check box.
    d. Click OK.
  • The Web Services Communication expander displays. For now leave the default settings. These will be configured if needed in the next procedure.
    e. Click Save Project .
  • The extension is added. Once finished, Extensions added successfully displays.

 

3 – Configure Project Settings for Web Services

Perform this procedure to set how communication is secured between the Desigo CC server and the IIS web server.

  • The Web Services extension was added to the project.
  • If the IIS web server runs on a separate computer that you want to isolate from the Desigo CC server computer, you prepared the necessary certificate. See Preparing Certificates for Web Services.
  1. Exit Desigo CC and launch the System Management Console (SMC).
  1. In the SMC tree, select Projects > [project].
  1. In the Project Settings toolbar, click Stop to stop the project and click OK.
  1. Click Edit .
    NOTE: For mobile app support, you do not need to configure the Communication Security expander of the initial screen. The Server Communication field is for installed Clients/FEPs, while the Web Server Communication field is for Web Clients and Windows App Clients.
  1. Click Next .
  • The Web Services Communication expander displays.
  1. Set the Communication field as follows:
  • For a local IIS web server deployment (the Desigo CC server and the IIS web server are both running on the same computer) you can select Local.
  • For a remote IIS web server deployment select Secured to isolate the IIS web server from the Desigo CC server computer. In the Host certificate field select the [server host certificate] that you created previously for the Desigo CC server computer.
  1. Click Save .
  1. Click Activate Project and Start to start up the project again. You should now be able to start the Desigo CC client application.

 

4 – Configure the Website for the Mobile App

In this step you will set up a parent website for the web application that supports the mobile app. The host computer you select for this website determines the URL that the mobile app connects to.

  1. Start SMC and do one of the following:
  • To create a new website: In the SMC tree, select the Websites node and click Create website .
  • To configure an existing website: In the SMC tree, select Websites > [website]. If it is running, click Stop website . Then click Edit .
  • In the Management tab, the website Details expander displays in Edit mode. Here you can configure the website details, including setting the security certificate.
  1. Set the User field: It is recommended to create a new user. If selected user is not a member of the IISUser group then when you save the website the SMC will prompt you to confirm adding the selected user to the IISUser group.
    NOTE: Do not use GmsDefaultUser for Website creation because whenever new GMS installation is done GmsDefaultUser, is removed from the system.
  1. Into the Host name field, enter the full name of the computer that will host the website. This must be the computer where IIS web server is running, and will determine the website’s URL. The field is prefilled to the name of the computer from which you are using SMC.
  1. Next to the Certificate issued to field, click Browse and select whichever host certificate (private CA or public CA) you prepared previously in Preparing Certificates for the Mobile App.
    NOTE: The selected certificate must be Issued to the computer specified in Host name (computer hosting the website).
    NOTE: If a private CA certificate is used here, the corresponding root certificate must be installed on the mobile device as well.
  1. Click Save .
  • The website is generated and its URLs display in the expander. Note that before these URLs will work you must also Start the website.

 

5 – 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 Preparing 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.

 

6 – Configure the Web Application for the Mobile App

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

  • You set up a parent website for the web application.
  • Start SMC.
  1. Do one of the following:
  • To create a new web application: In the SMC tree, select Websites > [parent website]. Then click Create and select Web Services.
  • To configure an existing web application: In the SMC tree, select Websites > [parent website] > [web application] and click Edit .
  • Two expanders, Web Application Details and Web Services Details, display in Edit mode.
  1. Configure the fields of these expanders as follows:
  • Name: This is the web application name that displays in the SMC tree.
  • Project name: Select the project to link to the web application. This must be a project configured with the Web Services extension. Otherwise you will not be able to save.
  • Protocol type: This field is read-only, and reflects what was previously configured for the Web Services extension of the linked project. See Configure Project Settings for Web Services, above. The protocol type refers to communication between the Web Services Interface (on the Desigo CC server) and the IIS web server. It can be left Unsecured if both are on the same machine (local IIS deployment), or in a remote IIS deployment that is confined to an intranet. Otherwise, it must be secured with a certificate.
  1. Click Save .

 

7 – Test the Web Application 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 application].

Check that the Web Application 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.

 

8 – 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.