Last version : 2.0 (released the 11th of November 2024)

The 2.0 version needs the user to have the role pos_alerter in order to work properly

The OneStock Alerter is a Windows application to install in store. It opens a pop-up when there are actions to be taken by the store, such as new orders to claim, orders to bag, to pack, etc.

It is different from the notification push that are sent by OneStock, because it is a program running in background, completely independent from your web-browser. The notification push relies on the web-browser to display notifications.

This application must be installed and configured on every computer that will use it. It is recommended to configure Windows to start this application automatically when the computer starts.

1 Technical recommendations
2 Installation
- 2.1 Launch installation in batch mode
- 2.2 File version.info
3 Configuration
- 3.1 Yaml configuration file
  - 3.1.1 Common section (mandatory)
  - 3.1.2 Section API (mandatory)
  - 3.1.3 Section browser (optional)
  - 3.1.4 Section pages (mandatory)
  - 3.1.5 Sample configuration file
- 3.2 Translation file
- 3.3 Icons
4 Monitoring

Technical recommendations

The OneStock Alerter application can be installed on the following versions of Windows : Windows 7, Windows 8.1, Windows 10, Windows 11.

It takes up to 30 MB of RAM and 100 MB of disk space (including 50 MB of rotating logs).

This application includes links to OneStock using the Internet browser. The default browser must therefore be compatible with OneStock.

Installation

The application is provided in the form of an executable that launches the installation of the program in Windows.

The application is installed in a default Windows installation folder:

Installation for all users : C:\Program Files (x86)\OneStock Alerter
Single user installation : C:\Users\{{username}}\AppData\Local\Programs\OneStock Alerter

A shortcut can be added automatically on the user’s desktop.

The application does not launch automatically when Windows starts. If you want it to launch directly, you have to configure it in Windows.

A version.info file is added to the installation directory. It contains the number of the current version of the alert.

Launch installation in batch mode

The installation application can be launched in batch mode, especially for remote installations.

To do this, the installation program must be started in administrator mode, with some of the following options, as required:

/SILENT: the setup window is displayed but does not prompt the user; installation is performed directly and the window closes automatically when the installation is complete.
/VERYSILENT: no window is displayed the installation is done completely in the background. Error messages may be displayed if errors occur.
/FORCECLOSEAPPLICATIONS: this option closes the application if it is running before starting the installation (in case of an upgrade).
/SUPPRESSMSGBOXES: This option allows you to not display error messages if errors occur.
/ALLUSERS: This option indicates that the installation must be done for all users (in the folder C:\Program Files (x86)\OneStock Alerter) and not only for the current logged user.

File `version.info`

The installation creates a version.info file in the installation folder (see the folder above). This is a text file that contains only the version number of the OneStock Alert currently installed, in the form x.x.x, for example "1.0.1".

To ensure that the application has been installed without error, we recommend checking that this file has been created or updated and that it contains the expected version number.

Configuration

Yaml configuration file

A text file config.yaml must be placed in a config folder in the installation folder. This file must be different for each store, since it contains the store code, and the login and password used may differ from store to store.

By default, the installation generates a text file config.yaml.dist. This file serves as a sample configuration to help the person configuring the alert create their config.yaml file. The config.yaml.dist file does not replace the config.yaml file and is not taken into account by the alerter.

The file is divided into sections, each beginning with a line containing the section and no indentation.

It is critical to respect indentation. The indentation is of two spaces per level.

Common section (mandatory)

Parameter	Description	Example

Parameter	Description	Example
`common`	Section Name
`frequency`	Number (integer) of minutes between 2 counter updates in the application Must be greater than or equal to 1	`5`
`exit`	Boolean If `true`, displays an option to exit the application If `false`, there is no option to exit the application (you can just hide the window)	`false`
`datetime_pattern`	String corresponding to the date-time format of the last refresh. %d = day of the month %m = number of the month %Y = year %H = hour %M = minute	`"%d/%m/%Y %H:%M"`
`language`	String corresponding to the display language of the interface. It must correspond to a language in the translation file (see next paragraph).	`"fr"`

Section API (mandatory)

Parameter	Description	Example

Parameter	Description	Example
`api`	Section Name
`url`	URL to access OneStock APIs	`"https://api.onestock-retail.com"`
`vi_url`	Access URL to the OneStock vendor interface	`"https://fashion-market.onestock-retail.com"`
`username`	Login used to access the APIs A different login/password can be used in each store or the same one can be shared.	`"jdoe"`
`password`	Password used to access the APIs	`"Dsj-R56R$R"`
`token`	API token: either use username and password, or token	`"3d4468864a3857c472f8697e299013a8"`
`site_id`	Site ID provided by OneStock (the same for all stores)	`"c000"`
`endpoint_id`	Current store ID. Not to be set if endpoint_query is set.	`"store123"`
`endpoint_query`	Replaces the need of setting the endpoint_id. Allows to retrieve the endpoint_id by a filtering query. Not to be set if endpoint_id is set.	`{"information": {"store_external_number": 1}}`

