How to use the dll



WinbooksOfficeApi.dll allows using objects, properties and methods to import external records in a WinBooks folder from any other Windows software which is able to address a dll (Visual Basic, Excel, Foxpro,...).
The first step is to prepare the import files with all the records and/or related forms. Then, via the programming interface, we activate the folder and point to the place where the files to import are. Finally, we start the test procedure of the imported files which will be followed by the execution of the import self.

Declaration



In the third party software we add a reference to WinbooksOfficeApi.dll.

When WinbooksOfficeApi.dll is linked to your software, we declare a new object variable and assign a reference to the object WinbooksObject. For example in VBA (Visual Basic for Application) : Dim Wb as new WinbooksObject.


Then we can access to all the methods and properties of the new object: Wb.Import.execute, Wb.Import.Warnings.count, ...

Folder opening



The first task is to connect to the folder where we are going to import the records. It's done through 4 different steps that must be done sequentially as described here under:

1° Initialization

Wb.init()

2° User login :

Wb.login(User name,password,[language]) (étoile)

3° Folder opening

Wb.opendossier(short name)

4° Bookyear opening

Wb.openbookyear(short name of the bookyear)


The initialization must be successful before the user login and the rest of the procedure.
Each of those operations returns an integer. An operation is successful when the returned value is 0 otherwise there was an error during the operation. The following list shows the possible returned values and their significations (charged in the property wb.LastErrorMessage).
The language (F,N) is an optional parameter. By default it's the folder language.

Operation

Value

Meaning

Init

0

Successful initialization


1

The user file is not found (users.dbf)


3

the winbooks.ini file is not found


4The user file is not found in the folder specify in the winbooks.ini file but we found a user file in the folder of the winbooks.exe

Login

0

Successful connection


1

Init has not been done


2

Unable to open the user file (users.dbf)

Opendossier

0

Successful opening


1

The folder name is empty


2

Init has not been done


3

Login has not been done


4

Wrong password


5

Unable to find the folder in the chosen directory


6

A user has exclusive connexion to the folder or unable to open settings file


7

You don't have the API module for this folder


8

Unregistered evaluation version, only Parfilux folder

Openbookyear

0

Successful opening


1

Opendossier has not been done


2

There is no bookyear for this folder


3

Unable to find the current bookyear


4

Unable to open the folder


Except the case of a demonstration version that works without users file, the Init procedure must have access to the users file User.dbf to verify and validate the user's login. The access path to the user.dbf file can be found in the Winbooks.ini file (in the main Winbooks folder by default).
As soon as the opening operations are executed and return good values we can move on to the preparation of the import.
Example : If Wb.init() <> 0 then Msgbox Wb.LastErrorMessage :Exit sub
If Wb.login(« SYSTEM », » ») <>0 then MsgBox Wb.lastErrorMessage : exit sub


Preparation of the import



The preparation has two objectives: to give some information about the files to import and to search for possible conflicts and the way to resolve them.
Format of the import files (optional) : DBF (by default),TXT (text delimited by comma), CSV, SDF (Standard delimited format).
Wb.import.fileformat(« DBF »)=Boolean
A positive value means that the format is valid and understood by WinBooks.
Directory in which the files to import are (mandatory)
wb.import.directory (« directory »)=Boolean
A positive value means that the directory is valid and contains import files with the specified format (.DBF by default).
This directory contains import files: at least the records file ACT.dbf and optionally the ACF.dbf (accounting plan), the CSF.dbf (customer and supplier information), the CURRENCY.dbf (including the currencies and rates), the DBK.dbf (the journals), TABLES.dbf (the codes of tables and their significations), the ZIPCODE.dbf (the added postal codes)



