Wello is a SaaS solution used by different types of companies that each have their specific needs. While core entities like `Company`, `Project`, and `Article` come with many standard properties, you often need to store extra information specific to your business, such as a special reference number, a custom date, or a unique text description.
To handle this, Wello provides a system for creating dynamic, Additional Fields. While the technical term within the Wello system is "Additional fields", it's helpful to think of them simply as custom fields you can create and manage.
These fields are presented logically in the user interface, grouped into chapters under the "Extra Info" tab, and support various input types like text boxes, dropdown lists, date pickers, and more.
There are two types of additional fields—Global and Specific—and it's important to understand the distinction
Global Fields
When you create a Global Field for a certain entity, it becomes available for every item of that entity. For example, if you create a chapter called “ERP Fields” and add a field named “ERP Creation Date” that applies to all types of the Project entity, then every project will have this field, each with its own value for “ERP Creation Date”
It is applied to the following entities:
📋 Article
📋 Company
📋 Work Order
📋 Equipment (Location, Project)
📋 User
📋 Task
Specific Fields
These fields are more specialized, as they are associated with a specific type within an entity. They are only visible when that type is selected, ensuring that users see only the fields relevant to their context. Therefore, Specific Fields apply only to entities that have multiple types, with each type requiring a distinct set of fields. Currently, Specific Fields are only supported for Equipment, where additional fields can be configured for each Equipment Type (Equipment Family).
For example, if you create a field named “Cause of Failure” linked to the equipment type “Aircool Maintenance”, then only equipment with the type “Aircool Maintenance” will have the “Cause of Failure” field.
Reports
Additionally, this same system is cleverly used to build Report Templates, serving as a form builder for structured reports such as Visit Reports (Sales) and Job Reports (Service)
Seamless ERP Integration: When connecting an external system like an ERP to Wello, you may have data that doesn't fit into the standard Wello fields. Additional Fields are the perfect solution for synchronizing this information.
Display Read-Only Information: You can set fields as "read-only." This is a great way to display helpful instructions or static data from another system directly within the Wello interface.
The additional fields structure can be divided in 2 parts :
Which tables are used to configure the fields
Global Fields
As you can see above diagram, Global Fields are the udf columns of entity that enabled by linking with db_info_field via column udf_name, that is when a db_info_field.udf_name store a name of an udf column of entity, that UDF column becomes enabled as a Global Field. In short, the values of db_info_field.udf_name represent the column names in the <Real table> (<Real table> could be article, company, jobs, project, task, user )
For example: we have a db_info_field line for 'company' and db_info_field.udf_name = 'udf2' then the value of this db_info_field line is saved to 'real table' (company.udf2). Therefore, to retrieve the value of this db_info_field, you need to access company.udf2
Specific fields & Reports
Db_info_field :
This is the main table that contains the different fields
Global Fields
Db_info_id : Foreign key (FK) to the chapter (Db_info) to which this field belongs
Db_input_type_id : FK to the type of field (e.g. Textbox, TextArea)
Name : name/code of the field
Title : value that will be shown on the User interface
Description : Internal description to help the user
Sequence : numeric value to order the fields within the chapter
Is_readonly : the user is not able to modify the field
Hide_in_view_if_empty : will hide the field if it is not filled after saving (used only for the reports)
udf_name: the column name of the <Real table> (<Real table> could be Article, Company, Jobs, Equipment, Task, User ), if it available
Specific fields & Reports
Db_info_id : Foreign key (FK) to the chapter (Db_info) to which this field belongs
Db_input_type_id : FK to the type of field (e.g. Textbox, TextArea)
Name : name/code of the field
Title : value that will be shown on the User interface
Description : Internal description to help the user
Sequence : numeric value to order the fields within the chapter
Is_readonly : the user is not able to modify the field
Hide_in_view_if_empty : will hide the field if it is not filled after saving (used only for the reports)
Db_info_field_property :
This table contains the different properties of the additional fields. For example if the field is a dropdown list, it will contain all the items of that list.
Db_info_field_id : FK to the field (db_info_field)value : key of the property (store there your ERP PK)Name : Item.text that will be shown in the User InterfaceSequence : numeric value to order the itemsDb_info :
This table contains the chapters.
Name : Name of the chapter that will be shown in the User InterfaceSequence : numeric value to order themParent_id : in case of sub chapterDb_info_category :
Links the field to the entity where additional fields can be used.
Cf chapter of the db_info_category to have the values that can be used.
Db_info_category_list :
Cross table to link the chapters (db_info) and the entity where they have to be shown (db_info_category). In the major case, it’s only 1.
Db_info_data :
Global Fields
The value of a Global Field is stored in the UDF column of the corresponding entity — for example, company.udf2. Please refer to “1) Configuration” for more details.
Specific fields & Reports
Contains the values for specific additional fields linked to a specific object (such as equipment_family), excluding entities like article, company, jobs, project, task, and user.
db_info_field_id : FK to the db_info_field
target_id : the id of the object (like company.id)
db_table_id : FK to the db_table to specify to which table the target_id refers. This field is mandatory because a chapter of additional fields can be shared on multiple entities in specific cases.
value : the value of the field (CF chapter “How values are stored”)
Entity (not actual table) :
Represents one of the tables of the system (like company, jobs or project).
id : the primary key of an entity is always a field called "id"Db_table :
Each table of the system is listed in the table “db_table”.
name : name of the table, like “company”, “jobs” or “project”Because the information needs to be stored in one single column (string type), a conversion between the real type and the string is done:
DateTime : format yyyy-MM-dd HH:mm:ss , Example 2015-02-01 13:45:15 for February 1st 2015 at 13h45m15
Boolean : 0 for false, 1 for true
Decimal : No thousand separator, “.” as decimal separator
Multiple values (in case of a multi select box) : each value separated by a coma “,”
When you are creating chapters, on the fly, using the API, you have to link the chapter to a valid entity of additional fields.
Here are the values can uses
| Tables | Guid | Code |
|---|---|---|
| Article | 62130B5B-6749-48D0-8E2A-A438375DFB06 | Article |
| Company | AAD3C635-7CAB-452A-BA82-B8CB678EB2E7 | Company |
| Contact | 827F60F3-195B-49BD-AA27-67DB40FA32C8 | Contact |
| Equipment Type | 2694CD20-C3AA-4472-985B-945D3A5E53F7 | EquipmentFamily |
| Jobs | CA58E657-8306-4ED5-9444-6119B41DF08E | Jobs |
| Opportunity | 10BAC2B7-61DD-4A86-9037-59E1CB57A17B | Opportunity |
| Project | 0449AE56-BCC4-DF11-B6D9-0030488C6C36 | Project |
| Task | 159269A7-CAC5-49db-823E-4CEF3AE1A126 | Task |
| User | C9B3F4B5-EB54-4F1F-B28C-3C1D5BC90C9D | User |
Currently, the API does not support creating Global Fields because a Global Field must be linked to a UDF column in the entity, which requires complex validation logic. It is not possible to simply set udf_name to an entity’s UDF column in the request. Therefore, if you want to create a Global Field, please use the Portal. For now, we can only create Specific Fields via the API.
Thanks to embedded entities, it’s possible to create an additional fields in one call. Like in the following example
<db_info_field> <name>TESTAPI_COMPANY_TXT1</name> <title>Field added using API</title> <db_input_type_code>TextArea</db_input_type_code> <db_info> <code>TESTAPI_CHAPTER_1</code> <name>Chapter Test API</name> <db_info_category_code>Company</db_info_category_code> </db_info> </db_info_field>
As we can see, we supply a node of db_info (the chapter) and specify that this chapter should belong to the Company InfoFields.
Now, let’s try a more complex field: a combobox with some item values (items in the combobox). Let’s first add the info field
<db_info_field> <name>TESTAPICOMBOBOX</name> <title>my first combobox</title> <db_input_type_code>ComboBox</db_input_type_code> <db_info> <code>TESTAPI_CHAPTER_1</code> <name>Chapter Test API</name> <db_info_category_code>Company</db_info_category_code> </db_info> </db_info_field>
HTTP STATUS 201 (and the id of the db_info_field returned, in this case ‘4877F5AA-011D-4771-99B7-5BA02752E1C5’). Then add 1 item for this combobox using the db_info_field_id received.
<db_info_field_property> <value>TESTAPICMB1_Value1</value> <name>My first value</name> <db_info_field_id>4877F5AA-011D-4771-99B7-5BA02752E1C5</db_info_field_id> </db_info_field_property>
Now, let’s try to add the second value using embedded entities for the db_info_field
<db_info_field_property> <value>TESTAPICMB1_Value2</value> <name>My second value</name> <db_info_field_name>TESTAPICOMBOBOX/db_info_field_name> </db_info_field_property>
Global Fields
Global Fields are UDF columns of an entity, so their values must be updated directly in the corresponding entity table
For example, the db_info_field is linked the column udf2 of entity company via db_info_field.udf_name = ‘udf2', it means <Real table> is company and the additional field value is stored in the udf2 column of the company entity. In this case, you need to call PUT on the Company endpoint to update the additional field value.
Specific fields & Reports
To store the value "for one info field, for one value", we need to fill the object db_info_data as explained earlier.
For db_info_field_id you can supply an embedded entity (db_info_field_name or db_info_field) to create/update the db_info_field.
For db_table_id you can supply the name (db_table_name) of the table (like 'company') instead of his Guid.
Because the entity target_id points to a dynamic entity (like a company.id or project.id) it's not possible to handle full embedded entity.
But you can fill the field target_code with your ERP primary key !
If API found a valid object that belongs to this table with this code then API automatically fills the target_id.
Here is an example of a POST to fill the value for a company with company.code='COMPANY123' with the info field (the textbox)created previously.
<db_info_data> <db_table_name>company</db_table_name> <target_code>COMPANY123</target_code> <value>value filled with he API</value> <db_info_field_name>TESTAPI_COMPANY_TXT1</db_info_field_name> </db_info_data>
Now, we can use the embedded entity for db_info_field_id.
<db_info_data> <db_table_name>company</db_table_name> <target_code>COMPANY123</target_code> <value>value filled with he API</value> <db_info_field> <name>TESTAPI_COMPANY_TXT1</name> <title>Field added using API</title> <db_input_type_code>TextArea</db_input_type_code> <db_info> <code>TESTAPI_CHAPTER_1</code> <name>Chapter Test API</name> <db_info_category_code>Company</db_info_category_code> </db_info> </db_info_field> </db_info_data>