Section browser (optional)

This section is necessary only if you want to launch a specific web browser when clicking on a counter or if you want to open it with a specific option (such as --kiosk).

Parameter	Description	Example

Parameter	Description	Example
`browser`	Section Name
`command`	Browser executable path	`"C:/Program Files (x86)/Google/Chrome/Application/chrome.exe"`
`params`	Optional params to be passed to the browser at runtime	`"--kiosk"`

Section pages (mandatory)

Parameter	Description	Example

Parameter	Description	Example
`pages`	Section Name
`Level 1`	List of sections. Out of the box sections : sfs (ship from store), ckc (click & collect), ropis (reserve & collect). To add a custom section, simply add it to the configuration and add its translation in the translation file.	`pages:` `sfs:` `claim:` `condition: "_"` `pack:` `condition: "_"` `custom_section:` `custom_page:` `condition: "_"` `path: "url"`
`Level 2`	List of pages to be displayed in the given section. Out of the box pages that can be displayed: claim, pack, pack_scan, dispatch, bag, bag_scan, receive, collect, reserve, carry, picking, sorting, moving, consolidation, boxing, prepare_select Extensions can be displayed: simply add a custom page key, add its translation in the translation file and indicate a path to recover the counters from.
`condition`	String that defines the conditions under which this counter will bring the alert to the foreground: >n with n being an integer (>= 0), as soon as the counter is higher than n > as soon as the counter is higher than its previous value. _ or (empty) never != as soon as the counter has a different value from its previous value < as soon as the counter is lower than its previous value	`pages:` `sfs:` `claim:` `condition: ">0"` `pack:` `condition: "_"` `dispatch:` `condition: ">"` `custom_section:` `custom_page:` `condition: "!="` `path: "url"`
`path`	Custom url to recover counter from. Usually used when configuring extension custom pages.	`pages:` `custom_section:` `custom_page:` `condition: "_"` `path: "url"`
`route`	By default counters redirect to `vi_url + "/" + key`, which in most cases works fine. For example, claim counter redirects to `vi_url/claim`. Nevertheless, a custom route can be configured using the route field, in which case the counter will redirect to `vi_url + "/" + route`. In the example code, custom page will redirect to `vi_url/custom/page`	`pages:` `sfs:` `claim:` `condition: ">0"` `custom_section:` `custom_page:` `condition: "_"` `path: "url"` `route: "custom/page"`

Sample configuration file

common:
  refresh_frequency: 1
  exit_mode: true
  datetime_pattern: "%d/%m/%Y %H:%M:%S"
  language: fr
api:
  url: "https://api.onestock-retail.com"
  vi_url: "https://url.onestock-retail.com"
  token: "3d4468864a3741c483c7807b299013a8"
  site_id: "c00"
  endpoint_id: "main_demo"
  #endpoint_query: {"information": {"numero_magasin": 1}}
browser:
  command: "C:/Program Files (x86)/Google/Chrome/Application/chrome.exe"
  params: "--kiosk"
pages:
  sfs:
    claim:
      condition: ">5"
    pack:
      condition: "_"
    dispatch:
      condition: "_"
  ckc:
    bag:
      condition: ">0"
    receive:
      condition: "_"
    collect:
      condition: "_"
  ropis:
    reserve:
      condition: ">0"
    carry:
      condition: "_"
  custome_section:
    custome_page:
      condition: "_"
      path: "url"
      route: "custom/page"

Translation file

A text file translations.yml is created in a config folder in the installation folder. This file can be modified to change the terms displayed on the screen or to translate the interface into a new language (French and English are included in the default file).

To add a language, simply copy the whole section corresponding to the language "fr" for example and paste it at the end of the file, replacing "fr" by the new language (to which the "language" configuration will refer) and translating each term on the right side.

Icons

To configure a different icon than the one provided, or to add an icon for a custom page, just add a new .png image of 24px x 24px to the img folder and rename it so it matches the page key. For example, claim.png if you would like to change the claim page icon.

Monitoring

An alerter.log file is systematically created and updated in the logs folder in the installation folder when the application is run. It is updated every n minutes, according to the frequency defined in the configuration file.

To ensure that the application runs without errors, it is possible to check if this file exists and has been updated in the last n minutes and that it does not contain an error message.

Errors are indicated in this file with the log level "- ERROR -".

OneStock Alerter