User Tools

Site Tools


implementation:scan:install

Installation Guide

1. Prerequisites

The following database management systems are supported:

  • MSSQL Server 2012, 2014, 2016
  • SAP HANA SPS11 or higher

Requirements for the machine where the Produmex Service Broker runs:

  • Windows 2008 R2/Windows 7 or higher
  • Administrator rights
  • Installation of .NET 4.0 framework or higher
  • Installation of SAP DI API (32/64-bit) depending on Service Broker version (32/64-bit)
  • HANA Client (On HANA environment only)
  • Installation of SAP Business One. Make sure that Crystal Reports engine is installed as part of the SBO installation.
  • SBO client needed with Crystal Reports engine in case of printing throught the Service Broker

Requirements for the machine where the Produmex add-on runs:

  • Windows 2008 R2/Windows 7 or higher
  • Administrator rights
  • Installation of .NET 4.0 framework or higher
  • HANA Client (On HANA environment only)
  • Installation of SAP Business One. Make sure that Crystal Reports engine is installed as part of the SBO installation.
  • A valid Produmex license

Please note: In order to use the scanning function, set the TAB suffix on the device.

For more information about hardware requirements and server sizing please see: Produmex Scan - Server sizing

2. Technical Background

Produmex Scan comprises of 3 parts:

  • The Produmex Scan Add-on
  • The Service Broker and the Produmex Scan module
  • The Produmex Scan client application

Connection method
The add-on must be installed in SAP Business One. It is used mainly for set-up and administrative purposes; it does not need to be running for the mobile devices to work.

The Service Broker handles the requests that come from the mobile application and processes them using the SAP DI API (for example based on the requests from the mobile device it creates a goods receipt PO or a delivery).

The client application is used to enter the data for the stock movements which is then sent to the Service Broker. The client application can run natively on the mobile device, or on the server and be accessed through remote desktop, depending on the network latency constraints or use case as described below.

Native client
The traditional and recommended way is to install Produmex Scan on the device directly where it can run as a native client. The Produmex Scan client application connects to the Service Broker by using HTTP/TCP protocols.

This connection method is recommended for on premise use or on cloud environments where the connection between the client and the server is fast and optimized.

Layouts of possible scenarios:

On premise

Cloud as native

Remote desktop
On cloud environments where the network connection is slower, the traditional connection method might cause latency due the number of messages sent by the Produmex Scan client. In order to improve the communication speed, it is recommended to run the application on a remote desktop. This way the client and the service broker communicates within the same network therefore the long distance traffic decreases.

In this case the client application and the Service Broker run on the same server. The application can be reached through a remote desktop application from the handheld device.

The remote desktop connection method is only recommended in cloud environments where latency issues occur due the slow connection between the client and the server.

Cloud remote

For more information about how to set up Remote Desktop Connection please see: Setup Remote Desktop Connection. When setting up the remote desktop connection, enable the ‘Full screen’ and the ‘Fit remote desktop to screen’ display options.

Client Configurations When using the remote desktop connection method we recommend the following display settings:

  • Set the Windows layout to ‘Desktop fullscreen’
  • Disable the built-in OS buttons by ticking the ‘Do not use built-in OS buttons’ option

3. Installing Produmex Scan

To make the system work you have to do the following:

  • Install the Produmex Scan add-on in your SAP company database and run the DBSetup.
  • Install the Service Broker + Produmex Scan server component on your SAP server and configure it.
  • Install the Produmex Scan application on the mobile devices.

3.1. Install Produmex Scan Add-on

3.1.1. Install the add-on

3.1.1.1. On Premise
3.1.1.1.1. Registering the Add-On

Extract the content of the .zip file on your local machine.
The .zip file contains two files:

  • BXMobileWH9Setup.ard
  • BXMobileWH9Setup.exe

In SAP Business One, open the Add-On Administration window (Main menu > Administration > Add-Ons > Add-On Administration).
Click on 'Register Add-On' button.

