Projects:Copy Retail Store and Terminal
Copy Retail Store and Terminal is an optional free commercial module that can be installed on top of Openbravo for Retail distribution starting from RR14Q2.
Overview
It provides an easy way to:
- Create a new Store based on an existing one if the target organization parameter is empty.
- Copy data from a source Organization to an already created Organization if the target organization parameter is set.
- Create a new POS Terminal based on an existing one.
Copy Store
The process is named Copy Retail Store. It can be opened from the Quick Launch 
icon.
Defaults Configuration
Some of the default values required during the Copy Store process are defined in the Copy Store Parameterization window.
Further explanation on what they are used for can be found in Terminal Type and Terminal Type - Payment Method sections.
Process Execution
After filling the parameters and clicking on the Done button the process is executed.
Here is a description of the different steps it does.
Default behavior
This process copies several entities from existent ones. The default behavior during the copy is:
- Try to copy property from the original entity to the new one
- If the original property references to another entity that is not in the new tree of organizations, it is set as blank, in case it is mandatory the process fails
- If the property has a tag, the tag is replaced for the value it refers to. The list of currently available tags is the next one:
- [ORG_SEARCHKEY] - It is replaced by the new/target organization searchkey.
- [ORG_NAME] - It is replaced by the new/target organization name.
- [ORG_SEARCHKEY4DIGIT] - It is replaced by the last 4 digits of the new/target organization search key.
This default behavior is overwritten by the process for some specific properties. Note it is also possible to extend this process through external modules to define different behavior for any property.
Copy Store (Organization)
The Store selected in Store To Copy parameter is copied to a new one.
The properties with different behavior than the standard one are:
- Search Key: the value is directly copied from Search Key parameter
- Name: the value is directly copied from Name parameter.
- Currency: in case the Currency parameter is set, that will value will be used in the new Store; if it is not set, the same currency the original Store had will be used in the new one.
- Location/Address: it will be set based on all the Location parameters.
- Warehouse: a new warehouse with 1 bin is created for the new Store.
- Price List: the one defined in Price List section is used.
- Assortment: the one defined in Assortment section is used.
- Anonymous Customer: the one defined in Anonymous Customer section is used.
- Default BP Category for BPs: the same category as the selected Anonymous Customer.
- Default BP County for BPs: taken from Country parameter.
- All Templates in Web POS Formats section are set for the new store.
Price List
In case Price List parameter is set, it will be used for the new Store. If not, a new one will be created with these values:
 | Note when a new Price List is created, it only contains header but not any version nor products. |