1° The imported files must have the same structure as the target file: If it's an import in the Parfilux folder, the imported ACT.dbf must have the same structure as Parfilux_Act.dbf in the directory of Parfilux.
2° Regarding the content of the field to fill in, it must be the same as the one created by WinBooks during the input of a record: to have an example, encode a sales invoice in Parfilux and look in the ACT how WinBooks writes the record. Several fields don't have to be filled in because it'll be done by WinBooks during the import process.
3° In the optional files we store the information of the customers, suppliers and general accounts, the journals, the currencies, the postal codes and the references of the tables found in the records of the ACT. The information is used to update the corresponding fields in the target folder.
Example n°1 : the invoice of a new customer. If the form of the new customer doesn't exist in the imported CSF.dbf, the only solution will be to refuse the import or to create a customer with an empty form. Otherwise if the form of the new customer is in the imported CSF file, it'll automatically be added to the accounting folder.
Example n°2 : the invoice of an existing customer Dupond whose address has been modified : if the modified form of Dupond is not in the imported CSF then the address can't be changed in the accounting folder.
4° Usually, we import records in a Winbooks folder: the ACT.dbf file is used and we advise filling in the CSF, ACF,... with the form referenced in the sent records. It's not mandatory to fill in the CSF, ACF with unreferenced forms, but if it's the case, the CSF/ACF will be updated.
5° It's also possible to import EXCLUSIVELY form information (new customers, currency rates,...). In this case the ACT.dbf is no imported. The forms will be updated with the data provided in the imported files.
Backup of the folder and of the imported files (optional)
To create a security backup of the accounting files of the target folder and of the imported files, we use this method by optionally specifying a valid path. By default, Winbooks takes the IMPORTBACKUP directory in the folder directory. The imported files are saved in IMPORTEDFILES subdirectory.

wb.import.backup([path])=Boolean
A positive value means that the path is valid and that the backup is well done.
Bookyear by default, (optional) in which the records will be imported, if the field PERIOD in the ACT file is empty. In Winbooks a period has two numbers from 00 (period of report) to 99 (period of closing). If the accounting year matches the civil year, the period will match the month: 03 for march. In the other cases (more than 12 months, shortened bookyear, ...) the number will be the number of the period in the bookyear. Example : if a bookyear begins July 1st, the month july will be 01.
Wb.import.SetDefaultPeriod(« WinbooksPeriod »)=Boolean
A positive value means that the period is valid. The functionWb.Param.GetPeriod ("date") returns the corresponding accounting period to the indicated date. The bookyear is always the one indicated by Wb.Openbookyear .
Import of link files in CPTLINK format of Cubic (optionally). The import of files built for the CPTLINK of Cubic has been achieved. For the moment, only sales journals and customers forms are dealt with.

CPTLINK is only used for belgian legislation folders.


WB.Import.LinkFormat = wbCubic (or 1)

