[toc]

0. General information about this system

0.1. R-Keeper CRM is the software package designed to automate Customer Relation Management.

0.1.1. Previously named as CardSystem5, this software package got the best functionality from PersonalCards software.

0.2. R-Keeper CRM has got interface for external systems (like RK7) to exchange information with its DB.

0.2.1. Exchange could go 2 way: get data from CRM and save/change data in CRM DB.

0.2.2. One additional example of specific data exchange is transaction (account charge or write-off).

0.2.3. For example, Delivery system can save references to CRM (customers, streets, etc.).

0.3. There is client-server application relation.

1. Description of files and folders

1.1. Distributive

1.1.1. Where to get

1.1.1.1. Download CRM from ftp://ftp.ucs.ru/Foreigns/R-Keeper_CRM/ folder   (deprecated CardSystem5 from ftp://ftpint.ucs.ru/dealers/Foreigns/CardSystem.ENG/ or /dealers/R-Keeper.CRM/versions/ folder). We recommend you take the latest version package.
1.1.1.1. Download FarCards5 from ftp://ftpint.ucs.ru/dealers/r-keeper/versions/PERSCARD/FARCARDS/ folder. Take the latest version.

1.1.2. General folders description

1.1.2.1. \BIN\ - contains main executive files of the system
1.1.2.2. \CONFIG\ - configuration files of the system (see 1.1.4)
1.1.2.3. \DATABASE\ - clean databases and scripts for creating them

1.1.2.4. \DRIVERS\ - key driver, additions to Firebird (required for install)

1.1.2.5. \Logs\ - all CS5 application logs are stored here (is created automatically)
1.1.2.6. \PascalScripts\ - contains examples of scripts. These scripts serve for modification and management of the system properties depending on users needs. Not used for basic installation. Working models are presented. On basis of them you can create your own scripts depending on tasks set

1.1.2.7. \Install\ - folder contains additional software that should be installed as shown below (optional)

1.1.3. BIN folder

CS_Server.exe - cards server
Cards_Editor.exe - cards editor
CS_Auth_Server.exe - external requests processing server
CS_Monitor.exe - automatic operations server. By example, transfer card to another level of discount when reaching threshold sum of spent money
Configurator.exe - utility for configuring connection of application servers to the database and client modules to application servers. Data entered here are recorded to the file Config.xml
CS_DataProvider.exe - datasource for reports. Executes queries to the database. Start it once to make record to the DCOM policies. Then it will be started automatically when reports building
RU_Server.exe - server of User and Reports manager applications
Reports_Manager.exe - reports module
User_Manager.exe - user management. Creating of user accounts, setting rights, roles and passwords
Users_And_Reports_Upgrader.exe - make record to the database about Reports and User manager versions

Farcards.exe - transmitter-server. Required for connection with R-Keeper cash server

1.1.4. CONFIG folder

1.1.4.1. Config.xml file contains settings made with Configurator.exe application (see 2.1.6).

1.2. Windows scripts for starting some applications (instead of *.bat files)

1.2.1. Files

Application_Start_Auth_Server.js – script for starting Cards authorization server
Application_Start_FarCards.js – script for starting FarCards
Application_Start_Monitor.js – script for starting Automatic operations server

1.2.2. Text of scripts

1.3. Brief description of libraries

1.4. Terminology

1.4.1. Multi-accounting is used in transactions, that's why you set subaccounts. Subaccount is the RK7 propery of object (currency), what sets this object transaction to be not abstract and have corresponding account in RKCRM.

1.5. Translation of CRM software package

1.5.1. Most of RKCRM applications except Editor have to be translated using .exe file resource edition.

1.5.2. Cards_Editor supports multi-language mode using translation files like "Cards_Editor.Eng" (Langer non-unicode to be used for versions before 05.07, LangUN unicode to be used for CRM modern versions) similar to RK7 ones.

1.5.3. You need to translate the following files in folders \Database\ and \Bin\ (example of 05.07.18.03 version):

1.5.3.1. In \Database\ folder you translate scripts using any text editor (do not change encoding!): Rights_Reports_ENG.xml, Rights_Cards_ENG.xml, step 2.xml.