- Organization: it will be in the new Store/Organization.
- Name: its default name will be
"New Store Search Key - Sales Price List". - Currency: if the Currency Parameter is set, it will be used. If not, the same currency that the original Store's price list had will be set.
The rest of parameters are copied from the Price List linked from the Store to Copy.
Assortment
The assortment used in the new store can be defined by the Assortment parameter. If it is not defined, a new one will be created.
| | Note the new Assortment will not contain any product by default |
Its properties will be:
- Organization: it will be in the new Store/Organization.
- Name:
"New Store Search Key - Assortment".
Anonymous Customer
In case the Anonymous Customer parameter is not blank, it will be used. Other case, a new one will be created based on original store's anonymous customer with the following properties:
- Organization: it will be in the new Store/Organization
- Name and Search Key:
"New Store Search Key - Anonymous Customer". - Business Partner Category: it will be taken from Business Partner Category parameter. Note this parameter is mandatory is Anonymous Customer parameter blank.
- Location: a new location will be created for the the Anonymous Customer based on Location parameters. Note that even Anonymous Customer parameter this new location will be added to the selected Business Partner.
Warehouse
A new warehouse with a single bin is created and assigned to the new store.
Financial Accounts
All Financial Accounts defined in original store are copied to the new one
The properties with exceptional behavior are:
- Currency: in case the Currency parameter is set, that value will be used in the new Financial Account; if it is not set, the same currency the original Financial Account has will be used in the new one.
- Description: blank.
- Location/Address: blank.
- Business Partner: The business partner related to the original financial account.
- Initial Balance: 0.
- Bank Account fields: blank.
Payment Methods
All Payment Methods in the original Financial Accounts are copied to the new ones.
Cash Management Events
All Cash Management Event in the original store are copied to the new one.
With the following values:
- Currency: in case the Currency parameter is set, that value will be used in the new Cash Management Event; if it is not set, the same currency the original Cash Management Event has will be used in the new one.
- Payment Method: if the original one is in the new store's organization tree, it is reused; if not, the corresponding one created for the Financial Account copy will be used.
- Financial Account: Use the one created as a copy from the original one.
POS Terminal
There are two ways to copy terminals:
- File: Terminals can be copied from a file.
- Default process: All the terminals present in the original store are copied to the new one.
The following fields are filled for the default process.
- Search Key: It looks if the original terminal search key looks like
[abc]-[xyz]where there are 2 strings sparated by an hyphen (-). If this is the case [abc] is replaced with the Search Key parameter and -[xyz] is preserved in the new one. When the original search key has not this format the new search key will beSearchKey-[uvw]where [uvw] is a sequence number starting with 001. - Name': The same value as the generated search key.
- Order Document No Prefix: The same value as the generated search key.
- Order Quotation No Prefix: The same value as the generated search key appended with
QT. - Hardware URL: blank.
- Scale URL: blank.
POS Terminal - Payment Type
All payment types in the original POS Terminals are copied to the new ones
- Financial Account: using the one previously copied.
- Payment Method: using the one previously copied.
- Cash Up Event: using the one previously copied.
Terminal Type
Default values used to perform this part of the process are defined in Copy Store Parameterization window.
When copying terminal, the terminal type is reused in case the original one is also in the new store's organization tree; if it is not a new one is created as a copy of the original one.
- Document Type: if the original one is in the new store's organization tree, it is reused; if not Document Type defined in the selected Defaults parameter is used.
- Document Type for Returns: if the original one is in the new store's organization tree, it is reused; if not Document type for Returns defined in the selected Defaults parameter is used.
- Document Type for Reconciliations: if the original one is in the new store's organization tree, it is reused; if not Document type for Reconciliations defined in the selected Defaults parameter is used.
Terminal Type - Payment Method
- Payment Method: the one copied in Payment Method step is used.
- Currency: in case the Currency parameter is set, that value will be used; if it is not set, the same currency the original Payment Method has will be used in the new one.
- Document Type: if the original one is in the new store's organization tree, it is reused; if not Payment Method Document Type defined in the selected Defaults parameter is used.
- G/L Item for Writeoff: if the original one is in the new store's organization tree, it is reused; if not G/L Item for Writeoff defined in the selected Defaults parameter is used.
- Cash Differences: if the original one is in the new store's organization tree, it is reused; if not Cash Differences defined in the selected Defaults parameter is used.
- G/L Item for Withdrawals: if the original one is in the new store's organization tree, it is reused; if not G/L Item for Withdrawals defined in the selected Defaults parameter is used.
- G/L Item for Deposits: if the original one is set and it is in the new store's organization tree, it is reused; if not G/L Item for Deposits defined in the selected Defaults parameter is used.
- G/L Item for Cash Drop/Deposit: if the original one is set and it is in the new store's organization tree, it is reused; if not G/L Item for Cash Drop/Deposit defined in the selected Defaults parameter is used.
Access
Access to new store is granted to all Automatic Roles.
Additionally roles with only access to original Store are copied but they are not assigned to any user.
Copy from file
Some of the parameters (POS Terminal, User, User Roles) can be generated from a file instead of take the data from the store to copy.
The file should be upload in the new field added on Copy Retail Store process definition. Mandatory fields for Openbravo will be mandatory too on the file.
For each column it is searched for Column Handlers to be executed. If there are more than one handler it will be executed the handler with the lowest priority. In case that a column has not any handler, the process will notify with an information log and it will only be processed by a generic handler if:
- The property related to the column is primitive
- The property is not mandatory or the field value is not empty
Excel file
To copy an organization from an excel file it is needed the following module:
- Copy Store Support for Excel: https://gitlab.com/openbravo/product/pmods/org.openbravo.retail.copystore.excel
The file is formed by sheets. The sheets have columns to be processed. The column names have filled in the first row of the excel file. The column names that they have not a specific implementation, are made by the Column Name DB or the Property Name. However, if no specific implementation exists for a column, the name for this column can be different.
Implemented sheets must be defined on 'Copy Store Configuration' window as system admin. Implemented sheets for excel files are:
- Store Header Information
- Store Additional Information
- Terminals
- Users
- User Roles
- User Terminals
- Backup Printers
- Safe Box
- Role Inheritance
It is important the order of the sheets for the correct functionality of the process. As they are defined above is the best order of the sheets.
POS Terminal
In order to copy POS terminals from an excel file, it is needed to create a new record in Copy Store Configuration Window as system admin with the following data:
- Module: Copy Store Support for Excel
- Name: Terminals
- Search Key: POSTerminals
For each POS terminal added into the Terminals sheet, it should be at least defined:
- Terminal Type: name of the original terminal type that will be based the new POS Terminal. It is checked if the value filled exists on Openbravo ERP.
- searchKey
- name
- orderdocnoPrefix: Order document prefix
- Default tab (Browse, Scan or Search): name of the default tab for the Web POS. It is checked if the value filled exists on Openbravo ERP.
The POS Terminal Process will copy each column in its respective openbravo column for each terminal. Also, it will copy all payments types related to the original POS Terminal as the default process. In case there are more than one POS Terminal with the same terminal type in the store copied, it will get the first result.
User
In order to copy the users from an excel, it is needed to create a new configuration in Copy store Configuration window as system admin with the following data:
- Module: Copy Store Support for Excel
- Name: Users
- Search Key: Users
The following columns will be at least defined and will be filled for each user on Users sheet:
- firstname
- lastName
- username
- Password
- Default language: An existing code language. Ex: en_US
User Role
In order to assign roles to a user from an excel, it is needed to create a new record in Copy store Configuration window as system admin with the following data:
- Module: Copy Store Support for Excel
- Name: User Roles
- Search Key: UserRoles
User Roles will be the sheet where will be at least defined the columns with the users and roles related to the previous users:
- Username
- Role
It is mandatory for each row that both columns exist to process it.
User Terminal
In order to assign terminal access to a user from an excel, it is needed to create a new record on Copy store Configuration window as system admin with the following data:
- Module: Copy Store Support for Excel
- Name: User Terminals
- Search Key: UserTerminals
The columns defined at least in User Terminals sheet for each user should be:
- Username
- Terminal
It is mandatory for each row that both columns exist to process it.
Hardware Manager
In order to copy the Hardware Managers from an excel, it is needed to create a new configuration on Copy store Configuration window as system admin with the following data:
- Module: Copy Store Support for Excel
- Name: Backup Printers
- Search Key: BackupPrinters
All hardware managers it is wanted to create for the new store should be on Backup Printers sheet. The following columns should be at least defined:
- name
- Terminal Type: name of the terminal type that will be based the new hardware manager.
Backup Printers Process creates first a new Hardware Manager for the new organization. Once it is created, it will be assigned to the terminal type specified. In case there are more than one terminal type with the same name it is chosen the first.
Safe Box
For each Safe Box we want to create, we must provide an existing Safe Box to use as a reference to copy its Payment Methods and Financial Accounts. The searchKey of this reference SafeBox should be in the 'Safe Box to copy' column.
Also, Safe Boxes are linked to a User whose username is provided in the 'User for Safe Box' column.
Org access
In order to assign organizations to a role from an excel, it is needed to create a new configuration on Copy store Configuration window as system admin with the following data:
- Module: Copy Store Support for Excel
- Name: Role Inheritance
- Search Key: RoleInheritance
The columns defined at least in Role Inheritance sheet for each user should be:
- name: name of the rol.
The new organization created will be assigned to the specified role. Only manual roles should be defined, since the automatic ones will be given access automatically.
Copy Terminal
Copy Terminal process is executed from POS Terminal window.
To execute it, select the terminal to copy, and click on the Copy Terminal button.
The process creates a new terminal based on the selected terminal it works in the same way POS Terminal copy in Copy Store process.
Extending/Modifying the Process
The logic applied to implement both processes have been implemented by extension of the copy entities process
| | Further information about how to implement a copy entity process can be found on Developers Guide for Copy Entity Process document. |
Developers can extend and/or modify logic executed by these 2 processes.
Also it is possible to extend the functionality to copy from a file.
Sections defined should implement a Tab Handler. There maybe more than one handler implementing one section. In this case, it is executed the handler with the lowest priority. For each Tab Handler it is needed to overwrite two methods:
- initializeRow(CopyStoreRecord) : Method to initialize the original and the new object it will be processed.
- postProcessRow(CopyStoreRecord) : This method is executed after processed the record.
For each Column Handler it is needed to overwrite two methods:
- processColumn(copyStoreProcess, CopyStoreField, origObject, newObject) : Method to process the field.
- validateColumn(CopyStoreField, copyStoreProcess) : Method to validate the field.
Further information about how to do it can be found in Developers Guide for Copy Retail Store and Terminal document.
Modules extending/modifying the process
The following published modules extend or modify the original process:
- Digital coupons: https://gitlab.com/openbravo/product/pmods/org.openbravo.retail.copystore.digitalcoupons
- The module copies the financial accounts related to issuing companies.
- Depends on module: Digital Coupons for Retail.
- Picking List: https://code.openbravo.com/erp/pmods/org.openbravo.retail.copystore.pickinglist
- The module copies document types for picking.
- Depends on module: Warehouse Picking List.
- Customer Sequence: https://gitlab.com/obcustomers/BUT/org.openbravo.retail.copystore.retailconfig.customersequence
- The module copies the sequence defined in Organization to be used for business partner search key.
- Depends on module: Retail Configuration.
- Pos2 info: https://gitlab.com/openbravo/product/pmods/org.openbravo.pos2.copystore
- The module copies data related to pos2 system like: schemas, modifiers, pick up points...
- Depends on modules: Copy Retail Store and Openbravo WebPOS2.