Click on the '…' button beside the Registration Data File and browse the BXMobileWH9Setup.ard file. SAP Business One will fill out the path to the .exe file automatically. Enable 'Install as Part of Registration' and click on the 'OK' button. Add-on registration

First SAP Business One will register the add-on and then it will start the installation wizard.

3.1.1.1.2. Proceeding with the installation

If the 'Install as Part of Registration' checkbox was turned on, the installation will start right away with starting the install wizard. Click on the 'Next' button to start the installation.

Accept the End-User License Agreement by selecting the 'I accept the agreement' option, and then click on the 'Next' button.

Make sure all components are checked and that there is enough disk space. Click on the 'Next' button.

Click on the 'Install' button to proceed with the installation.

If the installation process takes too long time, then SAP Business One will ask you if the installation finished successfully.

System message

If the installation was successful, click on the 'Yes' button.
Please note: If there was an error during installation, it will be failed regardless of your answer.

3.1.1.1.3. Activating the Add-on

Now you can see the add-on under Company-Assigned Add-Ons, on the right part of the window.
Make sure the 'Active' box is checked.
Change the Default Group from 'Disabled' to 'Manual' or 'Automatic'.

  • 'Automatic' means the add-on will launch each time you start SAP Business One.
  • 'Manual' means you have to launch the add-on manually after each time you start SAP Business One. It is advised to use this option during the configuration phase.

Click on the 'Update' button to save the changes.

3.1.1.2. In SAP Cloud
3.1.1.2.1. Install the add-on on the Could Control Center

Download the lightweight installer. The zip file is named: ProdumexScanAddOnSetup_<version number>_<SBO version number>_<environment>_lightweight.zip

Create a Produmex sub folder within the folder you defined as the Extension Repository Path. Upload the zip folder of the lightweight installer to this Produmex folder. Do not unzip the file.

On the Could Control Center, navigate to Landscape Management > Extensions.

Check whether the installation file is listed on the Extensions grid then press the ‘Synchronize All’ button to install the Produmex Scan add-on. Confirm that you would like to synchronize all extensions.

If the installation is successful, on the opening Synchronization Report the status on the line of Produmex Scan is 'Successful'. The installation zip is automatically moved to the Produmex Shared Repository folder.

3.1.1.2.2. Deploy the add-on to the Service Unit

When upgrading the add-on to a new version, make sure that the add-on is not running on any presentation server. If there is a running add-on, the upgrade will fail.

Next deploy the add-on on every service unit where you would like to use it.

Navigate to Landscape Management > Service Units. On the Service Units grid select the target service unit.

On the Service Unit Details grid go to the Extensions tab and click on the Deploy button. Follow the steps of the Extension Deployment Wizard. Select the Produmex Scan add-on at the Select Extensions step then finish the deployment.

3.1.1.2.3. Assign the add-on to the tenant(s)

This step is not required in the case of a version upgrade.

Finally assign the Produmex Scan add-on to the tenant(s) where you would like to use it.

Go to Customer Management > Tenants. Select the tenant on the Tenants grid. On the Tenant Details grid navigate to the Extensions tab, then click on the ‘Assign’ button. Follow the steps of the Extension Assignment Wizard. In the Select Extensions step select the Produmex Scan add-on, then finish the assignment.

3.1.2. Database Setup

When you first start the add-on after the installation, it will create its own database tables and user defined fields. The add-on will display a message whether to upgrade the database or not. Click on the ‘Yes’ button to upgrade the database.

To be able to run the DBSetup the SAP user must be superuser.

Please note: On MSSQL, the system will check whether there is a backup created within an hour. If no such backup is detected, a warning will be shown and the add-on exists. Create a backup of the database then restart the add-on.

On the next screen set up the database connection. Enter the database user name and the database password. After the DB Connection is set up, the system will upgrade the database.

DB connection setup

After clicking on the 'OK' button, a progress bar will appear and it will go through the database setup process. After the database structure has been modified, another System Message is displayed. Click on the ‘Yes’ button to add the user-defined fields.

