Set up Zylinc Mobile

This information is primarily for administrators and/or people who manage Zylinc solutions

If you set up support for Zylinc Mobile, users in your organization can begin to use the Zylinc smartphone app

For Android devices: Get Zylinc Mobile on Google Play

For iOS devices: Get Zylinc Mobile from App Store

Zylinc Mobile gives your users a real-time overview of colleagues’ calendars, contact details, and availability directly on their smartphones. If users have the required rights, they can also work with queues as agents.

That's because the app can run in two different modes: one without agent and queue features, and one with agent and queue features. The mode depends on your Zylinc licenses, and what administrators have set up in the Zylinc Administration Portal.

Under Set up Zylinc Mobile in the following, you find the complete list of tasks involved in setting up Zylinc Mobile.

The tasks can be grouped into prerequisite tasks and actual setup tasks.

Prerequisite tasks may or may not involve the Zylinc administrator. Depending on the structure of your organization, some of the prerequisite tasks may also be carried out by a database administrator (dba), an Active Directory administrator, a user administrator, a firewall administrator, or similar. Those tasks are:

  • Task 1 about general environment

  • Task 2 about licenses

  • Task 3 about certificate

  • Task 4 about users

  • Task 5 about groups to control user access

  • Task 6 about users' mobile numbers

  • Task 7 about password policy

  • Task 8 about firewall/DMZ

  • Task 9 about firewall port

  • Task 10 about registration of domains

Actual setup tasks will involve the Zylinc administrator. Those tasks are:

  • Task 11 about client access
  • Task 12 about client, mobile & web configuration
  • Task 13 about identity server
  • Task 14 about client API service
  • Task 15 about gateway service

You can set up the Zylinc solution in your organization to support Zylinc Mobile.

The tasks in the following will only work if you have set up your Zylinc environment according to best practices. For example, your Zylinc solution will need to:

  • Use a single Windows Application Server to host all the Windows-based Zylinc services and two Tomcat instances for the Tomcat-based Zylinc services.
  • Use a single Zylinc Media Server that also hosts the Zylinc Administration Portal.
  • Use a default instance of SQL Server, that you can co-locate on your Zylinc Windows Application Server, on a dedicated SQL Server, or on a cluster.
  • Use the default network port numbers.

For more information, see Install a Zylinc solution from scratch.

  1. In the Zylinc Administration Portal menu, select INSTALL > License

  2. In your browser, search for the word ZyMobile. If you can see a line in License Information with the name ZyMobile, your organization has available licenses for using Zylinc Mobile in the basic mode without agent and queue features. In the Count column, you can view how many.

  3. Then, in your browser, search for the word MobileAgent. If you can see a line in License Information with the name MobileAgent, your organization has available licenses for Zylinc Mobile with agent and queue features. In the Count column, you can view how many.

    Because the ability to work with agents and queues is an add-on feature, your organization can have more licenses available for working without agents and queues (ZyMobile) than for working with agents and queues (MobileAgent). In that case, the number of users who can work with agents and queues is the difference between the two numbers.

If you can’t see any lines in License Information with the names ZyMobile or MobileAgent, you must get licenses before you can continue.

Zylinc Mobile uses HTTPS and SSL to connect to your Zylinc solution through the Zylinc gateway service, which you're going to set up in the following.

Your Zylinc Windows Application Server (or a proxy service in your DMZ, on behalf of that server) is going to listen for HTTPS requests from Zylinc Mobile users on the internet.

When a server needs to do that, you must know the fully qualified DNS name on the internet for that server, so that you can get a X.509 certificate with the right attributes and extensions to be used for HTTPS and SSL, from a trusted certificate authority (CA), as described in the following.

Example of an application server with different DNS names on the LAN and on the Internet

The name of a Zylinc Windows Application Server on a LAN is winappserver.domain.local

The name of the same server as seen from the internet is internethost.companydomain.com

In the following we'll refer to the Zylinc Windows Application Server with two different names:

When we refer to the server's name on your LAN, we'll use the term WinAppServer

When we refer to the server's name on the internet, through an open port in your firewall, we'll use the term InternetHost

Before you can use HTTPS, you must get a certificate for the fully qualified DNS name on the internet for your Zylinc Windows Application Server (InternetHost), from a trusted certificate authority (CA).

You can get a certificate from, for example, verisign.com, thawte.com, trustcenter.de, or from a trusted certificate authority within your organization.

You can also get a certificate for free, for example from Let's Encrypt.