1.5.3.2. In \Bin\ folder you need to translate .exe files and .dll files and .ENG files. "iod_"* are device drivers. "csa_"* are actions.

1.5.3.2.1. in \Bin\Reports\ folder translate all .xml files.

1.5.3.2.2. In \Bin\Filters.dll\ translate .dll also.

2. Installation

!ATTENTION! CardSystem v.5 use protection system that infect protected files by special way. Almost all antivirus software detects these files as infected. When installation it needs to add CardSystem v.5 files to the exceptions of antivirus systems! (necessarily *.exe files, database files and GrdVkc32.dll)

2.1. Server side

2.1.1. Database management system

2.1.1.1. Check that Firebird is installed properly (CardSystem 05.05 for older versions) or MSSQLS 2012 or newer installed (versions CRM 05.05 and newer), or install the DBMS server now.

2.1.2. Protection key driver

2.1.2.1. Install license Guardant key driver of version not lower than 5.50.85 (not included in distributive - take from official source).

Make sure that this Guardant key you got from UCS is with preset CardSystem5 license in it (and put license key into computer and make installation of new hardware if necessary).

2.1.3. dbExpress

You need dbExprees driver for SQL server (data provider).

2.1.3.1 Install update for Firebird - dbxida270.exe (included in distributive).

2.1.3.2. Install or update for MSSQLS - dbxsda63.exe (included in distributive).

2.1.4. Install additional modules

2.1.4.1. Copy libraries dbexpint.dll, borlndmm.dll to folder system32 (SysWOW64), also it needs to register midas.dll. /deprecated

2.1.4.2. Install midas.dll

Everything can be done by running ‘install MIDAS.bat’ or 'install Midas (x64).bat'.

Text of ‘install MIDAS.bat’ for your own creating:

In case of x64 OS you have to use "%WINDIR%\SysWOW64\" folder, but regsvr32.exe and x32 midas.dll also.

2.1.4.3. Install borland socket server

you can use script from distrib "Install\System\install Socket Server (x64).bat".

2.1.5. Database

2.1.5.1. It’s recommended to CREATE database, not to use clean from distributive (if happened to be there, old versions).

2.1.5.2. For database creating execute two (three for old versions) scripts from distributive sequentially. Scripts are sequence of steps.

2.1.5.3. Before executing it needs to check paths to database folder in the script file beginning (header). You may set any path and DB name which you need. Make sure that DB path you set has write permissions for SQL server user.

2.1.5.3.1. Firebird

2.1.5.3.1.1. Steps:

Script 1: "Step 1 - CardsSystem 5.00 (Metadata) [FB SQL 3].sql" – creating of card system objects
Script 2: "Step 2 - CardsSystem 5.00 (Metadata) [FB SQL 3].sql" – creating of users and reports objects
Script 3: "Step 3 - CardsSystem 5.00 (Data) [FB SQL 3].sql" – data for starting the system

2.1.5.3.1.2. Scripts can be executed by several ways. By example, run fb_isql.bat from the command line with name of executed script. (Text fb_isql.bat: "C:\Program Files\Firebird\Firebird_2_1\bin\isql.exe" -input %1 -output %2 %3 %4). If Firebird was installed to not default folder change path in fb_isql.bat

Examples of running fb_isql.bat:
1.    fb_isql.bat "Step 1 - CardsSystem 5.00 (Metadata) [FB SQL 3].sql" result
2.    fb_isql.bat "Step 2 - CardsSystem 5.00 (Metadata) [FB SQL 3].sql" result
3.    fb_isql.bat "Step 3 - CardsSystem 5.00 (Data) [FB SQL 3].sql" result

IB_Expert utility can be used

Open IB_Expert. Tools > ScriptExecutive



Load from File

 

Choose script

 

Open and check DB path
 


Execute script

2.1.5.3.2. MSSQLS

2.1.5.3.2.1. Use Management studio or other way to execute two scpipts-steps.

2.1.5.3.2.2. Editable variables in DB creation sript for modern versions must be set like:

2.1.5.3.3. In result of successful scripts executing clean database will be created. It has some preset objects. You can find it by path specified in the header of scripts.

2.1.6. CRM Configurator

2.1.6.1. Then run Configurator.exe and configure section ‘Card system’.