A confirmation is displayed that the database structure have been modified. Acknowledge the message.

A System Message window warns that the add-on stopped:

Here you have to choose Continue working without this Add-on and restart SAP. Now you can start using the add-on in SAP.

3.2. Produmex Service Broker

Make sure you do not run both the 32-bit version and the 64-bit version Service Broker on one environment as they conflict with each other. Only one service broker instance should be installed on a server at any time.

The Service Broker establishes the connection between the company database/schema and the application on the mobile device. It queries the data from the database/schema and sends it to the mobile application, and it creates the SBO documents based on the requests from the mobile devices. The SBO documents are created with SAP DI API 32bit version.

The Service Broker can run as a service or from a command window. It creates threads for the different requests which are independent from each other so if one thread has a problem it can be closed and the others are not influenced by it.

If the Service Broker does not run, the communication between the clients and the company database/schema is not possible.

The service broker creates its log files at C:\ProgramData\BX\BX Service Broker\Logs. The ProgramData folder is hidden, you have to either enable 'Show hidden folders and files' in Windows Settings or you have to enter it directly to the address bar in Windows Explorer:

Log files

Install the service broker on the server which has access to the company database/schema. The installation file is an .exe file with a name like this one: BxServiceBroker.Setup.exe.

EULA
After launching the .exe file, the End User Licence Agreement will open up. Produmex Service Broker can only be installed if the License Agreement is accepted.

EULA

Service settings
When you start the installation, the Produmex Service Broker installer will request information based on the system and will set up the service based on the information you enter.

The installer will first ask the user who will be assigned to the service broker service in windows. This must be a user who has rights to write the event log and the program data directory where the logs are created. The service broker service will also make a connection to the company database/schema, the user must have rights for that as well.

Local System users usually do not have the right to use printers, therefore, it is recommended to configure a Windows user.

The default port for the communication between the service broker and the clients is 50231. The installer will open the firewall for this port automatically, but if you change the port, you will have to change the firewall settings manually.

You can also set up the start mode of the service. The recommended start mode is Auto.

Service Settings

Admin page
On the next screen specify a password for the Service Broker Administration web page.

Admin Page

Database connection
Then you have to provide connection data to the database server.

Select the database type from the dropdown menu.

  • MSSQL
    Add the name or the IP address of the database server. If you have a named instance, you have to enter the name of the server and the named instance as well (for example SERVER\NAMEDINSTANCE).
    Enter the database port on which the application can connect to the server. The default port is 1433.
    Add the name and the password of the database user. The default user is sa.

Database connection

  • HANA
    Add the name or the IP address of the database server. The database server name has to be added with the exact same format as it was added during the installation of the SAP Business One client.
    Enter the database port on which the application can connect to the server. The default port is 30015.
    Add the name and the password of the schema user. The default user is SYSTEM. It is recommended to install the Service Broker with the SYSTEM user.

Database connection

When working on SAP B1 Cloud, add the domain user name and password as well.

Default SAP Company
After that you have to set up the company database/schema. You can only set up one company here, if you have more than one database/schema, you can add the others in the Produmex Service Manager after installation. For more information please see: Produmex Service Manager-Add new database.

Enter an SAP user here which has at least an indirect access license as of SBO 9.2. PL08.

Add default company

Summary
At the end of the installation you will see a summary screen about you settings. Click ’Finish’ to end the installation.

Summary

Configure dependency from the SBO Server Tools service on an MSSQL system
If the server where Produmex Service Broker runs needs to be restarted frequently, we advise to configure dependency from the SBO Server Tools service.

When Produmex Service Broker starts, it tries to connect to the SAP environment. If the connection fails, Produmex Service Broker will not start.

If the Produmex Service Broker is dependent from the SBO Server Tools service, it will only start after the SBO Server Tools service is started, therefore it will be able to connect to the SAP environment.

To configure the dependency, open the Command Prompt window and enter the following:

