How to setup the new ticket vending machine - from configuration to deployment

This documentation is a step-by-step guide on how to setup the new ticket vending machine (TVM). It includes two sections: Configuration and Deployment.

Architecture and State Machine Diagram

Configuration

The new TVM software is simply a web application that can communicate with local hardware like payment terminal & ticket and receipt printers. The following steps demonstrate how to configure a new TVM in SecuTix's parameterization screens. 

Workstation configuration

This step aims at setting up a TVM workstation and configuring all the hardware that are connected to the TVM.

1. Go to tab Organization > Initialization > Organization parameters > Workstations
2. Click "+ New" to add a new workstation
3. Setup the general information in the General Tab:
   1. Input all the mandatory fields of the new workstation

   2. Input the correct "Terminal number" for the TPE

      Please contact Contactis if you are not sure which terminal number to use for your vending machine's TPE.

   3. Click "Save" button on the top-left corner to save the "General" tab
4. Configure the payment terminal (TPE):
   
   1. Go to tab "Hardware" & click "+ New"
   2. Choose "TPE" in the Type dropdown
   3. Choose "iSelf V3" in the Hardware dropdown & click "Next" (as shown in the screenshot on the left below)
   4. Input the "TPE" as "Internal name" and "Code"
   5. Choose the correct port name in the "Port" dropdown
      Note: this is the port name that TPE is connected to on the vending machine PC (usually it's COM2) (as shown in screenshot in the middle below)
   6. Click "SAVE AND CLOSE" to save the changes and close the window
   7. Go to tab "Hardware order > TPE" 
   8. Double click the "TPE" item to move it from the "Non selected" box to the "Selected and ordered" box (as shown in the screenshot on the right below)
   9. Click the "Save" button
      
      
      
5. Configure the Ticket Printer (currently all the vending machines are using BOCA printer as the ticket printer):
   1. Go to tab "Hardware" & click "+ New"
   2. Choose "Printer" in the Type dropdown
   3. Choose "Ticket" in the Sub type dropdown
   4. Choose the right hardware type for the BOCA printer that is used by the ticket vending machine & click "Next" (as shown in the screenshot on the left below)
   5. Input the "BOCA" as "Internal name" and "Code"
   6. Set the correct parameters in the remaining mandatory fields (as shown in screenshot in the middle below)
   7. Click "SAVE AND CLOSE" to save the changes and close the window
   8. Go to tab "Hardware order > Ticket Printer" 
   9. Double click the "BOCA" item to move it from the "Non selected" box to the "Selected and ordered" box (as shown in the screenshot on the right below)
   10. Click the "Save" button
       
       
       
6. Configure the Receipt Printer (currently all the vending machines are using Zebra printer as the receipt printer):
   1. Go to tab "Hardware" & click "+ New"
   2. Choose "Receipt Printer" in the Type dropdown

   3. Choose the correct hardware type for the receipt printer that is used by the ticket vending machine & click "Next" (as shown in the screenshot on the left below) 

      Choose "Zebra NE" if you don't want the receipt printer to eject the receipt after printing. Otherwise choose "Zebra E".

   4. Input the "Receipt Printer" as "Internal name" and "RPR" as "Code"
   5. Choose the correct port name in the Port dropdown
      Note: this is the port name that receipt printer is connected to on the vending machine PC (usually it's COM1) (as shown in screenshot in the middle below)
   6. Click "SAVE AND CLOSE" to save the changes and close the window
   7. Go to tab "Hardware order > Receipt Printer" 
   8. Double click the "Receipt Printer" item to move it from the "Non selected" box to the "Selected and ordered" box (as shown in the screenshot on the right below)
   9. Click the "Save" button
      
      
      

Sales channel configuration

This step aims at setting up a sales channel for the new TVM.

1. Go to tab Institution > Initialization > Institution parameters > Sales Channels
2. Click "+ New" to add a new sales channel
3. Choose "Internal" as the Sales channel type and click "Next" to continue
4. Fill in the "Internal name" and "Code" of the new sales channel
5. Select "Ticket Vending Machine (New)" in the Type dropdown
6. Authorize the contingents as you wish (as shown in the screenshot on the left below)

7. Go to the "Parameters" tab and configure the values accordingly (as shown in the screenshot on the right below). Please make sure the following two parameters are correctly set:

   Please make sure that the required migration script to setup the correct psp parameters is executed before you do this step.

   1. Choose "Ingenico MPA no SSL" as the "Payment service provider"
   2. "Mode of shipment" must be "Immediate", which means the tickets will be printed immediately after purchase
      
      

8. Click "SAVE AND CLOSE" to save the changes and close the window
   
   
   

Point of sales configuration

This step aims at setting up a point of sales (POS) for the new TVM.

1. Go to tab Organization > Initialization > Organization parameters > Sales Channels & double click on the TVM sales channel you created in step Sales channel configuration
2. Go to the "Point of sales" tab and click "+ New" to add a new point of sales
3. Fill in the mandatory fields in the "General" tab and make sure to:
   1. select the corresponding workstation configured in step Workstation configuration in the Workstation dropdown.

   2. put a unique url for each vending machine:

      The recommended url pattern is: https://INSTITUTION_CODE-TVM_Name.ENVIRONMENT_NAME-shop.secutix.com/

      e.g. https://mosa-tvm1.int1-shop.secutix.com/, https://mosa-tvm2.int1-shop.secutix.com/ ...

      
      
      

4. Go to the "Vending machine parameters" tab and Click "GENERATE" button to generate a secret token.

   This secret token is used for authentication when TVM is communicating with SecuTix's REST api.

   1. OPTIONAL - To enable Google Analytics Tracking you can also put the value of your GA Tracking ID or GTM Container ID into the corresponding field. For detailed instructions on how to enable GA or GTM tracking, please visit this page.

   
   
   
5. Configure the "Currencies" and "Payment modes" tabs based on your needs
6. Click "SAVE" to save the changes

How it looks - Light customization configuration

This step aims at setting up a theme for the new TVM, which defines its look & feel.

1. Go to tab Organization > Initialization > Organization parameters > Sales Channels & double click on the TVM sales channel you created in step Sales channel configuration
2. Double click on the Point of sales you created in step Point of sales configuration
3. Go to the "Theme" tab and follow the mapping information below to parameter the theme

Light customization mapping

What products to show - Landing page configuration

The new TVM allows you to freely choose the product grouping and presentation layout displayed on the TVM storefront page. The configuration is the same as the landing page for online sales platform. Please visit A dynamic shop window for more information. 

Configure opening & closing time

Like in the old Borne, the new TVM also allows you to configure the opening & closing time via menu Organization > Tools > Vending machine configuration > Opening hours.

Deployment

As mentioned above, the new TVM software is simply a web application that can communicate with local hardware like payment terminal & ticket and receipt printers via device manager (as illustrated in the diagram below). In this section we are going to explain you how to deploy the new TVM, including two big steps: installation of the device manager and deploy the TVM web app in Chrome Kiosk mode. 

Download and install Device Manager

1. Go to this page to download the device manager installer

2. Find the .exe file you just downloaded and double click on it
3. Install the kit with default settings

Setup Chrome to run the TVM web pages in Kiosk mode

1. Install the latest version of Chrome from Chrome's official website.
2. Create a new Chrome profile and check "create shortcut on Desktop"
3. Go to Chrome Settings and install SecuTix Root Certificate (you can download the certificate from this page : here)
   1. Extract the zip file you downloaded
   2. Import the file "SecutixRootCA256.crt" to Chrome "Trusted Root Certification Authorities" via Chrome Settings.
      
   3. You might have to install it locally first, then for the current user.
   4. 
4. Change the "On startup" option to "Open a specific page or set of pages"
5. Click on the "Set page" and put in the TVM PoS url that you configured in the previous section "Point of sales configuration"
6. Close the Settings menu and go to the page with the TVM PoS url (e.g. https://tvm1-mosa.int1-shop.secutix.com/)
7. Right click on the page and click on "Inspect" to open the web inspector
8. Go to "Application" tab and input the following <Key, Value> pair into the TVM Web Host's Local Storage:
   Key: secutixApiSecretKey
   Value: use the secret token that is configured in "Point of sales configuration"
   
   
   
9. Close Chrome
10. Find the Chrome shortcut created at step 2 on desktop & Right click -> Properties
11. In the Shortcut > Target field append this at the end and Save & Close the properties popup : --kiosk --disable-pinch --overscroll-history-navigation=0 --remote-debugging-port=9222 TVM_PoS_url_that_you configured_in_the_previous_section
12. Double click the shortcut to start the TVM
13. go to the page “pointofsalesurl/content/admin” and check the status. If ticket printer is KO, click on Set ticket counter and input a value. Status should now be ok. Press restart.
14. The new TVM is now running in the Kiosk mode on Chrome!

Set up chrome profile

1. On the windows button in the task bar right click, then “ run”, on the opening pop-up write “shell:startup”, then “ok”

2. This command open the startup folder for the kiok user , (C:\Users\....\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup), paste the Chrome link inside

3. Close the tvm‘s screen, right click on the chrome tvm shorcut copy, the, paste it in the start menu you just opened. Close it

4. Go to parameters > Accounts > Login options (Sign-in options) > Privacy > deactivate “use my login details”.

Optional - Automatic Switch off

1. Go to Control Panel > Administrative Tools > Task Scheduler

2. 

2. Create task on the right menu and name it

3. Go to triggers, schedule your task, here daily 8 pm from today. 

Actions > Start a program

Shutdown /s = automatic switch off (like BDC)

Shutdown /r = automatic reboot (like ONP)

4. Check your scheduled task in task library

TroubleShooting the TVM

• TVM is not starting on expected page: check point 4/5 and 11. Note that there may be a .bat file that automatically start the TVM. It should be fixed, too.

• The device drivers does not start (no red icon in the tray bar):
  • if the device drivers is started by the .bat file, ensure that

• • • the path located in the file is correct
    • the path must be within quotation mark, like "C:\Program Files(x86)\..." . Otherwise, the space will confuse Windows.
  • Disk full: 
    • stop the device drivers (there is a stop script in C:\Program Files (x86)\secutix\devicedrivers-manager)
    • delete the java folder C:\users\<user>\secutix\java  (or other directories that consume space on the drive, could be related to C:\Windows\Logs\CBS in case of frequent reboots)
    • reboot
    • Accept the startup of the device drivers (select the "remember" option)
    • Wait until device driver is started
• Tickets are not printed
  • COMM_0040 errors in the device manager logs : Check that the flag "enable bidirectional support" is checked on the printer configuration
  •