Configurator.exe is the main setup GUI for CRM package applications.

 

For connection via DCOM it’s enough to fill configuration fields correctly
For connection via TCP/IP it’s necessary Borland Socket Server started on the SERVER

To check DB connection press button [Test Connect]. If connection is successful you didn’t get any message, but configurations (dropdown lists) on the bookmark ‘Monitor’ became accessible. If connection problems system give message like ‘Connection failed’

Then it needs to fill other sections in Configurator by similar way:

 

!When configure parameters in section ‘Users authorization’ it needs to choose ‘Local’:



If choose ‘Global’



setting of rights will be impossible because it needs for primary configuration of rights in database. See description lower.

2.1.7. CRM CS_DataProvider

2.1.7.1. You need to register this server in windows using

2.1.8. CRM RU_Server

2.1.8.1. You need to register this server in windows using

2.1.9. CRM CS_Auth_Server

2.1.9.1. You have to install CS_Auth_Server as windows service using

2.1.9.2. You can also start this server as desktop application using parameter "/desktop".

2.1.9.3. CS_Auth_Server is the main server in CRM system that holds DB connection and accepts client connections to provide interfaces.

2.1.10. CRM CS_Monitor

2.1.10.1. You have to install CS_Monitor as windows service using

2.2. Card Editor

2.2.1. To install  to another PC you need only 4 folders

and only 4 files in \Bin\ folder

2.2.2. Start Configurator.exe and set in TCP/IP section server address and port (socket server one).

2.2.3. Install midas.dll.
2.2.4. Install borland socket server on CardSystem5 server (if not yet installed) and start it.
2.2.5. Start Cards_Editor.exe and login.

2.3. External connections

2.3.1. CS_Auth_Server , CS_DataProvider and scktsrvr applications (may be found in CS5 distributibe) are used to connect to CS5 DB from external systems (like FarCards or Delivery) and over the network from Cards_Editor.

2.3.2. Borland socket server should be installed with .bat file from the CS5 distributive (\Install\System\ folder). It is going to listen port 211 by default, which you have to set in Configurator.exe as shown in 2.2.2.

3. Licensing

3.1. Principles

3.1.1. Key for CardSystemV5 is prepared and programmed detached from other keys.

If key is programmed you cannot reprogram it for other system! Also impossible reprogram it for CardSystem V4.x

3.1.2. When preparing of the key in UCS HeadOffice, set maximum quatity of cards in database and connections from Editors and connections from other software (like RK7).

3.1.3. Information on license of the installed system can be looked on the bookmark [Licenses] in Cs_Server (CS_Auth_Server) program running as "desktop".

 

!It’s recommended all operations associated with licensing make without other keys put, with only Card System key. Take out other keys from computer temporary

3.1.4. Key driver ver. 05.50.85 must be used (included in distributive). With lower version drivers it will not work!

3.2. Steps

3.2.1. First, get specially prepared Guardant key from UCS

3.2.2. Plug key and run Configurator

3.2.3. Find key in drop-down list as shown by the decimal number (copy number from the list)
3.2.4. To get prolongation code send to UCS the number of protection key. It can be looked in Configurator.exe in the section ‘Card system’ (key number)

 
3.2.5. Get  Prolongation code from UCS licensing .

3.2.6. Open CS_Server program (CS_Auth_Server) on the tab ‘Licenses’.

3.2.7. Copy license code to ‘License prolongation’ field (it can be opened by ‘Prolong’ button). Save.

 

4. Setting rights for working with system. UserManager application

4.1. Import rights

4.1.1. !By default in the clean database there are no any user rights and ability to choose them. To get this ability it needs to make import of pre-defined rights from files included in distributive. This is Rights_Cards and Rights_Reports in the DATABASE folder!
4.1.2. Preset username is "Administrator" and password is "1".

4.1.3. Run User_Manager.exe. Press ‘Rights’ button. Then choose ‘Rights import’ from right click menu.
 

Then import rights from files Rights_Cards and Rights_Reports consequently (.xml files).

After that in the system default rights will be available with ability to edit them

 

4.2. Setup rights

4.2.1. You have to set any necessary rights to any user(s) or role(s).
4.2.2. Do not set "Prohibit editing" or "Viewing only" for Administrator!