The files CPTJVxx.TMP and CPTSCxx.TMP must be in the directory specified by the directory property (as seen above). WinbooksAPI will create and update the ACT and CSF files. A preprocessing converts the Cubic link files into Winbooks link files. If the property is not defined or if it's defined like this "WB.Import.LinkFormat = wbWinbooks (ou 0)" then the import will be done from files in WinBooks format. Warning, only one CPTJVxx.TMP or CPTSCxx.TMP can be handled at one time.
Validity test of the imported files, mandatory before doing the final import.
Before the import, the program carries out a lot of tests to verify the coherence of the imported files (balanced operations, numbering, structure,...). This operation is going to generate possible conflicts or fatal errors that have to be resolved before doing the import. As long as there are fatal errors or unresolved conflicts the import cannot be done.
Wb.import.test = Boolean
A positive value means that the test is well done (but it doesn't mean the test reports no error). A 0 means that some files were unreadable or that files cannot be opened. By using Wb.LastErrorMessage member, more information can be found.
NB Prior to this test procedure, an additional operation is done: some fields in the ACT are checked in order to complete them. Indeed to make the job easier WinbooksOfficeApi allows importing records where some information is missing. WinbooksOfficeApi will update those fields. Below you'll find the commented structure of the imported files and the inventory of the mandatory fields.

Below, the list of tests and the generated error type:

File

Test

Fatal Error

Warning

ACF

Difference in the structure

X



Difference in the length of the numbers of the accounting plan

X



Difference in the contents of the fields


X


Difference in the associated memo


X

CSF

Difference in the structure

X



Difference in the contents of the fields


X


Difference in the associated memo


X

ACT

Empty period and no default period

X



Existence of strictly identical journals to those in the target file


X


Difference in the structure

X



Records with the same numbers are found in the target file


X


Non-existent VAT code

X



Balanced accounting records

X



Break in the numbering sequence of the records


X


No customer/supplier information in the imported CSF and target file


X


No general account information in the imported ACF and targetfile


X


Journals coherence

X



Forbidden letter

X



Non-existent journal code in the DBK

X


CURRENCY

Different rates between the imported file and the target file


X

DBK

Difference in the content of the fields


X

TABLES

Difference in the content of the fields


X


The test procedure generates conflicts if needed. There are two types of conflicts: the « warnings » and the "fatal errors". The first can be resolved but the second can't.
The import cannot be done if there are still unresolved warnings or fatal errors.
To know how many number of warnings there are: wb.import.warnings.count
To know how many number of fatal errors there are : wb.import.fatalerrors.count
For each warning it's possible to know the error code with wb.import.warnings(index).code. This last property will return an error code. The property param (wb.import.warnings(index).param) gives information on the incriminated record to identify it quickly : customer reference, period, document number,... .
If we want complementary information on the report we can use the Errorcodes collection. By providing the error code we can have the description in return. The property AllowableActions gives solutions to resolve the problem.
Example : wb.import.warnings(1).code returns an error code : « ACC_MISS ». We use the membre errorcode like this to have the description of the warning: wb.import.errorcodes(« ACC_MISS »).description. The solutions to the problem can be provided by wb.import.errorcodes(« ACC_MISS »).allowableactions.
Allowableactions don't exist for fatal errors.
The resolution of conflicts can be done on two levels. The first one is the automatic correction of all conflicts with the same error code. The second is the correction of each conflict individually.
If we want to provide a global solution to repeated warnings, we'll use the Errorcodes member of the object. We specify the error type and assign a solution. WinbooksOfficeApi will enumerate a list of error codes and solutions to offer a friendly interface. The resolution is set with the property SetResolution.
Example 1 : wb.Import.ErrorCodes("ACC_MISS").SetResolution = wbBlankRecord. It means that for all "ACC_MISS" errors the resolution will be wbBlankRecord.
Example 2 : wb.import.ErrorCodes_("DOC_NUM").setresolution=_
WbIgnore: If imported records are already in the target file then we ignore it
WbReplace: The imported records will replace the corresponding records in the target file
WbEraseAll: all the previous records are erased in the target folder for the concerned journal and period.
If we want to give a specific solution to a conflict, we take position with the warnings member on the conflict specified by the index of the item. Then we assign a resolution type with SetResolution.
Example : wb.import.warnings(1).setresolution=wbBlankRecord. To the indexed conflict 1 we assign the resolution wbBlankRecord.
We have to insist on using the good type of solution for the resolution: for each error code, the property AllowableActions gives each time the possible resolutions. WinbooksOfficeApi will not use an incompatible resolution for the error type and will use, by default, the resolve value wbToResolve (still to resolve).
To verify wether a global error or a specific warning has been resolved, we use the property GetResolution. The property will return wbToResolve in case where a global solution can't be found for a specific error or where a specific conflict can't be handled. If a solution has been found, the property will get the type of resolution.
You'll find in annex the list of the error codes generated by the test procedure and their resolution.

The import

If you want to directly import a document while another user is already in the folder, you must used the wb.DirectImport parameter.
Allowed values are "TRUE" => Direct Import, "FALSE" conventional import



Once the coherence test is done and there are no more conflicts, we can launch the execute method to import the files in the target folder.
Wb.Import.Execute = Integer
The import also returns a value to indicate the state of the import.

0

The import is a success

1

The test method has not been done

2

There is still one or several unresolved warnings

3

Unable to import due to one or several fatal errors

4

The conflicts resolution is not up to date regarding the files

5The Importation failed, see LastErrorMessage for more informations


If the import doesn't return the value of a success (0), more details can be found in the member Lasterrormessage of WinbooksOfficeApi.