When you ask a certificate authority to issue a certificate for a server that's a part of your Zylinc solution, make sure to ask for a certificate that complies with all the following requirements:

  • The certificate must be of a type that makes it possible for a web server to provide connections from the internet via HTTPS protocol.

  • The certificate file must be in PFX format.

  • You'll need the password for the PFX file.

  • The PFX file must contain the private key for your certificate.

  • The PFX file must contain all intermediate certificates that may be required for the certificate to be trusted by, for example, web browsers, client computers, or internal or external servers.

    If the certificate chain is invalid or broken, your certificate will not work. This is because some web servers, for example Kestrel on Windows Nano, are shipped without a list of trusted CAs. That's why you need the PFX file to contain all levels of the required chain, including the root level.

  1. In the Administration Portal, select USERS > ZyDesk Users

  2. Check that you can see the users who are going to use Zylinc Mobile in the list.

    If you can’t see the users in the list, ask an Active Directory administrator to create the users. If your organization doesn’t import Zylinc users from Active Directory, ask a Zylinc user administrator to add the users to the CSV file that the Zylinc solution imports the users from.

Ask an Active Directory administrator to create the groups described in the following.

If your organization doesn’t import Zylinc groups from Active Directory, ask a Zylinc user administrator to add the groups to the CSV file that the Zylinc solution imports the groups from.

  1. Create a new group ZylincMobileOperatorUsers with the description: Members of this group can use Mobile Operator (that's Zylinc Mobile without agents and queues).

  2. Add the users who are going to use Zylinc Mobile without the agent and queue features to ZylincMobileOperatorUsers.

  3. Create a new group ZylincMobileAgentUsers with the description: Members of this group can use Mobile Agent (that's Zylinc Mobile with agents and queues).

    If you don’t plan to use Zylinc Mobile with agents queues, you can leave the group empty, but you’ll need the group in a later step.

  4. If you're going to use Zylinc Mobile with the agent and queue features, add the respective users to ZylincMobileAgentUsers.

  5. Reinitialize Directory Settings:

    1. In the Administration Portal menu, select NETWORK > Directory Settings

    2. Click Reinitialize

  6. Log out of the Administration Portal. This will clear its user and group cache.

If you're going to use the agent and queue features, the app may prompt you to enter your mobile phone number the first time that you use one of those features. This is because some mobile operating systems don’t allow apps to read the phone number from the phone's SIM card.

As an administrator, you can prevent your users from this annoyance, if you make sure that the Zylinc solution knows the mobile phone numbers for all users who are going to use Zylinc Mobile with the agent and queue features:

  1. In ZyDesk, search for the users who are going to use the agent and queue features in Zylinc Mobile.
  2. For each of these users, check that their mobile phone number is visible in the Mobile column.
  3. If you can’t see the mobile phone numbers of some of the users, ask the user administrator in your organization to add those users' mobile phone numbers to the user directory.

If a user decides to use a SIM card with another number, the user can manually enter that phone number in their Zylinc Mobile.

For compatibility reasons, there's a legacy Allow ZyDesk Password feature in the Administration Portal.

That feature allows all users to log in with the standard password: password. You probably don't want to allow this weak password when you set up mobile access.

Because of that, do the following to check that the feature is disabled:

  1. In the Administration Portal, select SYSTEM > Client Configuration
  2. In the ZyDesk- Installation & Access section, make sure that ZyDesk Login: Allow ZyDeskPassword is not selected.

If you were using the Allow ZyDesk Password option, now is a good time to stop using it and set up an alternative way to authorize users, for example, Active Directory integration or Import users, groups, and keywords from CSV file.

To use Zylinc Mobile, your organization must open a port in the firewall that makes it possible to listen to traffic from the internet.

Check if your organization’s IT policies require that servers with open ports to the internet must be placed in DMZ.

If your organization has already used the old Mobile Agent/Operator app, you can do the following. It'll stop the Client Manager from listening on the existing port, so that you can reuse the port for Zylinc gateway service in the following.

Your existing old Zylinc Mobile Agent/Operator will stop working, and when you restart Client Manager, the restart will affect all active users of the Zylinc solution.

Because of that, do the following in the same service window as when you set op the new Zylinc Mobile.

  1. In the Administration Portal menu, select SYSTEM > Interface Configuration
  2. In Zylinc Client Manager URL, WAN port, make a note of the existing WAN port. You are going to set up Zylinc gateway service on that port in a later step.
  3. Move the existing WAN port to an unused port. For example, you can subtract 1000 from the existing value.
  4. In the Deployment Manager menu, select Deployment > Tomcat Services
  5. Restart ClientManager

To open a port in the firewall, so that users in your organization can use Zylinc Mobile, do the following:

Ask your organization's firewall administrator to open a port from the internet to the Zylinc gateway service on the Zylinc Windows Application Server, or to a DMZ server.

You can view the port number in this Excel sheet. A typical value for Zylinc gateway service is 35063.

If you’re going to use DMZ, also ask the administrator to open the Zylinc Proxy internal (LAN) port from the LAN to the DMZ, but not from the internet to the DMZ.

You can view the port number in this Excel sheet. A typical value for Zylinc Proxy internal (LAN) port is 35031.

If you don’t need to use DMZ, you can directly forward the internet port to the Zylinc Windows Application Server. That way, you don’t need Zylinc Proxy.

If you need to use DMZ, you can set up Zylinc Proxy on a DMZ server, and set up the accompanying Zylinc Proxy Client on a LAN server.

With this method you don’t need to open a port from the DMZ to the LAN, or from the internet to the LAN, because the connection is initiated in the outgoing direction from LAN to DMZ. The only open port from the internet goes to the DMZ.

Zylinc Proxy and Zylinc Proxy Client work like this:

  1. Zylinc Proxy Client on the LAN server initiates an outgoing connection to Zylinc Proxy’s internal (LAN) port on the DMZ server.
  2. Zylinc Proxy Client on the LAN then uses the established connection and a protocol to instruct Zylinc Proxy on the DMZ server to begin to listen to the specified Wan Port (that’s the port that has been opened in the firewall from internet to DMZ).
  3. Zylinc Proxy on the DMZ server then begins to relay network traffic back to Zylinc Proxy Client on the LAN via the established connection.
  4. Zylinc Proxy Client on the LAN server connects to the specified Service Address and Port on the LAN, and then begins to relay network traffic to that address and port.
  5. Zylinc Proxy and Zylinc Proxy Client use a protocol to detect if the established connection becomes disconnected. If that’s the case, the process will repeat itself from step 1 to reestablish the connection.

On the DMZ server, do the following:

  1. Open the unzipped Zylinc release folder:

    C:\Zylinc install\Release_6.5u4.12\Release_6.5u4.12\

  2. Locate the DeploymentManager.exe file, and double-click it to start the program. Run DeploymentManager.exe directly from the unzipped folder.

    You'll need Deployment Manager more than once, so pin it to the taskbar.

  3. In the Deployment Manager menu, select Deployment > Installation.

  4. Maximize the Window to view all the available features.

  5. In the Installers list, select Java.

  6. Click Install Applications. When Java installation is complete, status changes from uninstalled to installed, and Java changes color to green in the Installers list.

  7. In the Installers list, select Tomcat.

  8. Click Install Applications.

Set up a new Tomcat instance with the following parameters:

Application server name (example): DMZserver

New instance name (example): ZyTomcatDMZ-8080

Use the admin user password for: Windows Tomcat DMZ 8080 user admin

Java and Tomcat versions: Most recent versions available in Deployment Manager

Initial memory: 512MB

Max memory: 2048MB

Port numbers (HTTP / AJP / Shutdown): 8080 / 8009 / 8005

Set service startup type to: Automatic

  1. In the Deployment Manager menu, select Application Administration > Apache Tomcat Administration

  2. In Instances, click New instance

  3. In Apache, select the most recent Tomcat version available in the list

  4. In Java, select the most recent Java version available in the list

  5. In Initial Memory (MB), enter 512

  6. In Max Memory (MB), enter 2048

  7. In Name, enter a name to use for the new instance in Deployment Manager, for example: ZyTomcatDMZ-8080

  8. In User, enter admin

  9. In Password, enter a password to use for Windows Tomcat DMZ 8080 user admin

    You’ll need this username and password when you're going to use a web browser to log in to Manager App for the new instance. This is useful, for example, when you need to test that HTTP works.

  10. Click Save instance

  11. A new instance with the name ZyTomcatDMZ-8080 should be visible in the Instances list

  12. Click Save instance

  13. In the Deployment Manager menu, select Deployment > Windows Services

  14. Click Refresh Services

    A new service with a name that ends with ZyTomcatDMZ-8080 should be visible in the Deployed Services list.

  15. Start the new service

  16. Select the new service, and in Change Startup Type, select Automatic, and click Change Startup Type.

  1. Go to the following address in a web browser: http://<DMZserver>:8080/

    Example: The complete URL could be http://DMZserver:8080/

  2. You should see a Tomcat welcome page that says If you're seeing this, you've successfully installed Tomcat. Congratulations!

  3. Click Manager App

  4. In User name, enter admin

  5. In Password, enter the password for Windows Tomcat DMZ 8080 user admin

  6. You should see a list of Applications, for example /docs and /examples

Now you know that HTTP works.

On the DMZ server, do the following:

  1. In the Deployment Manager menu, select Deployment > Tomcat Services
  2. In Instance, select ZyTomcatDMZ-8080
  3. In Available Tomcat applications, select Zylinc Proxy
  4. Click Deploy Services

On the DMZ server, do the following:

  1. In a browser open this URL: http://localhost:8080/
  2. Click Manager App, and log in as admin with the password for Windows Tomcat DMZ 8080
  3. Click ZylincProxy
  4. Click Configure
  5. In Internal port, enter the port number for the Zylinc Proxy internal (LAN) port that you opened from LAN to DMZ (typical value: 35031)
  6. Click Save

Do the following to restart Zylinc Proxy:

  1. In the Deployment Manager menu, select Deployment > Tomcat Services
  2. In Instance, select ZyTomcatDMZ-8080
  3. In Available Tomcat applications, select Zylinc Proxy
  4. Click Stop Services
  5. In Available Tomcat applications, select Zylinc Proxy
  6. Click Start Services
  1. In the Administration Portal menu, select INSTALL > Portal Configuration
  2. Make sure that Zylinc Proxy is selected.
  3. In the Administration Portal menu, select NETWORK > Zylinc Proxy
  4. In Host address, enter the hostname or IP address of the DMZ server
  5. In Port, enter the port number for the Zylinc Proxy internal (LAN) port that you opened from LAN to DMZ (typical value: 35031)
  6. Click Save
  7. Click Add Client Proxy Config
  8. In Client Proxy Context Name, enter ZXC_MobileApp1
  9. In Service Address, enter the IP address or hostname of the Zylinc Windows Application Server, for example: winappserver
  10. In Port and Wan Port, enter the port number that the service on the LAN listens on. This port numbers should be identical to the one that you've opened in the firewall.
  11. Click Save.

On the Zylinc Windows Application Server, do the following:

  1. In the Deployment Manager menu, select Deployment > Tomcat Services
  2. In Instance, select ZyTomcat1-8080-8443
  3. In Available Tomcat applications, select Zylinc Proxy Client
  4. In Context Path, change the value to /ZXC_MobileApp1
  5. Click Deploy Services

On the Zylinc Windows Application Server:

  1. In a text editor, open C:\Program Files\Zylinc\ApacheInstances\<instance name>\logs\ZXC_MobileApp1.log
  2. The log file should have lines that contain the phrases TRACE - ping and TRACE - pong

What the phrases TRACE - ping and TRACE - pong mean:

  • Zylinc Proxy Client in the LAN successfully connected to Zylinc Proxy in the DMZ on the Zylinc Proxy internal (LAN) port.
  • Zylinc Proxy Client in the LAN successfully loaded the configuration that you previously set up in the Administration Portal.
  • The configuration was sent to Zylinc Proxy in the DMZ. The system successfully listened to the port and relayed network traffic back to the LAN.
  • Together, that confirms that the proxy configuration is working as expected.
  1. Go back and double-check that you correctly carried out the previous steps that relate to Zylinc Proxy. Then restart the Tomcat service on DMZ server, and restart the Tomcat service on Zylinc Windows Application Server.
  2. In the log file, search for lines that contain the words error or exception. Often, such lines also contain additional information about the possible causes of problems, and what to do to solve them.
  3. Go to the DMZ server and use a text editor to open C:\Program Files\Zylinc\ApacheInstances\ZyTomcatDMZ-8080\logs\ZylincProxy.log, and repeat the previous test procedure.

Contact your Zylinc support service (see Get technical support), copy/paste the following into your support request, and fill in the missing information:

Please register the following e-mail domains with the Zylinc autoconf service, so that users from those domains can log in to Zylinc Mobile via our server on the internet that can be reached on the following fully qualified DNS name and port number. We are using Zylinc gateway service and we don't need legacy Client Manager activation.

List of e-mail domains: __________________

Fully qualified DNS name of our server on the internet: __________________

Port number of our server on the internet: __________________

If your organization has already used the old Mobile Agent/Operator app, you may be able to reuse the existing registration with Zylinc autoconf:

  • If your existing autoconf registration uses a fully qualified DNS name, and you are in control of the underlying domain so that you can request a certificate from a trusted certificate authority, you can generally reuse the registration.
  • If your existing autoconf registration uses an IP address, you can't reuse the registration (unless you are able to get a certificate for that specific IP address from a trusted certificate authority.)

If you need to find out if your existing registration uses fully qualified DNS name, you can contact your Zylinc support service (see Get technical support), copy/paste the following into your support request, and fill in the missing information:

We're going to use Zylinc Mobile, and we've used the old Zylinc Mobile Agent/Operator before. Please tell me if my existing Zylinc autoconf registration(s) for Mobile Agent/Operator uses a fully qualified DNS name, and can be reused when we begin to use Zylinc gateway service for Zylinc Mobile instead of the Client Manager WAN port.

List of e-mail domains: __________________

  1. In the Administration Portal menu, select USERS > Client Access

  2. In Available, select the group ZylincMobileOperatorUsers. Then click next to the Mobile Operator field to add ZylincMobileOperatorUsers (that's users of Zylinc Mobile without the agent and queue features) to the list.

  3. In Available, select the group ZylincMobileAgentUsers. Then click next to the Mobile Operator field to add ZylincMobileAgentUsers (that's users of Zylinc Mobile with the agent and queue features) to the list.

    Yes, that's right: Because the agent and queue functionality is an add-on, you’ll need to set up client access for Mobile Operator to include both the group ZylincMobileOperatorUsers (without agent/queue features) and the group ZylincMobileAgentUsers (with agent queue features).

  4. In Mobile Operator, security type, select Include Groups

  5. Click Save

Set up client access for Mobile Agent (that's Zylinc Mobile with agent and queue features ) to include only the group ZylincMobileAgentUsers:

  1. In the Administration Portal menu, select USERS > Client Access
  2. In Available, select the group ZylincMobileAgentUsers. Then click next to the Mobile Agent field to add ZylincMobileAgentUsers to the list
  3. In Mobile Agent, security type, select Include Groups
  4. Click Save

Check your client access configuration.

This is what it should look like:

  • In Mobile Operator, you should see two groups in the list:
    • ZylincMobileOperatorUsers
    • ZylincMobileAgentUsers
  • In Mobile Agent you should see only one group in the list:
    • ZylincMobileAgentUsers
  • For Mobile Operator, Security Type should be Include Groups
  • For Mobile Agent, Security Type should be Include Groups
  1. In the Administration Portal menu, select INSTALL > Portal Configuration
  2. Make sure that Client, Mobile & Web is selected.

If you're going to use Zylinc Mobile with the agent and queue features:

  1. In the Administration Portal menu, select SYSTEM > Client, Mobile & Web

  2. In the Mobile Agent section, select Mobile Agent

  3. Clear Client Manager cache:

    1. Open the following URL in a browser: https://<Zylinc Windows Application Server>:8443/ClientManager/

      Example: https://WinAppServer:8443/ClientManager

    2. Ignore the security warning about the certificate, and continue to the website

    3. Click Configuration

    4. Log in with user name admin and the password for Tomcat instance ZyTomcat1-8080-8443 user admin

    5. Click Reload Settings

To use Zylinc Mobile you're going add Identity Server to your existing Zylinc solution.

Install Identity Server

  1. Log in as an administrator on your Zylinc Windows Application Server.

  2. Make sure that Microsoft .NET Core version 2.2 or newer is installed.

  3. Copy the PFX file that contains the certificate for your Zylinc Windows Application Server to a folder, for example: C:\Cert\cert.pfx.

  4. In the Deployment Manager menu, select Deployment > Installation.

  5. In Installers, select Identity Server, and click Install Applications.

Initially start Identity Server service to create configuration file

  1. In the Deployment Manager menu, select Deployment > Windows Services

  2. Click Refresh Services

  3. Start Identity Server service

    The service will create a configuration file and then stop

  4. Click Refresh Services

  5. If the service didn't stop and is still running, stop it manually

Overwrite appsettings.json configuration file

  1. Download the following file:

    Mobile_and_Web_Agent_Identity_Server_appsettings.txt

  2. In the File Explorer menu, select View, and make sure that File Name Extensions is selected
  3. Rename the file to appsettings.json
  4. Copy the file to C:\ProgramData\Zylinc\IdentityServer\<version>\IdentityServer in such a way that the existing appsettings.json is overwritten

Edit appsettings.json file

Open the file appsettings.json in a text editor and make the following changes.:

Comments within the JSON code will provide you with the information you need to edit the file.

  1. In the section ConnectionStrings > ZyProdDB, change the following values so that they match the location of your ZyDB database:

    "Server=SqlServer;Database=ZyDB;User Id=ZyUser;Password=password"

  2. In the section SslCertificatePath, change the path so that it matches the path of your certificate file.

  3. In the section SslCertificatePassword, insert the password for your certificate. Use base64 encoding with padding. Padding means that you must include the = chars in the end of the encoded base64 string (if any).

    You can use the following PowerShell command to encode your password:

    [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("password"))

Check the syntax of appsettings.json file

We recommend that you check the file appsettings.json for syntax errors. To do that, you can, for example use the PowerShell script in the following:

  1. Download the following file

    Check_Json_Syntax.txt

  2. In the File Explorer menu, select View, and make sure that File Name Extensions is selected

  3. Rename the file to Check_Json_Syntax.ps1

  4. Copy the file to the folder C:\ProgramData\Zylinc\IdentityServer\<version>\IdentityServer

  5. Right click on the file and select Edit, to open the file in PowerShell ISE

  6. In PowerShell ISE, press F5 to run the script

    You should see a message on the screen: The syntax of the JSON file is OK

    If the script tells that there is an error in the syntax of the JSON file, we recommend that you remove any sensitive information from your file (i.e. usernames, passwords and hostnames), and use an online JSON validator, for example https://jsonlint.com/

    Alternatively, you can use a text editor that supports syntax checking for JSON files. For example, you can get 'Code Writer' from Microsoft Store.

Update Identity Server URL in the Administration Portal

  1. In the Administration Portal menu, select SYSTEM > Interface Configuration

  2. If you don't plan to use Zylinc Mobile from the internet, in Identity Server URL, enter https://<winappserver>:35062/auth/. Replace <winappserver> with the fully qualified DNS name of your Zylinc Windows Application server as seen from your LAN. The name must match the name in the certificate.

  3. If you plan to use Zylinc Mobile from the internet, in Identity Server URL, enter https://<internethost>:<port>/auth/. Replace <internethost> with the fully qualified DNS name of your Zylinc Windows Application server as seen from the internet. The name must match the name in the certificate. For example internethost.companydomain.com

    Replace <port> with the port number of your Zylinc gateway service, for example 35063.

Start Identity Server service and test that the service works

  1. In the Deployment Manager menu, select Deployment > Windows Services

  2. Click Refresh Services

  3. Start Identity Server service

  4. In a browser, go to the Identity Server URL you entered in a previous step, for example https://<winappserver>:35062/auth or https://internethost:35062/auth or https://internethost:35063/auth

  5. The HTTPS web page should open without any security errors.

  6. Click Manage stored grants

  7. Log in as a user that is known to the Zylinc solution.

  8. You should now see a message:

    Client Application Access

    Below is the list of applications you have given access to and the names of the resources they have access to.

    You have not given access to any applications

  9. In the menu, select the e-mail address of the user, and then select Logout, and click Yes

If any of the steps in the previous fail, you can check the Identity Server log file for errors. For more information, see Open latest log file from specific Zylinc module.

Install Client API service

  1. Log in as an administrator on your Zylinc Windows Application Server.

  2. In the Deployment Manager menu, select Deployment > Installation.

  3. In Installers, select Client API Service, and click Install Applications.

Initially start Client API Service to create configuration file

  1. In the Deployment Manager menu, select Deployment > Windows Services

  2. Click Refresh Services

  3. Start Client API Service service

    The service will create a configuration file and then stop

  4. Click Refresh Services

  5. If the service didn't stop and is still running, stop it manually

Overwrite appsettings.json configuration file

  1. Download the following file:

    Mobile_and_Web_Agent_Client_API_Service_appsettings.txt

  2. In the File Explorer menu, select View, and make sure that File Name Extensions is selected
  3. Rename the file to appsettings.json
  4. Copy the file to C:\ProgramData\Zylinc\ClientApiService\<version>\ClientApiService\appsettings.json in such a way that the existing appsettings.json is overwritten

Edit appsettings.json file

Open the file appsettings.json in a text editor and make the following changes.:

Comments within the JSON code will provide you with the information you need to edit the file.

  1. In the section ConnectionStrings > ZyProdDB, change the following values so that they match the location of your ZyDB database:

    "Server=SqlServer;Database=ZyDB;User Id=ZyUser;Password=password"

Check the syntax of appsettings.json file

We recommend that you check the file appsettings.json for syntax errors. To do that, you can, for example use the PowerShell script in the following:

  1. Download the following file

    Check_Json_Syntax.txt

  2. In the File Explorer menu, select View, and make sure that File Name Extensions is selected

  3. Rename the file to Check_Json_Syntax.ps1

  4. Copy the file to the folder C:\ProgramData\Zylinc\ClientApiService\<version>\ClientApiService

  5. Right click on the file and select Edit, to open the file in PowerShell ISE

  6. In PowerShell ISE, press F5 to run the script

    You should see a message on the screen: The syntax of the JSON file is OK

    If the script tells that there is an error in the syntax of the JSON file, we recommend that you remove any sensitive information from your file (i.e. usernames, passwords and hostnames), and use an online JSON validator, for example https://jsonlint.com/

    Alternatively, you can use a text editor that supports syntax checking for JSON files. For example, you can get 'Code Writer' from Microsoft Store.

Start Client API Service and test that the service works

  1. In the Deployment Manager menu, select Deployment > Windows Services

  2. Click Refresh Services

  3. Start Client API Service service

  4. The service should start without errors

Test Client API port and WebSocket port

We recommend that you check that Client API Service works correctly.

To do that, you can use the PowerShell script in the following:

  1. Download the following file

    Test_client_api_service_and_gateway.txt

  2. In the File Explorer menu, select View, and make sure that File Name Extensions is selected

  3. Rename the file to Test_client_api_service_and_gateway.ps1

  4. Right click on the file and select Edit, to open the file in PowerShell ISE

  5. In PowerShell ISE, edit the host names and port numbers in the top of the file, but don't edit anything below the following line:

    ########

    Comments within the PowerShell code will provide you with the information you need to edit the file.

  6. In PowerShell ISE, press F5 to run the script

  1. You should see a message like the following, telling that Test 1 and Test 4 are OK.

    At this point in time, all other tests are expected to return an error, because you haven't set up Zylinc gateway service yet.

    Test 1 - Client API port no gateway: OK

    Test 2 - Client API port through LAN gateway: ERROR: Unable to connect to the remote server

    Test 3 - Client API port through Internet gateway: ERROR: Unable to connect to the remote server

    Test 4 - Client API WebSocket port no gateway: OK

    Test 5 - Client API WebSocket port through LAN gateway: ERROR: Unable to connect to the remote server

    Test 6 - Client API WebSocket port through Internet gateway: ERROR: Unable to connect to the remote server

If any of the steps in the previous fail, you can check the Client API Service log file for errors. For more information, see Open latest log file from specific Zylinc module.

Install Zylinc gateway service

  1. Log in as an administrator on your Zylinc Windows Application Server.

  2. In the Deployment Manager menu, select Deployment > Installation.

  3. In Installers, select Zylinc Gateway, and click Install Applications.

Initially start Zylinc Gateway service to create configuration file

  1. In the Deployment Manager menu, select Deployment > Windows Services

  2. Click Refresh Services

  3. Start Zylinc Gateway service

    The service will create a configuration file and then stop

  4. Click Refresh Services

  5. If the service didn't stop and is still running, stop it manually

Overwrite appsettings.json configuration file

  1. Download the following file:

    Mobile_Agent_Gateway_appsettings.txt

  2. In the File Explorer menu, select View, and make sure that File Name Extensions is selected

  3. Rename the file to appsettings.json

  4. Copy the file to C:\ProgramData\Zylinc\Gateway\<version>\Gateway\appsettings.json in such a way that the existing appsettings.json is overwritten

Edit appsettings.json file

Open the file appsettings.json in a text editor and make the following changes.:

Comments within the JSON code will provide you with the information you need to edit the file.

  1. In the section SslCertificatePath, change the path so that it matches the path of your certificate file.

  2. In the section SslCertificatePassword, insert the password for your certificate. Use base64 encoding with padding. Padding means that you must include the = chars in the end of the encoded base64 string (if any).

    You can use the following PowerShell command to encode your password:



    [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("password"))

  3. Replace all instances of WinAppServer.domain.com with the fully qualified DNS name of your Zylinc Windows Application Server, as seen from your LAN.

  4. In the section GlobalConfiguration > BaseUrl Replace https://InternetServer.domain.com:35063 with the hostname and port number you have opened in your firewall.

Check the syntax of appsettings.json file

We recommend that you check the file appsettings.json for syntax errors. To do that, you can, for example use the PowerShell script in the following:

  1. Download the following file

    Check_Json_Syntax.txt

  2. In the File Explorer menu, select View, and make sure that File Name Extensions is selected

  3. Rename the file to Check_Json_Syntax.ps1

  4. Copy the file to the folder C:\ProgramData\Zylinc\Gateway\<version>\Gateway

  5. Right click on the file and select Edit, to open the file in PowerShell ISE

  6. In PowerShell ISE, press F5 to run the script

    You should see a message on the screen: The syntax of the JSON file is OK

    If the script tells that there is an error in the syntax of the JSON file, we recommend that you remove any sensitive information from your file (i.e. usernames, passwords and hostnames), and use an online JSON validator, for example https://jsonlint.com/

    Alternatively, you can use a text editor that supports syntax checking for JSON files. For example, you can get 'Code Writer' from Microsoft Store.

Start Zylinc gateway service and test that the service works

  1. In the Deployment Manager menu, select Deployment > Windows Services

  2. Click Refresh Services

  3. Start Zylinc Gateway service

  4. The service should start without errors

Use PowerShell to test Zylinc gateway service

We recommend that you check that Zylinc gateway service works correctly.

To do that, you can use the PowerShell script in the following:

  1. Download the following file

    Test_client_api_service_and_gateway.txt

  2. In the File Explorer menu, select View, and make sure that File Name Extensions is selected

  3. Rename the file to Test_client_api_service_and_gateway.ps1

  4. Right click on the file and select Edit, to open the file in PowerShell ISE

  5. In PowerShell ISE, edit the host names and port numbers in the top of the file, but don't edit anything below the following line:

    ########

    Comments within the PowerShell code will provide you with the information you need to edit the file.

  6. In PowerShell ISE, press F5 to run the script

  1. You should see a message like the following, telling that all tests are OK.

    Test 1 - Client API port no gateway: OK
    Test 2 - Client API port through LAN gateway: OK
    Test 3 - Client API port through Internet gateway: OK
    Test 4 - Client API WebSocket port no gateway: OK
    Test 5 - Client API WebSocket port through LAN gateway: OK
    Test 6 - Client API WebSocket port through Internet gateway: OK

Use web browser to test Client API port through Zylinc gateway service from LAN

You can use a web browser to test Client API WebSocket port.

  1. Download the following file

    Test_client_api_service_and_gateway_websocket_in_browser.txt

  2. In the File Explorer menu, select View, and make sure that File Name Extensions is selected

  3. Rename the file to Test_client_api_service_and_gateway_websocket_in_browser.txt.html

  4. Use a text editor to edit the following line:

    let socket = new WebSocket("wss://InternetServer.domain.com:35063/socket"); //use this line to test WebSocket through gateway

  5. Replace InternetServer.domain.com with the name of your Zylinc Windows Application Server

  6. Save your changes and open the html file in a web browser

  7. You should see the following message:

    [open] Connection established, send -> server

  8. Click OK

  9. You should see the following message:

    [message] Data received: pong <- server

When you see the word pong, you know that your WebSocket works through the Zylinc gateway service.

If any of the steps in the previous fail, you can check the Zylinc gateway service log file for errors. For more information, see Open latest log file from specific Zylinc module.

  1. Get the Zylinc Mobile app:

    For iOS devices: Get Zylinc Mobile from App Store

    For Android devices: Get Zylinc Mobile on Google Play

  2. Start the app and enter the e-mail address and password for a Mobile Operator user within your organization (that's a user without the ability to work with queues as an agent)

  3. In the menu, tap Colleagues

  4. You should see a list of users within your organization

  5. To make a test call to, for example, a user's mobile phone number, tap a user and tab Call mobile

  6. Zylinc Mobile should initiate an outgoing call via the SIM card in your smartphone

If you succeed, you know that network connectivity, user authentication, and basic functionality of Zylinc Mobile works.

  1. On the smartphone, create a mobile hotspot

  2. On a laptop, disconnect all network connections, and then connect the laptop’s Wi-Fi to the hotspot

  3. On the laptop, start PowerShell. Copy and paste the following command into the PowerShell Window (replace 35063 with the port number that you opened in your firewall, and replace internethost.companydomain.com with the internet hostname that you opened in your firewall):

    test-netconnection internethost.companydomain.com -port 35063

  4. You should see TcpTestSucceeded : True

If you don’t see TcpTestSucceeded : True, check your organization's firewall configuration. If you use DMZ, also test that Zylinc Proxy and Zylinc Proxy Client work as described in the previous.

When you make a log in attempt from the smartphone app to an e-mail address that is correctly registered with the Zylinc autoconf service, you can use the Zylinc gateway service log file to view if a request reaches your server.

You can use this fact to check that Zylinc autoconf service and Zylinc Mobile can locate your host with the open port on the internet.

  1. In a text editor, open the following file: C:\ProgramData\Zylinc\Gateway\<version>\Gateway\appsettings.json

  2. In the Logging > Ocelot section, locate the following line:

    "Ocelot": "Warning"

    Replace "Warning" with "Trace"

  3. Restart Zylinc gateway service.

  4. Open the Zylinc gateway service log file. For more information, see Open latest log file from specific Zylinc module.

  5. In the log file, search for the following string: /zylinc/api/v1.0/auth/identityServer

    If you can’t see lines in the log that contains that text, something is wrong with the registration of your e-mail domain. Contact support to solve the problem.

  6. Go back to step 2 and change "Trace" back to "Warning"

  7. Restart Zylinc gateway service.

If your organization is going to use Zylinc Mobile with the agent and queue features, also test the following:

  1. To test that the agent and queue features in Zylinc Mobile work, you should first test Zylinc Mobile without the agent and queue features, as described in the previous. This is because the agent and queue features are technically an add-on.

  2. When ready to test the agent and queue features, log in to Zylinc Mobile with an e-mail address of a user from your organization whom you’ve set up as a Mobile Agent user, and who's a member of a voice queue.

  3. In the app's menu, tap Mobile Agent.

    If you can’t see the Mobile Agent menu item, review your Zylinc Mobile setup as described in the previous.

  4. Tap Sign in. You can now see a list of the user's queues.

    If you can’t see that the agent becomes active, make sure the agent is a member of at least one voice queue.

  5. Tap the toggle button next to a queue, so that the toggle switches to the 'on' position.

  6. From another phone, call the queue that you activated in the previous step.

    If you can’t call the queue from another phone, make sure that the queue is open. If not, you can use the Administration Portal to add an open exception to the opening hours of the queue.

  7. You should be able to answer the call on the mobile phone of the Zylinc Mobile user.

  1. Clear client manager cache :

    1. Open the following URL in a browser: https://<Zylinc Windows Application Server>:8443/ClientManager/

      Example: https://WinAppServer:8443/ClientManager

    2. Ignore the security warning about the certificate, and continue to the website

    3. Click Configuration

    4. Log in with user name admin and the password for Tomcat instance ZyTomcat1-8080-8443 user admin

    5. Click Reload Settings

  2. Log out of Zylinc Mobile, and then log in again.

  3. If it still doesn’t work, reinstall the app.

  4. If it still doesn’t work, use ZyDesk to test that the Zylinc solution's Media Server can call the mobile phone number of a Mobile Agent user (which isn't the same as calling the mobile phone number from a desktop phone or soft phone).

    1. In the Administration Portal menu, select USERS > Agents
    2. Click ZyDesk Administrator
    3. Under User (Operator), clear the Default check box,and the select Internal in the Device menu
    4. Under Agent - Incoming Calls, clear the Default check box, and select Internal in the Device menu
    5. Click Save
    6. Then, in the menu, select INSTALL > Database Connection
    7. Click Rewrite Config, and answer OK
    1. Log in to ZyDesk as administrator@Zylinc.com
    2. Search for a person who’s going to use Zylinc Mobile with the agent and queue features.
    3. Double-click the phone number in the Mobile column next to the person’s name.
    4. An outgoing call should be initiated to the user’s mobile phone, and the user’s mobile phone should begin to ring.

    If the Media Server can’t call the agent’s mobile phone number, there’s a problem with your telephony integration. Check your SIP trunk and number plan configuration. You can also Set up SIP logging on Zylinc Media Server, and ask an IP telephony specialist to help use the SIP logs to identify the root cause of the failed call.