4.2.3. Only after assigning proper rights, you will be able to use Editor for references configuration.

5. Connection with R-Keeper

5.1. R-Keeper v6

For connection with R-Keeper v6 use Farcards retransmitter. Farcards must be configured for working in mode 1 (using of external DLL). As external DLL CardSystem5.dll is used.

Example of ini-file (FARCARDS.INI):

In the section [Card System5] we edit only path to the database and parameter ‘Qualifier = 10’ (any number)

‘Qualifier’ parameter is ‘Software classifier’. This number it needs to set in ‘Cards editor’

5.2. R-keeper v7

5.2.1. FARCARDS

5.2.1.1. Settings for R-Keeper v7 use the same logic as for R-Keeper v6, but you have to set several specific parameters additionally.
5.2.1.1.1. See example farcards.ini configuration below.

5.2.1.1.2. Connection changed from DB to CS Auth Server since CS5.05 (in [Card System 5] section the following parameters were removed: DB_Type = Firebird; DB_Name = 198.154.196.80:C:\DB\CARDSYSTEM503.FDB; DB_User = SYSDBA; DB_Password = masterkey; Prog Name = RKeeper; Summ_Format = 0.00; DopInfo_Prefix = Inactive bonuses).

5.2.1.1.3. You may set code substitution in this settings file as shown below if necessary. It always have to be set like: CS (what comes from R-Keeper CRM) = RK7 (what is sent to R-Keeper 7).

5.2.1.1.4. You have to set network DLL names in [LinkDLL] section (make sure that corresponding files exist in current folder). Each external DLL settings have to be put to the section named the same as file and link (for example, [RTcp] and [pds_netk]).

5.2.1.1.5. It is possible to switch on additional logs for pds_netk.dll adding "DebugMessages=1" parameter to [pds_netk] section.

5.2.1.1.6. [Card System 5] section has parameters for CardSystem5.dll settings: CS_Auth_Server "Address=" (IP) and "Port=" are main two for connection.

5.2.1.1.7. [Card System 5] section "HasCredit=" parameter enables (=1) or disables (=0) account credit limit usage.

5.2.1.1.8. In [Card System 5] section "CardActivation_Discount=" parameter value you have to set RK7 discount or markup (which is used on not active card activation) code.

5.2.1.1.9. In [Card System 5] section "CardActivation_Transaction=" parameter value you have to set RK7 discount or markup (which is used on not active card activation) transaction code.

5.2.1.1.10. In [Card System 5] section "CardActivation_SubAccount=" parameter value you have to set CS5 subaccout (which is used for transaction on card activation, if any non-zero amount is set in discount or markup) code .

5.2.1.2. Summ, Discount and Pay are obligatory account types. AccountType_ID is a last numer from Account type "Number" property as shown below.

It could be put to [AccountType_IDs] section for code substitution (Summ=3; Discount=5; Pay=4; Summ2=2 - parameters are account names). /deprecated

5.2.1.3. TransactionType_ID is corresponding account transaction code from account "Transactions" property as shown above. There are income and expenditure transactions as usually, both could be positive and negative charges.
The ini file string format is "CS5 external code"="external application external code".

It could be put to [TransactionType_IDs] section for code substitution (22=122; 21=121; 32=132; 31=131; 42=142; 41=141 - parameters are transaction codes). /deprecated

5.2.1.4. Scheme_ID is a scheme external code from "Schemes" as shown below. Fill in all scheme codes to ini file. The ini file string format is "CS5 external code"="external application external code".

It could be put to [Scheme_IDs] section for code substitution (1=01; 2=02; 3=03; 4=04; 5=05; 77=77 - parameters are scheme codes). /deprecated

5.2.1.5. Copy all necessary DLL files from RK7 distributive.

5.2.1.6. When started as "/desktop" this software shows network modules status (RNBOpen protocol is not necessary in RK7 case):

5.2.2. CS5 manager

5.2.2.1. Fill as many references as necessary, but those mentioned in 5.2.1. are obligatory.

5.2.2.2. Mind that you have only 8 subaccounts in FarCards.

5.2.3. RK7 manager

5.2.3.1. For connection with RK7 cash server you have to configure PDS interface first

