ERP 2.50:Functional Documentation/General Setup
The purpose of this section is to explain the setup of the things that you can find in the application but not under the perspective of the data model. To have the right configuration it is important to install OB successfully. To use OB correctly follow this flow:
This section focus on General Setup. This module improves and increases the performance of OB and allows to setup multiple things.
Openbravo is a multi-company application. Each client-entity is a company managed by the application. The management of each entity is independent from others in the application. Each entity comprises one or more organizations.
Openbravo works with at least two different entities. The one which manages model data and source data and the one which manages the sample/transactional data. So working with two entities the structure would be:
- The name of the client is System. To see all the data related to this client the user must be able to login with role System Administrator. Use default user: Openbravo password: openbravo. All the model data has tables, columns, windows, tabs, fields, menu, etc. so it is independent from any other client but at the same time every client will use the same windows, fields, etc that have been configured as system client. In the same way the source data has to be with data that is mandatory for some process independently from the rest of the clients but every client needs them. So this is common data for all clients.
- This new client must be created using the process Initial client setup. All the sample/transactional data is created under this new client and only the users related to this client can see the data.
Create a client
The only way of creating an entity is using the process Initial client setup. The reason is that a lot of processes have to be done in order to create the entity properly.
Please see the steps for creating a new client.
Four main tasks are involved in the initial client setup:
These four tasks are independent so if one of them fails, the process keeps going. But the fact is if data client or financial data fails OB won't work correctly.
1. Data client
This task is in charge of:
- Creates all the trees for the application: Organization, business partner, product, accounting report, taxes report, etc.
- Creates two user and two roles in order to be able to use the application with the new client and adds these two roles to user Openbravo
- Creates an organization
As an example and filling the fields in the Initial client setup window as this way:
- Client: OBSoftware
- Organization: Pamplona
- Client Username: Sirof
- Organization Username: Amedio
The process creates:
- Role1: OBSoftware Admin (Client name + Admin)
- Role2: OBSoftware User (Client name + User)
And relates the users → roles → organization having at the end this structure:
The reason why the process relates the new roles with user Openbravo is because Openbravo is the super user of the application so that user can manage all the entities and the application dictionary.
The difference between Sirof and Amedio users comes from the roles so with the organizations as well. Having access to organization * means that you can see everything in the application independently from the organization. However having access only to organization Pamplona means that you can only see the data related to this organization.
2. Accounting data
This task is in charge of:
- Creates the calendar year
- Creates the accounting schema
- Creates the account element
- Creates the accounting dimension
This task can be avoided if the chart of accounts is not selected. This has sense when OB is not used for accounting purposes just for management.
3. Financial data
This task is in charge of:
- Creates all the document types and their sequence. This is something mandatory to be able to create transactional documents.
From 2.50 MP19 version onwards, this is an optional step. In the initial client setup window, a new dataset is created belonging to core, with all the information about document types, sequences, etc., so core will appear as a module to be applied. If chosen, then all this data will be created for the new Client. If not, nothing will be created, and user will be able to apply this dataset later on through Enterprise Module Management window.
4. Master data
This task is in charge of:
- Creates a sample data (all the data is created with the name standard) to be able to start doing things with the application. It would be like a little configuration. All this data is created under this new entity and with organization * so it can be used by any other organization that belongs to this entity.
Going to General setup → Application → Client → Client other things that can be configured:
- Mailing: Allows you to send emails from the ERP using some functionalities as Alerts, Interest areas. Fields to configure:
- Mail host: The host name of the Mail Server for this client with SMTP services to send mail.
- SMTP authentication: Some email servers require authentication before sending emails. If is your case, define the user name and password. If authentication is required and no user name and password is required, delivery will fail.
- Request Email: Emails for requests, alerts and escalation are sent from this email address as well as delivery information if the sales rep does not have an email account. The address must be fully qualified (e.g. email@example.com) and has to be a valid address.
- Request User: Email user name for requests, alerts and escalation are sent from this email address as well as delivery information if the sales rep does not have an email account. Required, if your mail server requires authentication as well as for processing incoming mails.
- Request User Password: Password of the user name (ID) for mail processing.
- Multi-Schema: Allows you to configure different accounting schemas for the same entity in order to show the account in different ways. For example when a company has to show its income account in different countries so in different accounting schemas.
- Other configurations:
- Allow negative stock. This is very useful when stock control is not required.
- Control the order (PO/SO) organization and the business partner organization and makes sure both are the same.
- Control the shipment organization (MR/SG) and the business partner organization and makes sure both are the same.
- Group invoice lines in accounting in order not having too many entries in the books. This is very useful when the invoices have lots of lines (i.e 200 lines for each Invoice) so instead of having 200 entries for the journal, just have entries grouping by product.
An organization is a business unit within an entity. Each entity can have more than one business unit, to reflect different departments or divisions of the parent entity. Organizations can be structured geographically, by region or by function. Every organization is managed independently, but it is possible to share information between them for example business partners and products.
Organizations are set up using a tree structure so an organization can have access to specific documents and those of the child organization but not to documents of the sibiling or parent organizations.
All the organizations always depends on the super organization called '*', which is created automatically during the Initial Client Setup process. A hypothetical tree could be:
Organizations can be independent of each other in terms of account structures, and reporting, but every organization has the following characteristics:
- It is either a parent, a child or both a parent and a child within a hierarchy.
- It has an organization type.
Organization types enable organizations to work together in a coherent way, by controlling how each organization behaves in relation to other organizations. There are four default organization types, which are sufficient for most business scenarios.
- Organization: when you create a client, the system automatically creates the super-organization (called * or organization 0). In most cases, only the super-organization has an organization type of Organization. The Organization type is not a legal entity and transactions are not allowed.
- Legal with accounting: use where an organization exists legally as a corporation, and needs its accounts transactions to be managed by Openbravo ERP.
- Legal without accounting: use where an organization exists legally as a corporation but does not require accounting functionality from Openbravo ERP.
- Generic: an organization which is not a legal entity but where transactions are allowed.
The default organization types have the following characteristics:
|Organization Type||Legal Entity||Legal Entity with Accounting||Business Unit||Transactions Allowed|
|Legal with accounting||Y||Y||N||Y|
|Legal without accounting||Y||N||N||Y|
If an organization belongs to an organization type where the Legal Entity option is selected, you can specify whether that organization is or is not allowed to open or close its own accounting periods. If period control is enabled for an organization, any user with access to that organization can open and close an accounting period.
When opening a period, the user can opt to also open the selected period(s) for child organizations. However, when closing a period, the selected period is closed for all dependent organizations.
If an organization has multiple accounting schemas, the opened / closed period will also be opened / closed in all associated schemas.
It is not mandatory that each organization has a financial calendar, but where an organization is a Legal Entity, any sub-organizations that require financial calendars must use the same calendar as the parent organization.
You can restrict reports so that they can only be generated for organizations whose organization types have the Business Unit or Legal Entity option selected. In Financial Management > Accounting > Analysis Tools > User Defined Accounting Report Setup if the Balanced option is selected, the Organization field displays only those organizations with a Business Unit or Legal Entity status.
Organization Type Parameters
For most enterprises, the default organization types are enough to enable you to model your organization. However, understanding the underlying settings of organization types will help you decide which organization types you require. Some enterprises may also need to create custom organization types.
In General Setup > Enterprise > Organization Type, there are four options that govern how organizations of each organization type behave.
If an organization type has the Legal Entity option selected:
- Any organization belonging to the organization type is a legally recognized corporation.
Legal Entity with accounting
If an organization type includes the With Accounting option:
- Any organization belonging to the organization type is a legal entity (the With accounting option only becomes available if the Legal Entity option is already selected).
- Any organization belonging to the organization type allows its accounts to be managed by Openbravo ERP. Organizations that do not have accounting enabled are allowed to post financial transactions, if the Transactions Allowed option is selected, but the transactions are not used for financial reporting.
- You can specify whether organizations belonging to that type are allowed to open or close their own accounting periods.
If an organization type includes the Transactions Allowed option, organizations belonging to the organization type are allowed to post transactions for accounting purposes. If an organization is of a type where transactions are not allowed, you cannot include that organization on an accounting document, for example an invoice.
If an organization type includes the Business Unit option:
- Organizations belonging to that organization type are discrete sub-organizations of the client but have no legal status.
- You can specify whether organizations belonging to that type are allowed to open or close their own accounting periods.
Organization type rules
If your enterprise has more than one organization, you must observe the following rules when setting up the organizational structure:
- Each organization must have an organization type.
- Each organization where transactions are allowed must have one, but only one ancestor (including itself) that is a legal entity.
- If an organization belongs to an organization type where the business unit option is enabled, it must have one, and only one ancestor that is a legal entity.
- Only one organization of a type where the business unit option is enabled can be placed in each branch of the organization tree.
- If a legal entity has accounting enabled, it must have either:
- Its own account schema and its own financial calendar, or,
- An ancestor with its own accounts schema and financial calendar.
- If an organization is of an organization type where the Business Unit setting is enabled, it must have an ancestor that is a legal entity.
- If an organization belongs to an organization type where the legal entity or business unit option is selected, you can specify whether that organization is allowed to open or close its own accounting periods.
It is recommended that you enable period controls on all organizations of legal entity with accounting and assign each legal entity organization its own calendar
- Once an organization has been made ready, you cannot change the organization type.
- You cannot use more than one financial calendar within the same branch of the organization tree, so a child organization cannot have a different financial calendar from its parent organization.
- If an organization is the descendant of a legal entity with accounting, when you try to complete an accounting document (for example a sales invoice), Openbravo ERP checks that the accounting period is open. If accounting is not enabled, no check takes place.
The security permissions in a multi-organization follow this schema:
- Allowed to create documents in any organization except Org *
- Allowed to see data related to any organization
- Allowed to create any master data in any organization including Org *
- Allowed to create documents in Main org and Org1
- Allowed to see data related to Main org and its child organizations (org1, org2). Also the possibility of only selecting the Org1
- Allowed to create any master data in any organization except in Org2
- Only allowed to create documents in Org2
- Only allowed to see the data related to Org2
- Only allowed to create master data in Org2 including Org *
In this tab there are two very important fields that needs to be well configured:
The calculation of taxes depends on this because when a tax is configured there are four fields that must be correctly setup: Country from/Country to, Region from/Region to.
So in a procurement flow, OB takes the Country from and the Region from from the supplier location and the Country to and Region to from the Organization location.
In a sales flow, is the other way around.
- Business partner
This business partner is used for internal processes that needs a business partner. For example in internal transfers. Doing internal transfers (i.e from the cash journal to the bank account) means create two bills (one payment, one receivable) so a business partner is mandatory for this.
Not having this business partner setup the process Financial management → Receivables&Payables → Transactions → Funds transfers won't work.
The purpose of this section is to explain the current model for Openbravo security.
Security can be divided into functional and data. Functional Security defines access to different application elements while Data Security determines which data inside those elements is accessible or not.
Vertical security manages the definition of users, roles and permissions adding users to roles and making possible to decide if a user can access to a determinate element (for example to a window, form, process)
So the issues involve in vertical security are:
Users are the entities that can log into the application. The minimum requirements for a user to be able to log in is to have a password and at least one role associated. A user is supposed to be a representation of a person (each person should be a different user)
Roles are the connection between users and permissions, permissions are associated to roles and roles are linked to users. A role defines what information is allowed and which is forbidden. Despite of the fact that a single user can have multiple associated roles, only one role is effective at the same time: although the logged user has more than one role she or he will have to select one role or another one in order to have different access permissions.
Different permissions can be associated to a role. The effect of this is that the role will have access only to those elements having permission to.
Permissions are defined in the following levels: Organization Access, Element Access (windows, forms, processes...) and Table Access.
- Organization Access: Defines which organizations have the role access to.
- Element Access: A role can have access to these application elements Windows, Processes, Forms, Workflows and Tasks. For each of these elements to be allowed for a role it is necessary to explicitly give access to it. This means that, for example, only those windows with access linked to a role will be accessible for it.
- Table Access: This element grants access in a different way than the others. Here it is possible to revoke access to the selected tables. When permission is not allowed for a table the tabs associated to it will not be accessible.
Processes can be launched from menu or from buttons within tabs. The ones executed from menu and the ones with manual UI executed from tabs need to have explicit permission to be executed (see section above).
Standard UI processes that are launched from buttons within tabs, it is not necessary to grant explicit permission to the role to execute them. Permission is inherited from the window, so if the role has write access to the window, it will be able to execute the process.
It is possible to change this default behavior by adding a "Secured Process" system preference. If this preference is set, standard UI processes will work as the rest of them, being necessary to explicitly grant access to them to be executable.
To define this preference:
- Create a new List preference picking Secured Process as property.
- Set 'Y' as value
- Ensure visibility is correct.
You can find more documentation on defining properties here.
Horizontal Security is managed by clients, organizations, access level and user level. Thus is decided which data is accessible and which is not.
Data access level
Access level defines from which client/organizations is data visible. Access level is set for tables, processes, forms, workflows and tasks, so any of this elements has one access level. There are five possible levels:
The access permissions for them is described in the table below, where:
- Client 0: Client which shares its data among every client
- Organization *: An organization within a client sharing information between all the organizations in the same client
- Non 0/Non *: Only data in a non-0 client or non-* organization is visible and Any denotes that any type of data is accessible:
|System||0||*||Only allow to see records with client 0 and Org *. For example the application dictionary records|
|System/client||Any||*||Only allow to see records in any client and see Org *. For example master data records|
|Organization||Non 0||Non *||Only allow to see records in any client except 0 and see any org except *. For example transactional documents|
|Client/Organization||Non 0||Any||Only allow to see records in any client except 0 and see any org. For example transactional documents, master data
|All||Any||Any||Allow to see anything|
In any Window in Openbravo, it is possible for a user to see the records that belong to Organizations within the Natural Tree of the Organizations that the user has access to. This means that the user can see records from parent and children Organizations.
However, the user will not be able to edit the data of this records if it has not explicit access to the Organization of the record.
Every role has a user level which is used in the vertical security way in order to allow or deny access not only to data but to the whole element (for example to a window). There are three possible user levels (and their combinations): Client, Organization and System. User level is used in conjunction with Data Access level, so only roles defined with a type of user level can access to some types of elements defined in some Data Access level, it's summarized in the table below:
|Data Access Level||User Level|
|System/Client||System or Client or Client+Organization|
|Organization||Organization or Client+Organization|
|Client/Organization||Client+Organization or organization|
|All||System, Client+Organization, Organization|
Log in security
Log in security includes 2 features: User/Password check time delay after failed log in and Locking Users.
Both of them are configurable using the Openbravo.properties file.
User/Password check time delay
A time delay can be included for the log in user/password check after an invalid log in attempt. This delay is applied for a user in case the last time he/she tried to log in the application did not enter a valid password. This delay makes bots to spend much more time trying to guess a password for a user, making them virtually unusable.
The delay increments each time the user fails up to a maximum time. Once there is a correct login for that user, the delay is reset and it will be applied again in case of new failures.
It is configured through 2 properties in Openbravo.properties file.
- login.trial.delay.increment: Number of seconds the delay increases after each log in fail (decimal numbers are allowed starting from 3.0PR18Q3). In case this property is not present, it is empty or it is 0, there will not be delay. Starting from 3.0PR18Q3, new instances default it to 200 milliseconds.
- login.trial.delay.max: Maximum delay time in seconds. Once this delay time is reached, the increment defined in the previous property is not added any more. In the same way as the one above, if it is not present, it is empty or it is 0, there will not be maximum delay time, so the increment will be always added. Starting from 3.0PR18Q3, new instances default it to 3 seconds.
If the login security is enabled (login.trial.delay.increment is higher than 0), users can be locked after a number of failed log in trials. Once a user is locked he/she cannot log in the application until the user is unlocked. A message informing about this situation will be displayed.
The number of trails before the user is locked is configured by the login.trial.user.lock property. If it is not present, empty or 0, users will not be locked and locked users will have access to the application again. It is defaulted to 0.
Unlocking Locked Users
When a user is locked, it can be unlocked by an admin user. To do so log in as admin and go to General Setup || Security || User window. There uncheck the Locked field.
If admin is locked, it will be necessary to (temporary) disable the user locking mechanism by setting login.trial.user.lock property to 0 to allow access. Once the admin has logged in the application, this property can be restored to the previous value. Now you can proceed to unlock the user as explained in the paragraph above.
Instance configuration levels
On an instance it is possible to make settings on different levels. These levels are System, Client, Organization, Role and User. They are used to configure different functionalities such as Preferences, Widget Instances and Views. To make a configuration on a level different than User new Administrator flags have been included on the Role definition.
- System level
- There is no flag for System level.
- Users logged as System Administrator are able to configure settings at System level.
- These settings will be available to everyone.
- Client level
- There is a Client Administrator flag on the Role tab.
- Users are able to configure settings at Client level if the logged role has the flag enabled.
- These settings are available to all the users on the role's client.
- Organization level
- There is a Organization Administrator flag on the Org Access tab.
- Users are able to configure settings at Organization level on all the organizations of the logged role that have the flag enabled.
- These settings are available to all the users logged on that Organization.
- Role level
- There is a Role Administrator flag on the User Assignment tab.
- Users are able to configure setting at Role level on all the roles it is assigned to with the flag enabled.
- These settings are available to all the users logged with that role.
- User level
- Any user can define its own settings.
- Users are able to configure its own settings at user level and can choose if it is shown for an specific organization and/or role. All user level configurations belong to an specific client and are not shared between clients.
- These settings are available to the user who defines them.
Setup background process
Any background process can be defined in OpenbravoERP. This processes can be developed as a PL or java file and they can be scheduled and automatically executed. Processes can be executed at whatever interval is required, daily or on the specific days of the week, as a recurrent event or a one-off at a particular time.
The steps to create and setup a process are:
- Create the process in the application dictionary
- Create a schedule for it
Also the background processes can be activated or deactivated and this is very useful because sometimes when the process can run manually first is mandatory to stop the background process (i.e:PeriodicAcctServer)
OpenbravoERP is a multilingual application which means it is possible to see the whole interface in different languages.
See the steps for import/export translations.
In Openbravo database exist some tables that have their own translation table. All these kind of tables must be filled in English and the translation ones in the language that user wants. Whenever you login in English you see the data from the original tables, but if you login in a different language you will see the data from the translation tables.
Initially (from the installer) the translation tables comes in Spanish as a default language so means all the tables have their translation in Spanish.
The way to import/export translation work is:
Setup default values
In OpenbravoERP there are three ways of setting default values:
- Checking a record as a default value: In some windows you can define the default value of a list of values. These windows have a field "By default" so just checking the flag, the record will become a default value (i.e. Document type window)
- Through the application dictionary: Another way is going to the column that relates to that field and write the default value. So whenever you get to a window that contains that column it will be filled with that value. Please note it will only happen when creating a new record
- Using preferences: This is a more sophisticated way of configuring default values. It is possible to define a default value for a specific window, specific user and specific field
Whenever a user logs in, the application establish some session variables and within these are the default values. These all default values are managed in a hierarchy way.
A default value is set in Financial management->Accounting->Set up->Document type marking the record "POS Order"
Now as you are still logged in, if you go to the Sales order window and click New it won't show up the value "POS Order", but logging out and then logging in, the application will establish the new session variables and the "POS Order" value will show up
Maintaining the default value from example 1, the user may decide to set up another default value through the application dictionary in the same table as the window "Sales order" uses.
In this case the user must go to Application dictionary->Tables and columns-> and select the table C_Order. Then select the column C_Doctypetarget_id and fill the field "Default value" writing the ID for the corresponding document type. Let´s write for this example "Warehouse order".
This set up will have effect after the application is compiled
So now for the same window the OpenbravoERP has two default values, POS order and Warehouse Order, but this won't be a problem as the default values work in a hierarchy way.
The default value for the window will be "Warehouse order".
Finally the user decides to set up a new default value for the window "Sales order", but, in this case, using the preferences method.
The user should go to General set up->Application->Preferences and select the window, write C_Doctypetarget_id in the attribute field and the ID of the corresponding document type (e.g. Standard Order)
As before, only by logging out and logging in again will the new default value be established permanently.
So at this point OpenbravoERP will have three default values:
- By marking "By default" from the window Document type: POS Order
- By the application dictionary: Warehouse Order
- By the preferences menu: Standard Order
But the definitive default value will be "Standard Order" because the preferences method is the most restrictive way of setting up default values
Alerts are the way Openbravo ERP informs users about virtually any event that happens in the system and the administrator has defined a rule to show it.
The work flow for alerts is as follows:
- Administrator creates alert rules, which include a SQL clause defining the event that is going to be monitored and the recipients for the alerts.
- A background process is permanently checking if the conditions defined in each of the active alert rules return any line, in this case a new alert instance will be created for each of the returned lines.
- When a user logs in the application there is another process that constantly checks whether there are alert instances whose recipient is the current user and shows them to the user.
For more information click here
The way of configuring the menu in OpenbravoERP is easy and simple. The menu is organized in a hierarchy way as a tree node.
There can be two types of nodes:
- Folder: Group nodes
- Final node: Nodes that have an action related and can be
- External link
- Internal link
To add these actions in the menu and working:
- Create the element through the application dictionary: Windows, Reports, Process, etc.
- Compile the window, process, etc.
- Create node into the menu and add the action
- Finally move the node within the menu
When a node group different nodes, no actions can be related. For example when you create a new module or different sections inside a module (i.e. Reports, Set up)
See how to change the order in the menu.
Preferences can be manually set from General Setup || Application || Preference window. They can also be populated by modules.
The list of principal preferences defined in core is:
- Startpage of the user: The page to which the user is redirected after logging in. This is a relative url:
- if your startpage is a standard html page then you can point to it directly, for example: /web/org.openbravo.client.application/index.html
- if your startpage is a form defined in Openbravo then you should pass the form url as a parameter like this: /security/Menu.html?url=/myModule/newOpenbravoHome.html
- Note to workaround the startpage preference you can pass in the noprefs parameters. The url to use is then: http://localhost:8080/openbravo/security/Menu.html?noprefs=true
- Implements Customer Credit Used calculation:Avoid the C_BP_SOCREDITUSED_REFRESH function calculation.
- Implements an alternative Financial Management: Alternative Financial Management implementation within the module.
- Implements Payment Monitor management: Disables core's background process and button on invoice's header that manage the Payment Monitor
- Forced Login URL (Available from 2.50MP23): If this property is set and the Openbravo login page is accessed using a different URL, it will be redirected to the one defined by this property. Value for this property should be assigned at system level because it is used before login so there is not already user nor role (this means that all "Visible" fields should be left empty). This solves application logout under some circumstances (issue 14430).
- Secured Process (Available from 2.50MP27/3.0RC4): Forces UI standard processes to be secured. See more details here.
Attribute preferences are defined by a name (attribute) instead by a value in a list.
The list of principal preferences defined in core is:
- ForcedLinkWindow* (Available from 2.50MP27/3.0RC4): If a preference like ForcedLinkWindowDBTableName (where DBTableName is the name of the table in DB) is present, direct navigation will use as target the window which UUID is in the preference value instead of using the standard logic. For example a preference with attribute/value pair like ForcedLinkWindowC_Project/AAAAAAAAAAAAAAAAAA00000000000000 will make direct navigation to project to be opened in window with ID AAAAAAAAAAAAAAAAAA00000000000000. This window must have a tab which table is C_Project Note it is case sensitive.
- ModalModule* and ModalProcess* (Available from 3.0RC4): Defines whether processes should be opened in a browser or in a modal popup. See detailed information here.
Upgrade from a previous MP
Preferences are loaded in session when logging in the application or changing the current role. The way they are loaded has slightly changed in 2.50MP16.
- Prior to 2.50MP16. All preferences defined for a concrete client/organization (different that System), where loaded in case the used role had explicitly granted access to those organizations, but organization tree was not taken into account. For example, assuming a organization tree like *, A, A1, B being A1 below A in the tree and B at the same level of A. If the same preference has values for A and B, and a role (role1) with access to A and B logged in the application the preference value was unpredictable because both (A and B) were loaded, for a role (role2) having only access to A1, no preference value was loaded.
- From 2.50MP16. Preferences are loaded for the currently used organization (not the granted ones) taking into account the organization tree. So for the previous example, role1 logging in organization A would load preference value for organization A, role1 logging in organization B would load preference value for organization B, role2 logging in organization A1 would load preference value for organization A.
Because of this change, When upgrading core from a version prior to 2.50MP16, depending the preferences defined in the instance, it is possible some changes in the behavior. These cases are detected during the upgrade process displaying a warning. Administrator should take care of these cases. Note that this warning only appears during the upgrade process from a version prior to 2.50MP16 to 2.50MP16 or higher, but it will not appear again.