C:\>sc config BXServiceBroker depend=B1ServerTools

dependency

On the Dependencies tab of the Produmex Service Broker properties you can see that the dependency is successfully added:

dependency

Make sure you do not set the dependency on HANA enviroments. Since the Produmex Service Broker is a Windows service, SAP HANA and Produmex Service Broker are running on separate servers. In order to avoid this issue, make sure that the HANA server is already running when you restart the server of the Service Broker.

3.3. Server Module

The Produmex Service Broker can work together with different Produmex add-ons. In order to do it, it uses the dlls of the given add-on. You need to install these dlls with the server installer which has a name like this: ProdumexADD-ON NAME_ServerSetup_version nbr_ SBO Version_Database server type.32/64 bit installers.zip.

The add-on and the server dlls must be for the same version. If you use different versions, error messages may appear. You simply have to start the installer and it will automatically copy the dlls and then restart the service broker service. You can check the installed modules in the Service Manager. For more information please see: Configuring Produmex Service Broker

3.4. Produmex Service Manager

The Produmex Service Manager is a standalone program that can handle the Produmex Service Broker and other Produmex services. Service parameters, connection data to the database server, and the connection data to the company database/schema can also be modified on the Service Manager.

It is automatically installed by the Produmex Service Broker installer. The Service Broker will automatically appear in the Produmex Service Manager, together with all other installed Produmex services that are supported by the Service Manager.

3.4.1. Setup/Modify Connection data to the SAP company

Click on the ’Setup Companies’ button. On the opening window you have to enter the connection data to your SAP company database/schema.

  • MSSQL
    At ’Server’ enter the name or IP address of the server. At ’Port’ you have to enter the port on which the application can connect to the database server. Usually it is 1433, however, if you have a named instance in the SQL server, then you have to check the actual port.
    Then choose MSSQL version number and enter the SQL Server user name and password.
    Setup companies

How to check the port number on SQL
Open the SQL Server Configuration Manager. Select the SQL Server instance then right click TCP/IP on the right side and click on Properties. In the small window go to the bottom and check the port number.

Check port number

Please note: in this example there are no instances, so the port is the default 1433.

  • HANA
    At ’Server’ enter the name or IP address of the server. Please note: The database server name has to be added with the exact same format as it was added during the installation of the SAP Business One client.
    At ’Port’ you have to enter the port on which the application can connect to the database server. The default port is 30015.
    Select HANADB from the dropdown menu and enter the user name and password.
    Setup companies

When working on SAP B1 Cloud, add the domain user name and password as well.
At 'Language' it is possible to modify the language of the DI API transactions.

If you click on Test DB Connection, Service Manager will try to connect to the server with the given data. If the connection can be established, you will get a message: Database connection test – success!

3.4.2. Add new database

Click on the Setup Companies button.

On the opening ‘Setup companies’ screen check the connection data. If you would like to add a database from a different database server, modify the connection parameters then click on the ‘Test DB Connection’ button to test the connection. The modification of the connection parameters does not affect the connection settings of the already added databases.

Click on the ‘+’ icon to add a new database/schema.

On the ’Database Setup’ window select the database/schema from the dropdown menu.

Enter an SBO User and its password to create the connection to the database/schema. SAP employees are used for log in the mobile device. Transactions initiated by the employees will be posted by the SAP user defined for the Service Broker. The SBO user must have the authorizations to create stock related bookings in SAP Business One (Delivery, Goods Receipt PO, Stock Transfer, etc.) The SBO user also need at least an SAP Indirect Access license type as of SBO 9.2. PL08.

Database setup

Click on the ‘Save’ button then close the window. You can close now Setup Companies and go back to the Service Manager main screen.

Now you have to assign your companies to the Produmex Service Broker and other Produmex services.

Click on the ‘Companies…’ button and select the company database/schema on the opening ‘Select Companies’ screen.

Select companies

3.4.3. Configuring Produmex Service Broker

