Some import scenarios cannot be implemented using Excel Import Template settings alone.
In such cases, additional program logic, called a Handler, is required.
A Handler extends the standard Excel Import functionality and allows the system to process imported data according to specific business rules that cannot be configured using standard template settings.
When is a Handler required?
A Handler may be required when the import process needs to:
- search related objects using custom rules;
- populate fields based on business logic;
- create or update related objects using additional business rules that cannot be configured through standard template settings;
- perform calculations during import;
- validate imported values;
- process complex document structures;
- implement company-specific business processes.
Whenever possible, data import should be configured using the standard Excel Import Template functionality. A Handler is required only when the required import behavior cannot be achieved through template configuration.
Standard Import vs. Handler
Importing data into simple master data objects, such as catalogs, is typically a straightforward process.
For example, when importing Employees, each row in the Excel file usually represents one catalog element together with its attributes, such as Full Name, Gender, Date of Birth, and other employee information.
In these scenarios, the standard Excel Import Template is usually sufficient.
However, importing documents often requires additional processing.
Documents may contain references to multiple related objects, validations, calculated values, or business-specific rules that cannot always be resolved using standard template settings alone.
Example
Consider importing an Invoice document.
Before the document can be created, the system must determine values for fields such as Company and Contract.
These fields refer to different system catalogs.
During the import process, the system must:
- identify the Company specified in the Excel file;
- determine the appropriate Contract associated with that Company.
The standard Excel Import functionality searches for the Company using the configured import rules.
If no additional processing is implemented, the Contract specified in the Excel file is not evaluated. Instead, the system automatically assigns the Contract marked as the Main contract for the selected Company.
If a different Contract must be selected during import, additional processing logic must be implemented using a Handler.
Important
A Handler extends the standard import functionality.
It does not replace the Excel Import Template configuration.
Before implementing a Handler, configure the required Main Parameters and Fields of the Excel Import Template. A Handler should only be used for functionality that cannot be achieved using standard template settings.
Note
Depending on the configured Excel Import Template, some related objects can be created using standard functionality (for example, by enabling the Create Objects option where supported).
If the import process requires additional business logic, custom object creation rules, or processing of related data, a custom Handler must be developed.
Before you start configuring the template, ask yourself the following question:
Can my import template be fully described as "take the value from this Excel column and write it into this field in FirstBit"?
If the answer is Yes, a standard Excel import template will most likely be sufficient.
If your requirements include any of the following actions:
if...
otherwise...
find...
calculate...
create...
select...
validate...
transform...
populate automatically...
then your import requires business logic, not just field mapping. In this case, import template is not sufficient, and a custom development will be required.
Rule of thumb: Excel Import Templates without Handlers are designed to map Excel data to FirstBIT fields using configured import rules. If the import process requires additional decisions, calculations, transformations, validations, or automatic actions beyond these settings, a custom Handler is required.
Examples of Requirements That Need a Custom Handler
| Requirement | Example in FirstBIT Software | Can a Standard Excel Import Template Handle It? | Handler Required? |
|---|---|---|---|
| Populate document fields from Excel columns | Import Invoice Number, Date, Entity, Customer, Amount, Currency from Excel columns into corresponding document fields | ✅ Yes | No |
| Find existing master data by configured search criteria | Find Customer by Code, Item by Code, Warehouse by Name according to the configured field mapping | ✅ Yes | No |
| Create new master data elements using supported template settings | Create new Item or Customer while importing data when the Create Object option is available for the selected field | ✅ Yes | No |
| Create related objects with additional rules | Create a new Item with predefined attributes, default values, or additional related information that cannot be configured in the template | ❌ No | Yes |
| Select a non-default related object based on business rules | Assign a Contract different from the Main Contract of the selected Company during Invoice import | ❌ No | Yes |
| Populate fields depending on conditions | If Customer belongs to a specific category, automatically assign a specific Price Type, VAT Group, or other value | ❌ No | Yes |
| Perform calculations during import | Calculate document amounts, discounts, taxes, or other values based on imported data before saving the document | ❌ No | Yes |
| Transform imported values | Convert imported values according to business rules, for example changing external payment terms or categories into FirstBIT values | ❌ No | Yes |
| Search related objects using complex logic | Find a Customer first by TRN, then by Name, then apply additional selection rules | ❌ No | Yes |
| Validate imported data using specific business rules | Prevent import if a Customer is blocked, required information is missing, or imported values do not meet company rules | ❌ No | Yes |
| Create related documents automatically | Create additional documents, such as Delivery Notes or Bank Receipts, based on the imported document | ❌ No | Yes |
| Perform actions after import | Automatically post documents, recalculate data, change statuses, or execute additional processing after import | ❌ No | Yes |
| Validate data before import | Reject the invoice if the Customer is blocked or the TRN is invalid | ❌ No | Yes |
Handlers are implemented by the FirstBit technical team as part of system customization.
If additional import logic is required, please contact your Account Manager or the FirstBit Hotline to discuss the required customization.
Thank you for being FirstBIT customer!