(set Netbios name of FARCARDS in "Options" section "PDS server name" property the same as farcards.ini [pds_netk] section "NetServerName=" parameter).

5.2.3.2. You have also set transaction and subaccount codes in RK7 manager 'Currencies' reference -> 'Currency type' -> 'Currency'. They have corresponding 'Priority' settings in RKCRM as shown below.

5.2.3.3. Subaccount 1 has Transaction 101, 2 - 102 and so on. Maximum Subaccount 8 with Transaction 108. In RKCRM you assign subaccount by setting corresponding 'Priority' (see table below).

5.2.3.3.1. So, if you want data (amounts, operation types) for some currency to be recorded on some 'debit' account, you have to add this account to 'account types' with priority = 200 (for example), and set in RK7 currency: subaccount=2, transaction=102 (see below).
5.2.3.4. In Cards_Editor.exe you have to set Software classifier for RK7 and set the same "Code" as [Card System 5] section "Qualifier =" parameter value in farcards.ini.

5.2.3.5. You are also set "Settings" -> "Account types" for RK7 transactions (create new) to use Software classifier from 5.2.4.

5.2.3.6. Fill in all necessary Account types (both for Charging and Write-off) in 'Software classifiers' reference in Cards_Editor application with corresponding priorities (100 to 899).

5.2.3.7. Do not forget to assign driver(s) to logical interface and set proper accounts to be shown in its "Format of the maximum payment" property.

5.2.4. Modes

5.2.4.1. Enable card activation from RK7

5.2.4.1.1. Set some new undistributable markup in RK7 with only one zero amount detail

5.2.4.1.2. Set farcards.ini to enable card activation

where:

CardActivation_Discount - RK7 markup code;

CardActivation_Transaction - transaction code set in RK7 for that markup;

CardActivation_SubAccount - SubAccount code (from 1 to 8), where to put activation money

5.2.4.1.3. Set CS5 scheme with the same markup code as "external code"

5.2.4.2. Make credit available in RK7

5.2.4.2.1. Set "HasCredit=1" parameter in [Card System 5] section of farcards.ini.

5.2.4.3. Assign discounts for cardholders

5.2.4.3.1. Take discount code from RK7 and put it to discount scheme in RKCRM.

5.2.4.3.2. Assign this discount level to discount account type and check RK7-link software classifier enabled for.

5.2.4.3.3. Assign account of mentioned type and level to any user if applied.

6. Troubleshooting

6.1. Log files

6.1.1. There are \Logs\ folder for CardSystem5.
6.1.2. There are CardSystem5.log and Farcards.LOG files.

6.2. How to solve

6.2.1. Send logs to UCS tech support as follows from manual.
6.2.2. Follow 4. of to get proper support.

7. Main settings in Editor

7.1. Reference "System parameters"

7.1.1. Set standard UCS full restaurant code (9 digit), the same as in RK7, to the field "Enterprise code".

8. Coupon or card

8.1. Card

8.1.1. Card ranges

8.2. Coupon

8.2.1. Types:

8.2.1.1. personal and public

8.2.1.1.1. Personal coupons are those assigned to some person(s). Public coupons are not assigned to anybody.

8.2.1.2. amount and percent

8.2.1.2.1. By calculation method coupon can be percent (similar to discount), but the transaction (payment) goes as amount.

8.2.1.2.2. By calculation method coupon can be fixed amount. It can pay part of an order (total is more than coupon), or full order (total is less than coupon or equal).

8.2.2. Properties

8.2.2.1. Code is a coupon unique descriptor or "name" which to be printed (as barcode, etc.), or coupon number.

8.2.2.2. Identifier is a technical unique symbol sequence that allows CRM identify this coupon. Identifier = prefix+code. Code - is unique (last) part of identifier. Prefix made to recognise identifier sequence as coupon, distinguish from card.

8.2.2.3. Prefix = "-922001". The same for all coupons.

8.2.3. In CRM editor you have to set :

8.2.3.1. Coupon types with their properties.

8.2.3.1.1. Assign a scheme to percent or amount. This defines calculation method as well.

8.2.4. In RK7 set algorithm that adds prefix to read coupon code (from input device).