The Produmex Service Broker can work together with different Produmex add-ons, therefore in the Service Manager you have to configure which add-on you want to use. To do that, click on the ‘Configure…’ button or select it from the line of the Service Broker.

General tab
If you set the 'Debug writeline log' parameter to true, it will write a log about each command the Service Broker processes. Only set it to true, if Produmex support asks you to do that.

'Kill time' means that if a thread doesn’t respond to a request within this time limit, it will be killed. The setting depends on your server. If you have a quick server, set it to a small number, if you have a slow server, set it higher. Default is 10 seconds.

'Modules to load' is the module of the add-on to which the service broker connects. It is automatically done by the module installer for you, so you only have to set this manually in specific cases. To add multiple modules, separate them by comma.

  • In order to use Produmex Manufacturing, set it to BXPPSMobilePDCWebAPI.dll
  • In order to use Produmex Scan, set it to BXMobileWH9WebAPI.dll
  • In order to use Produmex Operator, set it to BXMWWebAPI.dll.

At the 'Port to listen on' you can set which port is used by the service broker to communicate with the clients. The default is 50231. Make sure that the port you set here is not blocked by any firewalls or antivirus software.

The 'Server Discovery Enable' turns on the feature that the client can look up the running service broker server automatically. It makes setting up the clients easier.

You have to assign an administrator user to the service in the Windows Service Manager, otherwise the Service Broker cannot connect to SBO and cannot write to its log files. If the Service Broker stops right after starting it, and in the log file you have access denied errors, then the cause is that you haven’t assigned the administrator user to the service.

Produmex Service Configuration

Produmex Service Broker tab
On the Produmex Service Broker tab you can see the loaded modules, and you can remove/install new modules if needed.

If you see a check icon before the module name, it means it could be loaded successfully. If a problem arises, you will see error beside the module name.

Produmex Service Configuration

3.4.4. Start Produmex Service Broker

After you have set all settings and installed the server module, you can start the Service Broker service in the Service Manager by selecting first the service then clicking on the ‘Start’ button. If you want to stop a service, click on the ‘Stop’ button.

You can also stop or start the services from windows service manager, but you cannot change the Produmex settings there. It is recommended that you set the service to Automatic start and that you set the recovery options to Restart at Recovery in Service Properties for the service.

If you want to start the Service Broker from the command window, you can start it with “C:\Program Files (x86)\Produmex\ServiceBroker\BxServiceBroker.Console.exe” (or Service Broker (Console) program in the Windows Start menu) and you will see a window like this:

The use of the command window is recommended for debugging purposes. In production environment the use of the service is more efficient.

3.5. Produmex Scan Client Application

In order to run the Produmex Scan client application on the mobile device you need the Microsoft .NET Compact 3.5 framework on all the mobile devices where the application will be used. For more information about hardware requirements and recommendations please see: General requirements for handheld devices

If you have a server operating system (for example Microsoft Windows Server 2003), you have to install the windows desktop experience component of windows from Control Panel>Programs and Features>Turn Windows Features On or Off.

Then you have to install the Windows Mobile Device Center 6.1 driver:

If it is not installed, you will get a message during installation that active sync is needed.

For windows 8 and 8.1 operating systems it can also be needed to install the Microsoft active sync component.
This step is not needed for the non-server operating systems.

Cradle the mobile device on your computer. Then run the Produmex Scan Application setup file contained in the ProdumexSCAN_ClientWM6Setup_version nbr._SBO version_Database server type.32/64 bit version.zip file on the host computer with administrator rights.

Install wizard

Follow the instructions of the installer. Choose the destination folder.

The installer will set up on the cradled, connected mobile device as well.
If for some reason the installation on the mobile device is interrupted, it can be installed directly on the mobile device, too. Copy ProdumexSCAN_ClientWM6Setup_version nbr._SBO version.cab from c:\Windows\WindowsMobile\BXMobileWarehouse\ to your mobile with Windows Mobile Device Center, and then run it in the mobile device.

Install on the device

You can find the configuration form and the application among the installed programs (under the start menu).

Install on the device

When started for the first time, it will open the configuration window. When you already configured it, it will open the login screen instead. If you want to start the configuration again, you have to start 'Configure Produmex Scan' on the mobile device. For more information about client configurations please see: Configure Produmex Scan

With the installer new shortcuts will also be added to the start menu under the Produmex folder, to run Produmex Scan and Configure Produmex Scan in desktop mode. This helps you simulate the mobile device client in an easy way, without needing to set up an emulated mobile environment.

4. Performing a version upgrade

Please always check the release notes of the new version before starting the upgrade, because it might contains important information regarding the upgrade.

4.1. Produmex Scan Add-on

The steps of a version upgrade for the Produmex Scan add-on are identical to a new installation.

If you are upgrading from a version higher than 17.05, it is not required to uninstall the current version before starting the upgrade.

When the add-on is started the first time after the upgrade, the database setup will run.
Please note: In order to run the database setup, a database backup that was created within an hour is required on an MSSQL environment.

4.2. Produmex Service Broker

If you are upgrading from version 17.09 or higher, it is not required to install a new version of the Service Broker for an upgrade of Produmex PDC/Scan. If you are upgrading from a version previous to 17.09, please take the extra steps described here: Version 17.09. The steps of a version upgrade are identical to a new installation.

If you would like to uninstall the 32-bit DI API when upgrading to the 64-bit Service Broker, it is advised to uninstall both the 32-bit and the 64-bit DI API and then install the 64-bit DI API again because on certain SBO versions the uninstallation of the 32-bit DI API can cause issues for the 64-bit DI API.

Compatibility matrix

Service Broker Version
18.2. 18.1. 17.11. 17.09. 17.05.
Server Module version 18.2.
18.1.
17.11.
17.09.
17.05.

4.3. Server Module

The steps of the version upgrade for the server module are identical to a new installation.

4.4. Produmex Scan client

The steps of the version upgrade for the Scan Client are identical to a new installation. If you are upgrading from a version higher than 17.05, only uninstall the current Produmex Scan version if based on the settings of the operating system, the installation process requires it.

5. Adding a new database to an existing installation

1. Assign the Produmex Scan Add-On to the database.

2. Start the add-on and run the database setup. When working on a MSSQL environment, create a database backup before starting the database upgrade.

3. Open Produmex Service Manager. Click on the ‘Setup Companies’ button and add the database. Then click on the ‘Companies’ button and enable the company. For more information please see: Produmex Service Manager

4. Run the configurator for Produmex Scan. On the General tab, select the database from the list of databases and click OK.

6. Troubleshooting

6.1. Failed installation

If installation fails for some reason, you usually find the add-on at the Pending add-ons tab, from where you can try the installation again. Select the line of the Produmex add-on, then click on the 'Install' button.

Pending add-ons

6.2. Getting a license

An active license is needed for running correctly this add-on. For more information about licensing please see: Licensing System

License

6.3. No backup detected

If the system detect that there is no backup, it will show this window:

Db backup
Press OK. As the add-on stopped, the system will ask you how you want to continue:

Choose the last option: Continue working without this Add-on, and then press OK. It will stop the add-on. To continue, back up the current customer database.

6.4. Wrong digital signature for Add-on installer

When starting the Produmex Manufacturing add-on after the installation, the following error message appears: 'Wrong digital signature for Add-on installer'

The most likely cause for this issue is that the installation .exe file was corrupted during the extraction process. Extract the installation .zip folder again and start the installation afresh.

6.5. Connection to the company failed on HANA

During the installation of the Service Broker on HANA environment, the following error message appears after the default SAP company was specified:

It means that the connection cannot be established to the database server. Go back to the Database connection screen of the Service Broker installer and enter the name of the database server with the exact same format as it was defined during the installation of the SAP Business One client.

implementation/scan/install.txt · Last modified: 2018/04/19 14:10 by csuhaa