iDempiere en - User contributions [en]

Multiple instances of iDempiere

2021-07-29T15:24:11Z

Soundbytes: typo

Running multiple instances of iDempiere on a single server is not too difficult. Here is a checklist of things to take care of:

# Install the instances into different directories. The instances do not need to share any common files. So you are just fine making a full installation for each instance.
# Make sure the iDempiere server instances use different TCP ports.
# If you really should need to use a single port to access all of the instances you could use an HTTP server like Apache or Ngnix to define virtual hosts. Proxying or use of rewrite rules will then allow you to manage the desired redirections. I recommend using subdomains to do the job.
# With an HTTP server in front of iDempiere, you will also be able to offload the ssh encryption (HTTPS) onto the HTTP server.
# There is another benefit to using subdomains for browser access: If all your server instances use the same hostname the client browser will sometimes not be able to keep cookies from different instances apart. This can lead to a blocked session as discussed [https://groups.google.com/g/idempiere/c/kBefSKYsq0o here] in the iDempiere google group.
# Make sure each instance uses its own database. Use different names for the instance databases.
# Use different DB user names. The docs advise not to change the default user name Adempiere and this is ok for a single instance installation. However, if you use a single DB user for all of your instances you will run into trouble once you need to restore a database from a backup file. The RUN_DBRestore.sh will attempt to delete and recreate the DB user which will throw an error when the user owns more than one DB.
# Multiple database Clusters under Postgresql: If a Postgresql database server is used it might make sense to use a dedicated database cluster for each iDempiere instance to avoid any side effects of having multiple iDempiere databases side by side. Firewalling the iDempiere instances through database clusters allows to use the recommended configuration for database and database user names in each cluster (You can ignore points 6. and 7. then). Note that using dedicated database clusters requires some additional steps in database server setup. Also server hardware requirements might be a bit higher because of the added overhead.
# You can run all of your instances as services in parallel. Before the installation of another instance rename the service script: <code>sudo mv /etc/init.d/iDempiere /etc/init.d/iDempiere-theInstance.</code> Of course, you will need to do some book keeping work with the service controller of your OS to ensure that the renamed services are started as desired.
# The service controller talks to the iDempiere server via the OSGI console. For this to work without problems in a multi-instance environment you need to assign a different telnet port number to each of the instances: in the editor of your choice open the file <code>/etc/init.d/iDempiere</code>. Find the line <code>export TELNET_PORT=12612</code> and change the port number to something else.

Please Note:

* OS specific descriptions in this guide are for Ubuntu 16/18/20 or Debian, if on another OS you might need to do some further research.
* I have been using the described approach to host iDempiere since version 5 for some time now and did not have any problems so far. Still make sure you do your own thorough tests if you want to go that route.
* If you run into any problems (and maybe even manage to solve them) please report back to the community. (You can edit this page or post to the iDempiere [https://groups.google.com/g/idempiere Google group]) Thanks!
[[Category:HowTo-Technical]]

Multiple instances of iDempiere

2021-07-29T15:22:35Z

Soundbytes: typo

Running multiple instances of iDempiere on a single server is not too difficult. Here is a checklist of things to take care of:

# Install the instances into different directories. The instances do not need to share any common files. So you are just fine making a full installation for each instance.
# Make sure the iDempiere server instances use different TCP ports.
# If you really should need to use a single port to access all of the instances you could use an HTTP server like Apache or Ngnix to define virtual hosts. Proxying or use of rewrite rules will then allow you to manage the desired redirections. I recommend using subdomains to do the job.
# With an HTTP server in front of iDempiere, you will also be able to offload the ssh encryption (HTTPS) onto the HTTP server.
# There is another benefit to using subdomains for browser access: If all your server instances use the same hostname the client browser will sometimes not be able to keep cookies from different instances apart. This can lead to a blocked session as discussed [https://groups.google.com/g/idempiere/c/kBefSKYsq0o here] in the iDempiere google group.
# Make sure each instance uses its own database. Use different names for the instance databases.
# Use different DB user names. The docs advise not to change the default user name Adempiere and this is ok for a single instance installation. However, if you use a single DB user for all of your instances you will run into trouble once you need to restore a database from a backup file. The RUN_DBRestore.sh will attempt to delete and recreate the DB user which will throw an error when the user owns more than one DB.
# Multiple database Clusters under Postgresql: If a Postgres Database server is used it might make sense to use a dedicated database cluster for each iDempiere instance to avoid any side effects of having multiple iDempiere databases side by side. Firewalling the idempiere instances with database clusters allows to use the recommended configuration for database and database user names in each cluster (You can ignore points 6. and 7. then). Note that using dedicated database clusters requires some additional steps in database server setup. Also server hardware requirements might be a bit higher because of the added overhead.
# You can run all of your instances as services in parallel. Before the installation of another instance rename the service script: <code>sudo mv /etc/init.d/iDempiere /etc/init.d/iDempiere-theInstance.</code> Of course, you will need to do some book keeping work with the service controller of your OS to ensure that the renamed services are started as desired.
# The service controller talks to the iDempiere server via the OSGI console. For this to work without problems in a multi-instance environment you need to assign a different telnet port number to each of the instances: in the editor of your choice open the file <code>/etc/init.d/iDempiere</code>. Find the line <code>export TELNET_PORT=12612</code> and change the port number to something else.

Please Note:

* OS specific descriptions in this guide are for Ubuntu 16/18/20 or Debian, if on another OS you might need to do some further research.
* I have been using the described approach to host iDempiere since version 5 for some time now and did not have any problems so far. Still make sure you do your own thorough tests if you want to go that route.
* If you run into any problems (and maybe even manage to solve them) please report back to the community. (You can edit this page or post to the iDempiere [https://groups.google.com/g/idempiere Google group]) Thanks!
[[Category:HowTo-Technical]]

Multiple instances of iDempiere

2021-07-29T09:19:08Z

Soundbytes: typos fixed

Running multiple instances of iDempiere on a single server is not too difficult. Here is a checklist of things to take care of:

# Install the instances into different directories. The instances do not need to share any common files. So you are just fine making a full installation for each instance.
# Make sure the iDempiere server instances use different TCP ports.
# If you really should need to use a single port to access all of the instances you could use an HTTP server like Apache or Ngnix to define virtual hosts. Proxying or use of rewrite rules will then allow you to manage the desired redirections. I recommend using subdomains to do the job.
# With an HTTP server in front of iDempiere, you will also be able to offload the ssh encryption (HTTPS) onto the HTTP server.
# There is another benefit to using subdomains for browser access: If all your server instances use the same hostname the client browser will sometimes not be able to keep cookies from different instances apart. This can lead to a blocked session as discussed [https://groups.google.com/g/idempiere/c/kBefSKYsq0o here] in the iDempiere google group.
# Make sure each instance uses its own database. Use different names for the instance databases.
# Use different DB user names. The docs advise not to change the default user name Adempiere and this is ok for a single instance installation. However, if you use a single DB user for all of your instances you will run into trouble once you need to restore a database from a backup file. The RUN_DBRestore.sh will attempt to delete and recreate the DB user which will throw an error when the user owns more than one DB.
# Multiple database Clusters on Postgresql: If a Postgres Database server is used it might make sense to use a dedicated database cluster for each iDempiere instance to avoid any side effects of having multiple iDempiere databases side by side. Firewalling the idempiere instances with database clusters allows to use the recommended configuration for database and database user names in each cluster (You can ignore points 6. and 7. then). Note that using dedicated database clusters requires some additional steps in database server setup. Also server hardware requirements might be a bit higher because of the added overhead.
# You can run all of your instances as services in parallel. Before the installation of another instance rename the service script: <code>sudo mv /etc/init.d/iDempiere /etc/init.d/iDempiere-theInstance.</code> Of course, you will need to do some book keeping work with the service controller of your OS to ensure that the renamed services are started as desired.
# The service controller talks to the iDempiere server via the OSGI console. For this to work without problems in a multi-instance environment you need to assign a different telnet port number to each of the instances: in the editor of your choice open the file <code>/etc/init.d/iDempiere</code>. Find the line <code>export TELNET_PORT=12612</code> and change the port number to something else.

Please Note:

* OS specific descriptions in this guide are for Ubuntu 16/18/20 or Debian, if on another OS you might need to do some further research.
* I have been using the described approach to host iDempiere since version 5 for some time now and did not have any problems so far. Still make sure you do your own thorough tests if you want to go that route.
* If you run into any problems (and maybe even manage to solve them) please report back to the community. (You can edit this page or post to the iDempiere [https://groups.google.com/g/idempiere Google group]) Thanks!
[[Category:HowTo-Technical]]

Multiple instances of iDempiere

2021-07-28T10:30:00Z

Soundbytes: added paragraph on postgresql DB clusters

Running multiple instances of iDempiere on a single server is not too difficult. Here is a checklist of things to take care of:

# Install the instances into different directories. The instances do not need to share any common files. So you are just fine making a full installation for each instance.
# Make sure the iDempiere server instances use different TCP ports.
# If you really should need to use a single port to access all of the instances you could use an HTTP server like Apache or Ngnix to do define virtual hosts. Proxying or use of rewrite rules will then allow you to do the desired redirections. I recommend using subdomains to do the job.
# With an HTTP server in front of iDempiere, you will also be able to offload the ssh encryption (HTTPS) onto the HTTP server.
# There is another benefit to using subdomains for browser access: If all your server instances use the same hostname the client browser will sometimes not be able to keep cookies from different instances apart. This can lead to a blocked session as discussed [https://groups.google.com/g/idempiere/c/kBefSKYsq0o here] in the iDempiere google group.
# Make sure each instance uses its own database. Use different names for the instance databases.
# Use different DB user names. The docs advise not to change the default user name Adempiere and this is ok for a single instance installation. However, if you use a single DB user for all of your instances you will run into trouble once you need to restore a database from a backup file. The RUN_DBRestore.sh will attempt to delete and recreate the DB user which will throw an error when the user owns more than one DB.
# Multiple database Clusters on Postgresql: If a Postgres Database server is used it might make sense to use a dedicated database cluster for each iDempiere instance to avoid any side effects of having multiple iDempiere databases side by side. Firewalling the idempiere instances with database clusters allows to use the recommended configuration for database and database user names in each cluster (You can ignore points 6. and 7. then). Note that using dedicated database clusters requires some additional steps in database server setup. Also server hardware requirements might be a bit higher because of the added overhead.
# You can run all of your instances as services in parallel. Before the installation of another instance rename the service script: <code>sudo mv /etc/init.d/iDempiere /etc/init.d/iDempiere-theInstance.</code> Of course, you will need to do some book keeping work with the service controller of your OS to ensure that the renamed services are started as desired.
# The service controller talks to the iDempiere server via the OSGI console. For this to work without problems in a multi-instance environment you need to assign a different telnet port number to each of the instances: in the editor of your choice open the file <code>/etc/init.d/iDempiere</code>. Find the line <code>export TELNET_PORT=12612</code> and change the port number to something else.

Please Note:

* OS specific descriptions in this guide are for Ubuntu 16/18/20 or Debian, if on another OS you might need to do some further research.
* I have been using the described approach to host iDempiere since version 5 for some time now and did not have any problems so far. Still make sure you do your own thorough tests if you want to go that route.
* If you run into any problems (and maybe even manage to solve them) please report back to the community. (You can edit this page or post to the iDempiere [https://groups.google.com/g/idempiere Google group]) Thanks!
[[Category:HowTo-Technical]]

Multiple instances of iDempiere

2021-07-27T11:19:49Z

Soundbytes:

Running multiple instances of iDempiere on a single server is not too difficult. Here is a checklist of things to take care of:

* Install the instances into different directories. The instances do not need to share any common files. So you are just fine making a full installation for each instance.
* Make sure each instance uses its own data base. Use different names for the instance data bases.
* Make sure the iDempiere server instances use different tcp ports.
* If you really should need to use a single port to access all of the instances you could use a http server like apache or ngnix to do define virtual hosts. Proxying or use of rewrite rules will then allow you to do the desired redirections. I recommend using subdomains to do the job.
* With a http server in front of iDempiere you will also be able to offload the ssh encryption (https) onto the http server.
* There is another benefit to using subdomains for browser access: If all your server instances use the same host name the client browser will sometimes not be able to keep cookies from different instances apart. This can lead to a blocked session as discussed [https://groups.google.com/g/idempiere/c/kBefSKYsq0o here] in the iDempiere google group.
* Use different DB user names. The docs advise not to change the default user name Adempiere and this is ok for a single instance installation. Still if you use a single DB user for all of your instances you will run into trouble once you need to restore a database from a backup file. The RUN_DBRestore.sh will attempt to delete and recreate the DB user which will throw an error when the user owns more than one DB.
* You can run all of your instances as services in parallel. Before the installation of another instance rename the service script: <code>sudo mv /etc/init.d/iDempiere /etc/init.d/iDempiere-theInstance.</code> Of course you will need to do some book keeping work with the service controller of your OS to ensure that the renamed services are started as desired.

* The service controller talks to the iDempiere server via the OSGI console. For this to work without problems in a multi instance environment you need to assign a different telnet port number to each of the instances: in the editor of your choice open the file <code>/etc/init.d/iDempiere</code>. Find the line <code>export TELNET_PORT=12612</code> and change the port number to something else.

Please Note:

* OS specific descriptions in this guide are for Ubuntu 16/18/20 or Debian, if on another OS you might need to do some further research.
* I have been using the described approach to host iDempiere since versions 5 for some time now and did not have any problems so far. Still make sure you do your own thorough tests if you want to go that route.
* If you run into any problems (and maybe even manage to solve them) please report back to the community. (You can edit this page or post to the iDempiere [https://groups.google.com/g/idempiere Google group]) Thanks!
[[Category:HowTo-Technical]]

Multiple instances of iDempiere

2021-07-27T11:14:51Z

Soundbytes:

Running multiple instances of idempiere on a single server is not too difficult. Here is a checklist of things to take care of:

* Install the instances into different directories. The instances do not need to share any common files. So you are just fine making a full installation for each instance.
* Make sure each instance uses its own data base. Use different names for the instance data bases.
* Make sure the idempiere server instances use different tcp ports.
* If you really should need to use a single port to access all of the instances you could use a http server like apache or ngnix to do define virtual hosts. Proxying or use of rewrite rules will then allow you to do the desired redirections. I recommend using subdomains to do the job.
* With a http server in front of iDempiere you will also be able to offload the ssh encryption (https) onto the http server.
* There is another benefit to using subdomains for browser access: If all your server instances use the same host name the client browser will sometimes not be able to keep cookies from different instances apart. This can lead to a blocked session as discussed [https://groups.google.com/g/idempiere/c/kBefSKYsq0o here] in the iDempiere google group.
* Use different DB user names. The docs advise not to change the default user name Adempiere and this is ok for a single instance installation. Still if you use a single DB user for all of your instances you will run into trouble once you need to restore a database from a backup file. The RUN_DBRestore.sh will attempt to delete and recreate the DB user which will throw an error when the user owns more than one DB.
* You can run all of your instances as services in parallel. Before the installation of another instance rename the service script: 'sudo mv /etc/init.d/idempiere /etc/init.d/idempiere-theInstance.'
Of course you will need to do some book keeping work with the service controller of your OS to ensure that the renamed services are started as desired.
* The service controller talks to the iDempiere server via the OSGI console. For this to work without problems in a multi instance environment you need to assign a different telnet port number to each of the instances: in the editor of your choice open /etc/init.d/idempiere. Find the line 'export TELNET_PORT=12612' and change the port number to something else.

Please Note:

* OS specific descriptions in this guide are for Ubuntu 16/18/20 or Debian, if on another OS you need to do some research.
* I have been using the described approach to host idempiere versions 5 and 6 for some time now and did not have any problems so far. Still make sure you do your own thorough tests if you want to go that route.
* If you run into any problems (and maybe even manage to solve them) please report back to the community. (You can edit this page or post to the iDempiere google group) Thanks!
[[Category:HowTo-Technical]]

Multiple instances of iDempiere

2021-07-27T11:10:19Z

Soundbytes: added category

Running multiple instances of idempiere on a single server is not too difficult. Here is a checklist of things to take care of:

* Install the instances into different directories. The instances do not need to share any common files. So you are just fine making a full installation for each instance.
* Make sure each instance uses its own data base. Use different names for the instance data bases.
* Make sure the idempiere server instances use different tcp ports.
* If you really should need to use a single port to access all of the instances you could use a http server like apache or ngnix to do define virtual hosts. Proxying or use of rewrite rules will then allow you to do the desired redirections. I recommend using subdomains to do the job.
* With a http server in front of iDempiere you will also be able to offload the ssh encryption (https) onto the http server.
* There is another benefit to using subdomains for browser access: If all your server instances use the same host name the client browser will sometimes not be able to keep cookies from different instances apart. This can lead to a blocked session as discussed [https://groups.google.com/g/idempiere/c/kBefSKYsq0o here] in the iDempiere google group.
* Use different DB user names. The docs advise not to change the default user name Adempiere and this is ok for a single instance installation. Still if you use a single DB user for all of your instances you will run into trouble once you need to restore a database from a backup file. The RUN_DBRestore.sh will attempt to delete and recreate the DB user which will throw an error when the user owns more than one DB.
* You can run all of your instances as services in parallel. Before the installation of another instance rename the service script:
sudo mv /etc/init.d/idempiere /etc/init.d/idempiere-theInstance.
Of course you will need to do some book keeping work with the service controller of your OS to ensure that the renamed services are started as desired.
* The service controller talks to the iDempiere server via the OSGI console. For this to work without problems in a multi instance environment you need to assign a different telnet port number to each of the instances: in the editor of your choice open /etc/init.d/idempiere. Find the line
export TELNET_PORT=12612 and change the port number to something else.

Please Note:

* OS specific descriptions in this guide are for Ubuntu 16/18/20 or Debian, if on another OS you need to do some research.
* I have been using the described approach to host idempiere versions 5 and 6 for some time now and did not have any problems so far. Still make sure you do your own thorough tests if you want to go that route.
* If you run into any problems (and maybe even manage to solve them) please report back to the community. (You can edit this page or post to the iDempiere google group) Thanks!
[[Category:HowTo-Technical]]

Multiple instances of iDempiere

2021-07-27T11:06:40Z

Soundbytes: added a note on ssh rencryption via http server

Running multiple instances of idempiere on a single server is not too difficult. Here is a checklist of things to take care of:

* Install the instances into different directories. The instances do not need to share any common files. So you are just fine making a full installation for each instance.
* Make sure each instance uses its own data base. Use different names for the instance data bases.
* Make sure the idempiere server instances use different tcp ports.
* If you really should need to use a single port to access all of the instances you could use a http server like apache or ngnix to do define virtual hosts. Proxying or use of rewrite rules will then allow you to do the desired redirections. I recommend using subdomains to do the job.
* With a http server in front of iDempiere you will also be able to offload the ssh encryption (https) onto the http server.
* There is another benefit to using subdomains for browser access: If all your server instances use the same host name the client browser will sometimes not be able to keep cookies from different instances apart. This can lead to a blocked session as discussed [https://groups.google.com/g/idempiere/c/kBefSKYsq0o here] in the iDempiere google group.
* Use different DB user names. The docs advise not to change the default user name Adempiere and this is ok for a single instance installation. Still if you use a single DB user for all of your instances you will run into trouble once you need to restore a database from a backup file. The RUN_DBRestore.sh will attempt to delete and recreate the DB user which will throw an error when the user owns more than one DB.
* You can run all of your instances as services in parallel. Before the installation of another instance rename the service script:
sudo mv /etc/init.d/idempiere /etc/init.d/idempiere-theInstance.
Of course you will need to do some book keeping work with the service controller of your OS to ensure that the renamed services are started as desired.
* The service controller talks to the iDempiere server via the OSGI console. For this to work without problems in a multi instance environment you need to assign a different telnet port number to each of the instances: in the editor of your choice open /etc/init.d/idempiere. Find the line
export TELNET_PORT=12612 and change the port number to something else.

Please Note:

* OS specific descriptions in this guide are for Ubuntu 16/18/20 or Debian, if on another OS you need to do some research.
* I have been using the described approach to host idempiere versions 5 and 6 for some time now and did not have any problems so far. Still make sure you do your own thorough tests if you want to go that route.
* If you run into any problems (and maybe even manage to solve them) please report back to the community. (You can edit this page or post to the iDempiere google group) Thanks!

Multiple instances of iDempiere

2021-07-27T10:58:32Z

Soundbytes: Created page with "Running multiple instances of idempiere on a single server is not too difficult. Here is a checklist of things to take to take care of: * Install the instances into different..."

Running multiple instances of idempiere on a single server is not too difficult. Here is a checklist of things to take to take care of:

* Install the instances into different directories. The instances do not need to share any common files. So you are just fine making a full installation for each instance.
* Make sure each instance uses its own data base. Use different names for the instance data bases.
* Make sure the idempiere server instances use different tcp ports.
* If you really should need to use a single port to access all of the instances you could use a http server like apache or ngnix to do define virtual hosts. Proxying or use of rewrite rules will then allow you to do the desired redirections. (I am using subdomains and apache mod_proxy to do the job)
* There is another benefit to using subdomains for browser access: If all your server instances use the same host name the client browser will sometimes not be able to keep cookies from different instances apart, which can lead to a blocked session as discussed here in the idempiere google group.
* Use different DB user names. The docs advise not to change the default user name Adempiere and this is ok for a single instance installation. Still if you use a single DB user for all of your instances you will run into trouble once you need to restore a database from a backup file. The RUN_DBRestore.sh will delete and recreate the DB user which will throw an error when the user owns more than one DB.
* You can run all of your instances as services in parallel. Before the installation of another instance rename the service script:
sudo mv /etc/init.d/idempiere /etc/init.d/idempiere-theInstance.
Of course you will need to do some book keeping work with the service controller of your OS to ensure that the renamed services are started as desired.
* The service controller talks to the iDempiere server via the OSGI console. For this to work without problems in a multi instance environment you need to assign a different telnet port number to each of the instances: in the editor of your choice open /etc/init.d/idempiere. Find the line
export TELNET_PORT=12612 and change the port number to something else.

Please Note:

* OS specific descriptions in this guide are for Ubuntu 16/18/20 or Debian, if on another OS you need to do some research.
* I have been using the described approach to host idempiere versions 5 and 6 for some time now and did not have any problems so far. Still make sure you do your own thorough tests if you want to go that route.
* If you run into any problems (and maybe even manage to solve them) please report back to the community. (You can edit this page or post to the iDempiere google group) Thanks!

Application Dictionary - Add Data Relations and Configure the Quick Entry Dialog

2021-05-26T10:15:50Z

Soundbytes: just more screenshots

[[Category:Application Dictionary|P]]

__INDEX__

=Introduction=
This tutorial is brought to you by Andreas Sumerauer. If you have any questions, criticism or suggestions for improvement, feel free to join the discussion in the [https://groups.google.com/g/idempiere iDempiere google group.]

==Goal of this tutorial==
After finishing this tutorial you will have learned how to add Columns to existing tables.
You will be able to connect records from different tables in a useful way. This is done using data relations.
Finally you will learn how to create sophisticated user interface elements to manage these relations within iDempiere.
As in the previous tutorial we will again only use the iDempiere system user interface to create the additions to the database and the user interface.

==Prerequisites==
This tutorial builds on [[Application_Dictionary_-_Create_a_Custom_Table_and_Window|Create a Custom Table and Window]].
Before you start you should have successfully completed that first tutorial.
* Some knowledge of the basic concepts of relational data bases will be beneficial but is not required.
* You can greatly improve your learning experience through actively reproducing the steps given here. The customizations added during the course of the previous lesson are required for doing that.

==Example Specification==

To complete the example specification from the last tutorial we still need to create a data relation between the new ''Office Room'' table and the factory provided ''Business Partner'' table. This table holds the data of all the persons that our client's organizations are interacting with.
* That relation will be built through a new ''Office Room'' column that we are going to add to the ''Business Partner'' table together with a so called foreign key constraint that serves to keep the data consistent through any data changes that concern the newly defined relation. (Note that in iDempiere also an employee of the organization is a Business Partner.)
* On the user interface side we are going to add a new ''Office Room'' field to the ''Business Partner'' window.
* As a last step we are going to configure iDempiere's ''QuickEdit'' dialog. This will allow us to add or modify an employee's office room without having to switch away from the ''Business Partner'' window to the ''Office Room'' window.

==Conventions==

* This tutorial uses a numbered list whenever there are steps that need to be executed to implement the specified requirements.
* A bulleted list will be used for hints, explanations and background information.

=Steps=

==Add Database Elements==
[[File:Tutorial add Reference 08.png|border|right|349x349px]]

===Add a new Column to the Business Partner Table===

Now it is time to create the relation from the existing database to the new ''Office Room'' table.
# Open the Table & Columnn window and load the AD_User table.
# Click the ''Create New'' Button ('+' icon) in the ''Column'' tab tool bar to open the ''Table > Column'' window with a new record.
# In the ''Element'' field enter ''SB_OfficeRoomID''. Remember that this Element was generated when we created the ''Office Room'' table in the previous tutorial.
You will find that a number of fields have been autofilled.

Note that the System has entered the value ''Table Direct'' into the ''Relation'' field. Idempiere comes with a number of predefined relations to choose from. You can scroll through the ''Reference'' dropdown list to see all of them. The selected reference lets iDempiere know how to handle the data stored in the table column. It will determine:
* [[File:Tutorial add Reference 07.png|border|right|386x386px]]The column's data type in the database and in the application
* How the Data is presented to the user.
* The UI elements that are presented to the user for manipulation and management of the stored data.

<ol start="4">
<li>You can try and explore some different reference types by selecting them from the dropdown. You will find that the layout of the ''Column'' window adapts to show special properties that are relevant to the selection.
<li>Now return to the initial selection of ''Table Direct''.
</ol>
===Configure the Data Relation established by the new Column===

# Let's have a closer look at the ''Constraint Type'' field. Check out the choices presented through the dropdown list.

The constraint type determines how the database will behave when a the record referenced by the field is deleted:
If the user or some process tries to delete an ''Office room'' that is still referenced by some ''Business Partner'' record we need to take some action to preserve the consistency of our data. Otherwise we might end up with a dangling reference in the ''Business Partner'' record.

* [[File:Tutorial add Reference 06.png|border|right]]'''''No Action''''': This is the default. If there are any child records (i .e. any users referencing a room) then the database engine will not delete the record. Instead an error message will be produced whenever the user tries to delete that room.
* '''''Do Not Create''''': No constraint is created for this column. This is not recommended! Going without a constraint can lead to data errors, the parent can be deleted without any notice leaving orphan children in the database.
* '''''Cascade''''': When the parent record is deleted then the child records on this constraint will be deleted too (if possible) - this constraint is executed in the database, consequently the business model rules are not triggered (workflows, changelog, etc)
* '''''Model Cascade''''': When the parent record is deleted then the child records on this constraint will be deleted too (if possible) - this constraint is executed within iDempiere, so all business model rules are applied.
* '''''Set Null''''': When the parent record is deleted then the child records on this constraint will set to null (if possible)

<ol start="2">
<li>Set the ''Constraint Type'' field back to the default value ''No Action'' and save the new record.
<li>Hit the Synchronize Button and confirm the process dialog with OK to generate the new column in the database.
[[File:Tutorial add Reference 05.png|border|341x341px]]

</ol>
[[File:Tutorial add Reference 04.png|border|right|397x397px]]
A confirmation dialog will appear when the process has been completed. In the upper section of the dialog you will find the SQL commands that the application has sent to the database engine. The lower section shows the response from the database which should basically be just an exact echo of the commands given above. This indicates that the commands were executed without errors.

<ol start="4">
<li>Hit OK to close the dialog and you are done.
</ol>

==Add the User Interface Elements==

===Add a new field to a factory provided window.===

We are now going to add a new ''Office Room'' field to the 'Business Partner > Business Partner' window tab.

# Go up one tab level to the ''Table'' view. To do that click ''Table'' in the breadcrumbs bar or hit ''ALT'' + ''Arrow UP'' on the keyboard.
# Now click the Label of the ''Window'' field to zoom over to that window.
# In the business partner window switch to the ''Business Partner'' subtab by hitting the ''Edit Record'' button in the subtab row. (Or hit ''ALT'' + ''Arrow Down'' on the keyboard.)
# [[File:Tutorial add Reference 02.png|border|right|472x472px]]Now click the ''Process'' button in the icon bar and select ''Create Fields'' from the context menu. The ''Create Fields'' process dialog will appear. [[File:Tutorial add Reference 03.png|border]]

When adding fields to a factory provided window it is always a good idea to restrict the number of fields that are created by the process. Many tables include columns that purposefully do not have a corresponding field in the edit window. We need to ensure that we do not generate fields for these columns too.

<ol start="5">
<li>We will avoid inadvertently creating fields for those columns by entering today's date in the date field. This will exclude any columns from the process that have been created earlier by somebody else.
<li>Now hit OK. A confirmation dialog will appear that lists the newly created fields.
</ol>

===Configure the Window Layout===

# We are again using the Tab editor to adapt the window layout. Open the editor through the context menu of the ''Process'' button.
# In the editor you will find the new ''Office Room'' editor field at the bottom of the page. Drag and drop it to a more convenient position.

With regards to our specification it does not make sense to assign a room to a business partner that is not also an employee. We can guide our users by only showing the new field when the ''Employee'' checkbox is ticked.

<ol start="3">
<li>[[File:Tutorial add Reference 01.png|border|right|487x487px]]With the focus still on the ''Office Room'' field enter '@IsEmployee@=Y' into the '''Display Logic''' field in the ''Property'' sidebar to the right of the edit area.
</ol>

===Side Note - The iDempiere Context===

What actually have we done here? To understand the meaning of the arcane text we have just entered it is necessary to dig a bit deeper and learn a bit about the iDempiere context.
* iDempiere makes all field values of the current window (among many other things) available as so called context variables. Each time the user enters a new value into field its corresponding variable in the iDempiere context will be updated immediately.
* The iDempiere context is just a long list of values. Each of these values is paired with a key that is needed to identify that value.
* To access a context value from the '''Display Logic''' field we just have to surround its key name with @ symbols.
The application will then replace the codified key name with the respective context value and then check wether the resulting statement is true or not.
The value of the '''Display Logic''' checkbox is 'Y' when it is ticked and 'N' when not.
So when we write '@IsEmployee@=Y' iDempiere will replace the '@IsEmployee@' part with a 'Y' when the checkbox is ticked.
The statement will then be 'Y=Y'. This is obviously true and because of that the ''Office Room'' field will be shown. Unticking the box changes the statement to 'N=Y' which is false and the field will be hidden.

===Configure the Office Room Identifier String===

ToDo

===Make selected Fields available to the Quick Entry Dialog===

As a last step we are now going to make a few of the fields in the ''Office Room'' window available to the ''Quick Entry'' dialog.
We have already used that dialog in the previous tutorial when we created the entity types for our custom columns.
Remember that we did not switch to the entity type window to do that. Instead we opened the context menu of the ''Entity Type'' field and selected ''New'' to bring up the quick entry dialog. We then were able to create the new types using that dialog.
# ToDo:Switch to Window, Tab and Field: Office Room
# In the Field subtab select the ''Room Number'' row and click the ''Edit Record'' button.
# Tick the ''Quick Entry'' checkbox in ''the Window > Tab > Field'' view that the window that has switched to. This makes the field available to the QuickEntry dialog.

Repeat that last step for both the ''Floor Number'' and ''Building Wing'' fields.

Hint: Do not forget to save your last edit. iDempiere will autosave any of your changes when you load another record into the active window or switch to a parent tab or subtab. Manual saving is required in all other cases. That is when you change the focus to any other tab in the hierarchy that is not a parent or child of the previous one.

==Conclusion==

Todo: List UI customization elements: new field in existing Window, QuickEntry Dialog enabled for new Element.
Todo: Login as client admin or user
Todo: Description Office Room Field in Business Partner Window
Todo: Usage QuickEntry

File:Tutorial add Reference 08.png

2021-05-26T10:13:37Z

Soundbytes:

Table > Column window

File:Tutorial add Reference 07.png

2021-05-26T10:09:18Z

Soundbytes:

Reference dropdown list

File:Tutorial add Reference 06.png

2021-05-26T10:07:35Z

Soundbytes:

Constraint Type dropdown list

File:Tutorial add Reference 05.png

2021-05-26T10:05:51Z

Soundbytes:

Synchronize Column button

File:Tutorial add Reference 04.png

2021-05-26T10:02:55Z

Soundbytes:

Synchronize Column - Confirmation Dialog

Application Dictionary - Add Data Relations and Configure the Quick Entry Dialog

2021-05-26T10:00:35Z

Soundbytes: more screenshots

[[Category:Application Dictionary|P]]

__INDEX__

=Introduction=
This tutorial is brought to you by Andreas Sumerauer. If you have any questions, criticism or suggestions for improvement, feel free to join the discussion in the [https://groups.google.com/g/idempiere iDempiere google group.]

==Goal of this tutorial==
After finishing this tutorial you will have learned how to add Columns to existing tables.
You will be able to connect records from different tables in a useful way. This is done using data relations.
Finally you will learn how to create sophisticated user interface elements to manage these relations within iDempiere.
As in the previous tutorial we will again only use the iDempiere system user interface to create the additions to the database and the user interface.

==Prerequisites==
This tutorial builds on [[Application_Dictionary_-_Create_a_Custom_Table_and_Window|Create a Custom Table and Window]].
Before you start you should have successfully completed that first tutorial.
* Some knowledge of the basic concepts of relational data bases will be beneficial but is not required.
* You can greatly improve your learning experience through actively reproducing the steps given here. The customizations added during the course of the previous lesson are required for doing that.

==Example Specification==

To complete the example specification from the last tutorial we still need to create a data relation between the new ''Office Room'' table and the factory provided ''Business Partner'' table. This table holds the data of all the persons that our client's organizations are interacting with.
* That relation will be built through a new ''Office Room'' column that we are going to add to the ''Business Partner'' table together with a so called foreign key constraint that serves to keep the data consistent through any data changes that concern the newly defined relation. (Note that in iDempiere also an employee of the organization is a Business Partner.)
* On the user interface side we are going to add a new ''Office Room'' field to the ''Business Partner'' window.
* As a last step we are going to configure iDempiere's ''QuickEdit'' dialog. This will allow us to add or modify an employee's office room without having to switch away from the ''Business Partner'' window to the ''Office Room'' window.

==Conventions==

* This tutorial uses a numbered list whenever there are steps that need to be executed to implement the specified requirements.
* A bulleted list will be used for hints, explanations and background information.

=Steps=

==Add Database Elements==

===Add a new Column to the Business Partner Table===

Now it is time to create the relation from the existing database to the new ''Office Room'' table.
# Open the Table & Columnn window and load the AD_User table.
# Click the ''Create New'' Button ('+' icon) in the ''Column'' tab tool bar to open the ''Table > Column'' window with a new record.
# In the ''Element'' field enter ''SB_OfficeRoomID''. Remember that this Element was generated when we created the ''Office Room'' table in the previous tutorial. You will find that a number of fields will be autofilled.
Note that the System has entered the value ''Table Direct'' into the ''Relation'' field. Idempiere comes with a number of predefined relations to choose from. You can scroll through the ''Reference'' dropdown list to see all of them. The selected reference lets iDempiere know how to handle the data stored in the table column. It will determine:
* The data type in the data base and in the application
* How the Data is presented to the user.
* The UI elements that are presented to the user for manipulation and management of the stored data.

<ol start="4">
<li>You can try and explore some different reference types by selecting them from the dropdown. You will find that the layout of the ''Column'' window adapts to show special properties that are relevant to the selection.
<li>Now return to the initial selection of ''Table Direct''.
</ol>
===Configure the Data Relation established by the new Column===

# Let's have a closer look at the ''Constraint Type'' field. Check out the choices presented through the dropdown list.

The constraint type determines how the database will behave when a the record referenced by the field is deleted:
If the user or some process tries to delete an ''Office room'' that is still referenced by some ''Business Partner'' record we need to take some action to preserve the consistency of our data. Otherwise we might end up with a dangling reference in the ''Business Partner'' record.

* '''''No Action''''': This is the default. If there are any child records (i .e. any users referencing a room) then the database engine will not delete the record. Instead an error message will be produced whenever the user tries to delete that room.
* '''''Do Not Create''''': No constraint is created for this column. This is not recommended! Going without a constraint can lead to data errors, the parent can be deleted without any notice leaving orphan children in the database.
* '''''Cascade''''': When the parent record is deleted then the child records on this constraint will be deleted too (if possible) - this constraint is executed in the database, consequently the business model rules are not triggered (workflows, changelog, etc)
* '''''Model Cascade''''': When the parent record is deleted then the child records on this constraint will be deleted too (if possible) - this constraint is executed within iDempiere, so all business model rules are applied.
* '''''Set Null''''': When the parent record is deleted then the child records on this constraint will set to null (if possible)

<ol start="2">
<li>Set the ''Constraint Type'' field back to the default value ''No Action'' and save the new record.
<li>Hit the Synchronize Button and confirm the process dialog with OK to generate the new column in the database.
</ol>
A confirmation dialog will appear when the process has been completed. In the upper section it shows the SQL commands that the application has sent to the database engine. The lower section shows the response from the database which should basically be just an exact echo of the commands given above. This indicates that the commands were executed without errors.

<ol start="4">
<li>Hit OK to close the dialog and you are done.
</ol>

==Add the User Interface Elements==

===Add a new field to a factory provided window.===

We are now going to add a new ''Office Room'' field to the 'Business Partner > Business Partner' window tab.

# Go up one tab level to the ''Table'' view. To do that click ''Table'' in the breadcrumbs bar or hit ''ALT'' + ''Arrow UP'' on the keyboard.
# Now click the Label of the ''Window'' field to zoom over to that window.
# In the business partner window switch to the ''Business Partner'' subtab by hitting the ''Edit Record'' button in the subtab row. (Or hit ''ALT'' + ''Arrow Down'' on the keyboard.)
# [[File:Tutorial add Reference 02.png|border|right|472x472px]]Now click the ''Process'' button in the icon bar and select ''Create Fields'' from the context menu. The ''Create Fields'' process dialog will appear. [[File:Tutorial add Reference 03.png|border]]

When adding fields to a factory provided window it is always a good idea to restrict the number of fields that are created by the process. Many tables include columns that purposefully do not have a corresponding field in the edit window. We need to ensure that we do not generate fields for these columns too.

<ol start="5">
<li>We will avoid inadvertently creating fields for those columns by entering today's date in the date field. This will exclude any columns from the process that have been created earlier by somebody else.
<li>Now hit OK. A confirmation dialog will appear that lists the newly created fields.
</ol>

===Configure the Window Layout===

# We are again using the Tab editor to adapt the window layout. Open the editor through the context menu of the ''Process'' button.
# In the editor you will find the new ''Office Room'' editor field at the bottom of the page. Drag and drop it to a more convenient position.

With regards to our specification it does not make sense to assign a room to a business partner that is not also an employee. We can guide our users by only showing the new field when the ''Employee'' checkbox is ticked.

<ol start="3">
<li>[[File:Tutorial add Reference 01.png|border|right|487x487px]]With the focus still on the ''Office Room'' field enter '@IsEmployee@=Y' into the '''Display Logic''' field in the ''Property'' sidebar to the right of the edit area.
</ol>

===Side Note - The iDempiere Context===

What actually have we done here? To understand the meaning of the arcane text we have just entered it is necessary to dig a bit deeper and learn a bit about the iDempiere context.
* iDempiere makes all field values of the current window (among many other things) available as so called context variables. Each time the user enters a new value into field its corresponding variable in the iDempiere context will be updated immediately.
* The iDempiere context is just a long list of values. Each of these values is paired with a key that is needed to identify that value.
* To access a context value from the '''Display Logic''' field we just have to surround its key name with @ symbols.
The application will then replace the codified key name with the respective context value and then check wether the resulting statement is true or not.
The value of the '''Display Logic''' checkbox is 'Y' when it is ticked and 'N' when not.
So when we write '@IsEmployee@=Y' iDempiere will replace the '@IsEmployee@' part with a 'Y' when the checkbox is ticked.
The statement will then be 'Y=Y'. This is obviously true and because of that the ''Office Room'' field will be shown. Unticking the box changes the statement to 'N=Y' which is false and the field will be hidden.

===Configure the Office Room Identifier String===

ToDo

===Make selected Fields available to the Quick Entry Dialog===

As a last step we are now going to make a few of the fields in the ''Office Room'' window available to the ''Quick Entry'' dialog.
We have already used that dialog in the previous tutorial when we created the entity types for our custom columns.
Remember that we did not switch to the entity type window to do that. Instead we opened the context menu of the ''Entity Type'' field and selected ''New'' to bring up the quick entry dialog. We then were able to create the new types using that dialog.
# ToDo:Switch to Window, Tab and Field: Office Room
# In the Field subtab select the ''Room Number'' row and click the ''Edit Record'' button.
# Tick the ''Quick Entry'' checkbox in ''the Window > Tab > Field'' view that the window that has switched to. This makes the field available to the QuickEntry dialog.

Repeat that last step for both the ''Floor Number'' and ''Building Wing'' fields.

Hint: Do not forget to save your last edit. iDempiere will autosave any of your changes when you load another record into the active window or switch to a parent tab or subtab. Manual saving is required in all other cases. That is when you change the focus to any other tab in the hierarchy that is not a parent or child of the previous one.

==Conclusion==

Todo: List UI customization elements: new field in existing Window, QuickEntry Dialog enabled for new Element.
Todo: Login as client admin or user
Todo: Description Office Room Field in Business Partner Window
Todo: Usage QuickEntry

File:Tutorial add Reference 03.png

2021-05-26T09:59:36Z

Soundbytes:

Process Menu - Create Fields

File:Tutorial add Reference 02.png

2021-05-26T09:57:21Z

Soundbytes:

Create FIelds Dialog - insert date

Application Dictionary - Add Data Relations and Configure the Quick Entry Dialog

2021-05-26T09:54:40Z

Soundbytes: screenshot added

[[Category:Application Dictionary|P]]

__INDEX__

=Introduction=
This tutorial is brought to you by Andreas Sumerauer. If you have any questions, criticism or suggestions for improvement, feel free to join the discussion in the [https://groups.google.com/g/idempiere iDempiere google group.]

==Goal of this tutorial==
After finishing this tutorial you will have learned how to add Columns to existing tables.
You will be able to connect records from different tables in a useful way. This is done using data relations.
Finally you will learn how to create sophisticated user interface elements to manage these relations within iDempiere.
As in the previous tutorial we will again only use the iDempiere system user interface to create the additions to the database and the user interface.

==Prerequisites==
This tutorial builds on [[Application_Dictionary_-_Create_a_Custom_Table_and_Window|Create a Custom Table and Window]].
Before you start you should have successfully completed that first tutorial.
* Some knowledge of the basic concepts of relational data bases will be beneficial but is not required.
* You can greatly improve your learning experience through actively reproducing the steps given here. The customizations added during the course of the previous lesson are required for doing that.

==Example Specification==

To complete the example specification from the last tutorial we still need to create a data relation between the new ''Office Room'' table and the factory provided ''Business Partner'' table. This table holds the data of all the persons that our client's organizations are interacting with.
* That relation will be built through a new ''Office Room'' column that we are going to add to the ''Business Partner'' table together with a so called foreign key constraint that serves to keep the data consistent through any data changes that concern the newly defined relation. (Note that in iDempiere also an employee of the organization is a Business Partner.)
* On the user interface side we are going to add a new ''Office Room'' field to the ''Business Partner'' window.
* As a last step we are going to configure iDempiere's ''QuickEdit'' dialog. This will allow us to add or modify an employee's office room without having to switch away from the ''Business Partner'' window to the ''Office Room'' window.

==Conventions==

* This tutorial uses a numbered list whenever there are steps that need to be executed to implement the specified requirements.
* A bulleted list will be used for hints, explanations and background information.

=Steps=

==Add Database Elements==

===Add a new Column to the Business Partner Table===

Now it is time to create the relation from the existing database to the new ''Office Room'' table.
# Open the Table & Columnn window and load the AD_User table.
# Click the ''Create New'' Button ('+' icon) in the ''Column'' tab tool bar to open the ''Table > Column'' window with a new record.
# In the ''Element'' field enter ''SB_OfficeRoomID''. Remember that this Element was generated when we created the ''Office Room'' table in the previous tutorial. You will find that a number of fields will be autofilled.
Note that the System has entered the value ''Table Direct'' into the ''Relation'' field. Idempiere comes with a number of predefined relations to choose from. You can scroll through the ''Reference'' dropdown list to see all of them. The selected reference lets iDempiere know how to handle the data stored in the table column. It will determine:
* The data type in the data base and in the application
* How the Data is presented to the user.
* The UI elements that are presented to the user for manipulation and management of the stored data.

<ol start="4">
<li>You can try and explore some different reference types by selecting them from the dropdown. You will find that the layout of the ''Column'' window adapts to show special properties that are relevant to the selection.
<li>Now return to the initial selection of ''Table Direct''.
</ol>
===Configure the Data Relation established by the new Column===

# Let's have a closer look at the ''Constraint Type'' field. Check out the choices presented through the dropdown list.

The constraint type determines how the database will behave when a the record referenced by the field is deleted:
If the user or some process tries to delete an ''Office room'' that is still referenced by some ''Business Partner'' record we need to take some action to preserve the consistency of our data. Otherwise we might end up with a dangling reference in the ''Business Partner'' record.

* '''''No Action''''': This is the default. If there are any child records (i .e. any users referencing a room) then the database engine will not delete the record. Instead an error message will be produced whenever the user tries to delete that room.
* '''''Do Not Create''''': No constraint is created for this column. This is not recommended! Going without a constraint can lead to data errors, the parent can be deleted without any notice leaving orphan children in the database.
* '''''Cascade''''': When the parent record is deleted then the child records on this constraint will be deleted too (if possible) - this constraint is executed in the database, consequently the business model rules are not triggered (workflows, changelog, etc)
* '''''Model Cascade''''': When the parent record is deleted then the child records on this constraint will be deleted too (if possible) - this constraint is executed within iDempiere, so all business model rules are applied.
* '''''Set Null''''': When the parent record is deleted then the child records on this constraint will set to null (if possible)

<ol start="2">
<li>Set the ''Constraint Type'' field back to the default value ''No Action'' and save the new record.
<li>Hit the Synchronize Button and confirm the process dialog with OK to generate the new column in the database.
</ol>
A confirmation dialog will appear when the process has been completed. In the upper section it shows the SQL commands that the application has sent to the database engine. The lower section shows the response from the database which should basically be just an exact echo of the commands given above. This indicates that the commands were executed without errors.

<ol start="4">
<li>Hit OK to close the dialog and you are done.
</ol>

==Add the User Interface Elements==

===Add a new field to a factory provided window.===

We are now going to add a new ''Office Room'' field to the 'Business Partner > Business Partner' window tab.

# Go up one tab level to the ''Table'' view. To do that click ''Table'' in the breadcrumbs bar or hit ''ALT'' + ''Arrow UP'' on the keyboard.
# Now click the Label of the ''Window'' field to zoom over to that window.
# In the business partner window switch to the ''Business Partner'' subtab by hitting the ''Edit Record'' button in the subtab row. (Or hit ''ALT'' + ''Arrow Down'' on the keyboard.)
# Now click the ''Process'' button in the icon bar and select ''Create Fields'' from the context menu. The ''Create Fields'' process dialog will appear.

When adding fields to a factory provided window it is always a good idea to restrict the number of fields that are created by the process. Many tables include columns that purposefully do not have a corresponding field in the edit window. We need to ensure that we do not generate fields for these columns too.

<ol start="5">
<li>We will avoid inadvertently creating fields for those columns by entering today's date in the date field. This will exclude any columns from the process that have been created earlier by somebody else.
<li>Now hit OK. A confirmation dialog will appear that lists the newly created fields.
</ol>

===Configure the Window Layout===

# We are again using the Tab editor to adapt the window layout. Open the editor through the context menu of the ''Process'' button.
# In the editor you will find the new ''Office Room'' editor field at the bottom of the page. Drag and drop it to a more convenient position.

With regards to our specification it does not make sense to assign a room to a business partner that is not also an employee. We can guide our users by only showing the new field when the ''Employee'' checkbox is ticked.

<ol start="3">
<li>[[File:Tutorial add Reference 01.png|border|right|466x466px]]With the focus still on the ''Office Room'' field enter '@IsEmployee@=Y' into the '''Display Logic''' field in the ''Property'' sidebar to the right of the edit area.
</ol>

===Side Note - The iDempiere Context===

What actually have we done here? To understand the meaning of the arcane text we have just entered it is necessary to dig a bit deeper and learn a bit about the iDempiere context.
* iDempiere makes all field values of the current window (among many other things) available as so called context variables. Each time the user enters a new value into field its corresponding variable in the iDempiere context will be updated immediately.
* The iDempiere context is just a long list of values. Each of these values is paired with a key that is needed to identify that value.
* To access a context value from the '''Display Logic''' field we just have to surround its key name with @ symbols.
The application will then replace the codified key name with the respective context value and then check wether the resulting statement is true or not.
The value of the '''Display Logic''' checkbox is 'Y' when it is ticked and 'N' when not.
So when we write '@IsEmployee@=Y' iDempiere will replace the '@IsEmployee@' part with a 'Y' when the checkbox is ticked.
The statement will then be 'Y=Y'. This is obviously true and because of that the ''Office Room'' field will be shown. Unticking the box changes the statement to 'N=Y' which is false and the field will be hidden.

===Configure the Office Room Identifier String===

ToDo

===Make selected Fields available to the Quick Entry Dialog===

As a last step we are now going to make a few of the fields in the ''Office Room'' window available to the ''Quick Entry'' dialog.
We have already used that dialog in the previous tutorial when we created the entity types for our custom columns.
Remember that we did not switch to the entity type window to do that. Instead we opened the context menu of the ''Entity Type'' field and selected ''New'' to bring up the quick entry dialog. We then were able to create the new types using that dialog.
# ToDo:Switch to Window, Tab and Field: Office Room
# In the Field subtab select the ''Room Number'' row and click the ''Edit Record'' button.
# Tick the ''Quick Entry'' checkbox in ''the Window > Tab > Field'' view that the window that has switched to. This makes the field available to the QuickEntry dialog.

Repeat that last step for both the ''Floor Number'' and ''Building Wing'' fields.

Hint: Do not forget to save your last edit. iDempiere will autosave any of your changes when you load another record into the active window or switch to a parent tab or subtab. Manual saving is required in all other cases. That is when you change the focus to any other tab in the hierarchy that is not a parent or child of the previous one.

==Conclusion==

Todo: List UI customization elements: new field in existing Window, QuickEntry Dialog enabled for new Element.
Todo: Login as client admin or user
Todo: Description Office Room Field in Business Partner Window
Todo: Usage QuickEntry

File:Tutorial add Reference 01.png

2021-05-26T09:53:31Z

Soundbytes:

Tab Editor - Display Logic

Application Dictionary - Add Data Relations and Configure the Quick Entry Dialog

2021-05-25T23:22:32Z

Soundbytes: Created page with "P __INDEX__ =Introduction= This tutorial is brought to you by Andreas Sumerauer. If you have any questions, criticism or suggestions for..."

[[Category:Application Dictionary|P]]

__INDEX__

=Introduction=
This tutorial is brought to you by Andreas Sumerauer. If you have any questions, criticism or suggestions for improvement, feel free to join the discussion in the [https://groups.google.com/g/idempiere iDempiere google group.]

==Goal of this tutorial==
After finishing this tutorial you will have learned how to add Columns to existing tables.
You will be able to connect records from different tables in a useful way. This is done using data relations.
Finally you will learn how to create sophisticated user interface elements to manage these relations within iDempiere.
As in the previous tutorial we will again only use the iDempiere system user interface to create the additions to the database and the user interface.

==Prerequisites==
This tutorial builds on [[Application_Dictionary_-_Create_a_Custom_Table_and_Window|Create a Custom Table and Window]].
Before you start you should have successfully completed that first tutorial.
* Some knowledge of the basic concepts of relational data bases will be beneficial but is not required.
* You can greatly improve your learning experience through actively reproducing the steps given here. The customizations added during the course of the previous lesson are required for doing that.

==Example Specification==

To complete the example specification from the last tutorial we still need to create a data relation between the new ''Office Room'' table and the factory provided ''Business Partner'' table. This table holds the data of all the persons that our client's organizations are interacting with.
* That relation will be built through a new ''Office Room'' column that we are going to add to the ''Business Partner'' table together with a so called foreign key constraint that serves to keep the data consistent through any data changes that concern the newly defined relation. (Note that in iDempiere also an employee of the organization is a Business Partner.)
* On the user interface side we are going to add a new ''Office Room'' field to the ''Business Partner'' window.
* As a last step we are going to configure iDempiere's ''QuickEdit'' dialog. This will allow us to add or modify an employee's office room without having to switch away from the ''Business Partner'' window to the ''Office Room'' window.

==Conventions==

* This tutorial uses a numbered list whenever there are steps that need to be executed to implement the specified requirements.
* A bulleted list will be used for hints, explanations and background information.

=Steps=

==Add Database Elements==

===Add a new Column to the Business Partner Table===

Now it is time to create the relation from the existing database to the new ''Office Room'' table.
# Open the Table & Columnn window and load the AD_User table.
# Click the ''Create New'' Button ('+' icon) in the ''Column'' tab tool bar to open the ''Table > Column'' window with a new record.
# In the ''Element'' field enter ''SB_OfficeRoomID''. Remember that this Element was generated when we created the ''Office Room'' table in the previous tutorial. You will find that a number of fields will be autofilled.
Note that the System has entered the value ''Table Direct'' into the ''Relation'' field. Idempiere comes with a number of predefined relations to choose from. You can scroll through the ''Reference'' dropdown list to see all of them. The selected reference lets iDempiere know how to handle the data stored in the table column. It will determine:
* The data type in the data base and in the application
* How the Data is presented to the user.
* The UI elements that are presented to the user for manipulation and management of the stored data.

<ol start="4">
<li>You can try and explore some different reference types by selecting them from the dropdown. You will find that the layout of the ''Column'' window adapts to show special properties that are relevant to the selection.
<li>Now return to the initial selection of ''Table Direct''.
</ol>
===Configure the Data Relation established by the new Column===

# Let's have a closer look at the ''Constraint Type'' field. Check out the choices presented through the dropdown list.

The constraint type determines how the database will behave when a the record referenced by the field is deleted:
If the user or some process tries to delete an ''Office room'' that is still referenced by some ''Business Partner'' record we need to take some action to preserve the consistency of our data. Otherwise we might end up with a dangling reference in the ''Business Partner'' record.

* '''''No Action''''': This is the default. If there are any child records (i .e. any users referencing a room) then the database engine will not delete the record. Instead an error message will be produced whenever the user tries to delete that room.
* '''''Do Not Create''''': No constraint is created for this column. This is not recommended! Going without a constraint can lead to data errors, the parent can be deleted without any notice leaving orphan children in the database.
* '''''Cascade''''': When the parent record is deleted then the child records on this constraint will be deleted too (if possible) - this constraint is executed in the database, consequently the business model rules are not triggered (workflows, changelog, etc)
* '''''Model Cascade''''': When the parent record is deleted then the child records on this constraint will be deleted too (if possible) - this constraint is executed within iDempiere, so all business model rules are applied.
* '''''Set Null''''': When the parent record is deleted then the child records on this constraint will set to null (if possible)

<ol start="2">
<li>Set the ''Constraint Type'' field back to the default value ''No Action'' and save the new record.
<li>Hit the Synchronize Button and confirm the process dialog with OK to generate the new column in the database.
</ol>
A confirmation dialog will appear when the process has been completed. In the upper section it shows the SQL commands that the application has sent to the database engine. The lower section shows the response from the database which should basically be just an exact echo of the commands given above. This indicates that the commands were executed without errors.

<ol start="4">
<li>Hit OK to close the dialog and you are done.
</ol>

==Add the User Interface Elements==

===Add a new field to a factory provided window.===

We are now going to add a new ''Office Room'' field to the 'Business Partner > Business Partner' window tab.

# Go up one tab level to the ''Table'' view. To do that click ''Table'' in the breadcrumbs bar or hit ''ALT'' + ''Arrow UP'' on the keyboard.
# Now click the Label of the ''Window'' field to zoom over to that window.
# In the business partner window switch to the ''Business Partner'' subtab by hitting the ''Edit Record'' button in the subtab row. (Or hit ''ALT'' + ''Arrow Down'' on the keyboard.)
# Now click the ''Process'' button in the icon bar and select ''Create Fields'' from the context menu. The ''Create Fields'' process dialog will appear.

When adding fields to a factory provided window it is always a good idea to restrict the number of fields that are created by the process. Many tables include columns that purposefully do not have a corresponding field in the edit window. We need to ensure that we do not generate fields for these columns too.

<ol start="5">
<li>We will avoid inadvertently creating fields for those columns by entering today's date in the date field. This will exclude any columns from the process that have been created earlier by somebody else.
<li>Now hit OK. A confirmation dialog will appear that lists the newly created fields.
</ol>

===Configure the Window Layout===

# We are again using the Tab editor to adapt the window layout. Open the editor through the context menu of the ''Process'' button.
# In the editor you will find the new ''Office Room'' editor field at the bottom of the page. Drag and drop it to a more convenient position.

With regards to our specification it does not make sense to assign a room to a business partner that is not also an employee. We can guide our users by only showing the new field when the ''Employee'' checkbox is ticked.

<ol start="3">
<li>With the focus still on the ''Office Room'' field enter '@IsEmployee@=Y' into the '''Display Logic''' field in the ''Property'' sidebar to the right of the edit area.
</ol>

===Side Note - The iDempiere Context===

What actually have we done here? To understand the meaning of the arcane text we have just entered it is necessary to dig a bit deeper and learn a bit about the iDempiere context.
* iDempiere makes all field values of the current window (among many other things) available as so called context variables. Each time the user enters a new value into field its corresponding variable in the iDempiere context will be updated immediately.
* The iDempiere context is just a long list of values. Each of these values is paired with a key that is needed to identify that value.
* To access a context value from the '''Display Logic''' field we just have to surround its key name with @ symbols.
The application will then replace the codified key name with the respective context value and then check wether the resulting statement is true or not.
The value of the '''Display Logic''' checkbox is 'Y' when it is ticked and 'N' when not.
So when we write '@IsEmployee@=Y' iDempiere will replace the '@IsEmployee@' part with a 'Y' when the checkbox is ticked.
The statement will then be 'Y=Y'. This is obviously true and because of that the ''Office Room'' field will be shown. Unticking the box changes the statement to 'N=Y' which is false and the field will be hidden.

===Configure the Office Room Identifier String===

ToDo

===Make selected Fields available to the Quick Entry Dialog===

As a last step we are now going to make a few of the fields in the ''Office Room'' window available to the ''Quick Entry'' dialog.
We have already used that dialog in the previous tutorial when we created the entity types for our custom columns.
Remember that we did not switch to the entity type window to do that. Instead we opened the context menu of the ''Entity Type'' field and selected ''New'' to bring up the quick entry dialog. We then were able to create the new types using that dialog.
# ToDo:Switch to Window, Tab and Field: Office Room
# In the Field subtab select the ''Room Number'' row and click the ''Edit Record'' button.
# Tick the ''Quick Entry'' checkbox in ''the Window > Tab > Field'' view that the window that has switched to. This makes the field available to the QuickEntry dialog.

Repeat that last step for both the ''Floor Number'' and ''Building Wing'' fields.

Hint: Do not forget to save your last edit. iDempiere will autosave any of your changes when you load another record into the active window or switch to a parent tab or subtab. Manual saving is required in all other cases. That is when you change the focus to any other tab in the hierarchy that is not a parent or child of the previous one.

==Conclusion==

Todo: List UI customization elements: new field in existing Window, QuickEntry Dialog enabled for new Element.
Todo: Login as client admin or user
Todo: Description Office Room Field in Business Partner Window
Todo: Usage QuickEntry

Application Dictionary - Create a Custom Table and Window

2021-05-24T12:30:32Z

Soundbytes: typo

[[Category:Application Dictionary|P]]

__INDEX__

=Introduction=
This tutorial is brought to you by Andreas Sumerauer. If you have any questions, criticism or suggestions for improvement, feel free to join the discussion in the [https://groups.google.com/g/idempiere iDempiere google group.]

==Goal of this tutorial==
This tutorial will enable you to create your own custom Data Tables that are fully integrated within the iDempiere application framework.
You will be able to do that without writing a single line of SQL or Java code. Instead you will be introduced to the iDempiere Application Dictionary that provides the tools for the creation of wide ranging customizations and extensions to the iDempiere application.

==Example Specification==
Let's say we want iDempiere to tell us in which office room each employee's workspace is.
In the course of this tutorial we are going to lay the groundwork for this example specification by adding a new table to hold our office room data and a window to manage the data stored within that table.

==Prerequisites==
To get the most out of this tutorial it is highly recommended that before you start you have made yourself familiar with the idempiere user interface.
 Some basic understanding of the concept of the iDempiere application dictionary will be helpful but is not strictly required.
 You can greatly improve your learning experience through actively reproducing the Steps. For that you will need to have System administrator access to a sandbox iDempiere installation.

=Steps=

==Add Database Elements==
[[File:Tutorial TableWindowCreation 01.png|alt=Table and Column window|border|right|386x386px]]

===Create a new Table Definition===
We will start by adding the Office Room table to our data base.
Log in as the SuperUser. Then open the Table & Column window and add a new table.
Now fill in the following fields:
* DB Table Name: ''SB_OfficeRoom''
* Name: ''Office Room''
* Data Access Level: ''Client + Organization''
* Save the new record.

[[File:Tutorial TableWindowCreation 02.png.png|border|right|325x325px]]
[[File:Tutorial TableWindowCreation 03.png.png|thumb|379x379px]]

====Generate Mandatory Columns====

We will now add a number of columns to the new table. A table that has a window is required to have a number of mandatory columns that are used by iDemiere for house keeping purposes.
These columns can be generated very easily by copying the table schema from another existing table that meets those requirements:
* Click the process button (gear icon) in the tool bar.
* Select Copy Columns from Table. A good candidate to be used as a template would be ''C_Subscription_Delivery''. Enter that name into the dialog that pops up and hit OK. The newly generated columns will appear in the Column sub tab right under the main edit area.
* We are going to need all of these columns except for ''C_Subscription_ID''. To remove it tick the checkbox at the left side of the column's row and hit the ''Delete Record'' button ('-' icon).

====Add Custom Columns to the Table====

Now add the ''RoomNo'' column:
* Click the ''Create New'' Button ('+' icon) in the ''Column'' tab tool bar. The ''Table > Column'' window is opened with the new record loaded.
* [[File:Tutorial TableWindowCreation 04.png.png|right|239x239px]]Rightclick the Entity Type field and select new from the context menu.
* Fill in the required fields in the QuickEntry dialog then hit OK:
** DB Column Name: ''RoomNo''
** Name: ''Room Number''
** Print Text: ''Room Number''
* Back in the Column window fill in these fiels then save the new record:
** Reference: ''String''
** Length: ''30''

Obviously it does not make sense to have a room without a number. So let's make the Room Number field mandatory:

:* Tick the ''Mandatory'' checkbox. A new ''Office Room'' record can now only be saved when the ''Room Number'' field is not empty.

Repeat the above steps to create two more new columns: ''FloorNo'' (''Floor Number'') and ''BuildingWing'' (''Building Wing''). Leave the ''Mandatory'' checkbox unticked for these two columns.

[[File:Tutorial TableWindowCreation 05.png.png|border]]

===Generate the Table within the Database===

The new table and its columns are now defined as part of the iDempiere application dictionary.
To create all of them in the database hit the ''Synchronize Column'' button in the ''Table > Column'' window.
Note that this button works a bit differently for a table that already exists in the database.
It will then only create or update the currently edited column.

===Add a Unique Constraint===

Since our customization only manages a single building we can safely assume that room numbers will be unique.
To avoid user errors we are going to create a UNIQUE constraint on that column. We have to make sure that different tenants can still have rooms with the same number. Because of that the constraint has to include the ''AD_Client_ID'' column as well.
* In the subtab bar click the ''Table Index'' tab and then the ''Create New'' button of that tab. [[File:Tutorial TableWindowCreation 06.png.png|border]]
* Enter ''Unique_RoomNo_per_Tenant'' into the Name field of the ''Table > Table Index'' window that has just opened.
* Tick both the ''Create Constraint'' and the ''Unique'' checkboxes.
* Save the new record.
* Now we need to add the index columns. Hit the ''Create New'' button of the ''Index Column'' subtab. [[File:Tutorial TableWindowCreation 07.png|border]]
* The edit view will switch to ''Table > Table Index > Index Column''. Here enter ''RoomNo'' into the ''Column'' field.
* Save the new record and create another one for the ''AD_Client_ID'' column.
* Now switch back to the ''Table > Table Index'' view and click the ''Index Validate'' button. This will generate the constraint within the database. [[File:Tutorial TableWindowCreation 08.png|border]]

==Add the User Interface Elements==

===Generate Window, Tab and Fields as well as a Menu Entry for the new Table===
[[File:Tutorial TableWindowCreation 09.png|border|right]]
We now go back to the ''Table'' window. Rightclick ''Table'' in the breadcrumb row or hit ''ALT+Arrow Up'' on the keyboard.

Click the Process button in the tool bar and select ''Create Window, Tab and Field from Table'' from the context menu.

In the dialog that appears tick the ''Create Menu'' checkbox and hit OK.

[[File:Tutorial TableWindowCreation 10.png|border|511x511px]]

After the successfull completion of the process a confirmation dialog will pop up.
In that dialog click on ''Tab: Office Room''. This will open a new ''Window > Tab'' window.

[[File:Tutorial TableWindowCreation 11.png|border|375x375px]]

===Improve the Tab Layout===

The new Tab's layout has been generated using some default settings. Let's see if we can improve it a bit.
* hit the ''Process'' button in the toolbar of the new window and select ''Tab Editor''. [[File:Tutorial TableWindowCreation 12.png|border]]
* This opens the ''Tab Editor'' dialog. [[File:Tutorial TableWindowCreation 13.png|border|897x897px]]

The Tab editor is a very powerful tool that can't be fully covered in the course of this tutorial. We will now just reposition some of the layout elemnts. Rightclick and hold the label of the ''Building Wing'' field then move the mouse to the right of the ''Room Number'' field and release the mouse button. You have just dragged and dropped the ''Building Wing'' field to a new position.
* Now drag and drop the ''Active'' checkbox to the right of the ''Floor Number'' field.
* We want the checkbox to be vertically aligned with the editor fields in the layout column. If you find that the checkbox has landed too close to the ''Floor Number'' field change the X-Position value in the Property sidebar to the right from 4 to 5 and hit ''Enter''. This will move he checkbox to the desired position. [[File:Tutorial TableWindowCreation 14.png|border|838x838px]]
* Finally hit the ''OK'' button to save your edits and close the dialog.

=Conclusion=

Now lets view the results.
* log in to the Application as GardenAdmin. You might have to log out before in case you are still loged in as the system user
* Type ''Office Room'' into the menu filter field. [[File:Tutorial TableWindowCreation 15.png|border]] The Menu will pop up with only the ''Office Room'' entry visible.
* Click the menu entry to open the ''Office Room'' window. Note that the mandatory ''Room Number'' field is lined red while it is empty. [[File:Tutorial TableWindowCreation 16.png|border]]

Congregulations! You have finished this tutorial. You are now able to create your own custom tables complete with its own window and menu entry within iDempiere.

Application Dictionary - Create a Custom Table and Window

2021-05-24T12:29:13Z

Soundbytes:

[[Category:Application Dictionary|P]]

__INDEX__

=Introduction=
This tutorial is brought to you by Andreas Sumerauer. If you have any questions, criticism or suggestions for improvement, feel free to join the discussion in the [https://groups.google.com/g/idempiere iDempiere google group.]

==Goal of this tutorial==
This tutorial will enable you to create your own custom Data Tables that are fully integrated within the iDempiere application framework.
You will be able to do that without writing a single line of SQL or Java code. Instead you will be introduced to the iDempiere Application Dictionary that provides the tools for the creation of wide ranging customizations and extensions to the iDempiere application.

==Example Specification==
Let's say we want iDempiere to tell us in which office room each employee's workspace is.
In the course of this tutorial we are going to lay the groundwork for this example specification by adding a new table to hold our office room data and a window to manage the data stored within that table.

==Prerequisites==
To get the most out of this tutorial it is highly recommended that before you start you have made yourself familiar with the idempiere user interface.
 Some basic understanding of the concept of the iDempiere application dictionary will be helpful but is not strictly required.
 You can greatly improve your learning experience through actively reproducing the Steps. For that you will need to have System administrator access to a sandbox iDempiere installation.

=Steps=

==Add Database Elements==
[[File:Tutorial TableWindowCreation 01.png|alt=Table and Column window|border|right|386x386px]]

===Create a new Table Definition===
We will start by adding the Office Room table to our data base.
Log in as the SuperUser. Then open the Table & Column window and add a new table.
Now fill in the following fields:
* DB Table Name: ''SB_OfficeRoom''
* Name: ''Office Room''
* Data Access Level: ''Client + Organization''
* Save the new record.

[[File:Tutorial TableWindowCreation 02.png.png|border|right|325x325px]]
[[File:Tutorial TableWindowCreation 03.png.png|thumb|379x379px]]

====Generate Mandatory Columns====

We will now add a number of columns to the new table. A table that has a window is required to have a number of mandatory columns that are used by iDemiere for house keeping purposes.
These columns can be generated very easily by copying the table schema from another existing table that meets those requirements:
* Click the process button (gear icon) in the tool bar.
* Select Copy Columns from Table. A good candidate to be used as a template would be ''C_Subscription_Delivery''. Enter that name into the dialog that pops up and hit OK. The newly generated columns will appear in the Column sub tab right under the main edit area.
* We are going to need all of these columns except for ''C_Subscription_ID''. To remove it tick the checkbox at the left side of the column's row and hit the ''Delete Record'' button ('-' icon).

====Add Custom Columns to the Table====

Now add the ''RoomNo'' column:
* Click the ''Create New'' Button ('+' icon) in the ''Column'' tab tool bar. The ''Table > Column'' window is opened with the new record loaded.
* [[File:Tutorial TableWindowCreation 04.png.png|right|239x239px]]Rightclick the Entity Type field and select new from the context menu.
* Fill in the required fields in the QuickEntry dialog then hit OK:
** DB Column Name: ''RoomNo''
** Name: ''Room Number''
** Print Text: ''Room Number''
* Back in the Column window fill in these fiels then save the new record:
** Reference: ''String''
** Length: ''30''

Obviously it does not make sense to have a room without a number. So let's make the Room Number field mandatory:

:* Tick the ''Mandatory'' checkbox. A new ''Office Room'' record can now only be saved when the ''Room Number'' field is not empty.

Repeat the above steps to create two more new columns: ''FloorNo'' (''Floor Number'') and ''BuildingWing'' (''Building Wing''). Leave the ''Mandatory'' checkbox unticked for these two columns.

[[File:Tutorial TableWindowCreation 05.png.png|border]]

===Generate the Table within the Database===

The new table and its columns are now defined as part of the iDempiere application dictionary.
To create all of them in the database hit the ''Synchronize Column'' button in the ''Table > Column'' window.
Note that this button works a bit differently for a table that already exists in the database.
It will then only create or update the currently edited column.

===Add a Unique Constraint===

Since our customization only manages a single building we can safely assume that room numbers will be unique.
To avoid user errors we are going to create a UNIQUE constraint on that column. We have to make sure that different tenants can still have rooms with the same number. Because of that the constraint has to include the ''AD_Client_ID'' column as well.
* In the subtab bar click the ''Table Index'' tab and then the ''Create New'' button of that tab. [[File:Tutorial TableWindowCreation 06.png.png|border]]
* Enter ''Unique_RoomNo_per_Tenant'' into the Name field of the ''Table > Table Index'' window that has just opened.
* Tick both the ''Create Constraint'' and the ''Unique'' checkboxes.
* Save the new record.
* Now we need to add the index columns. Hit the ''Create New'' button of the ''Index Column'' subtab. [[File:Tutorial TableWindowCreation 07.png|border]]
* The edit view will switch to ''Table > Table Index > Index Column''. Here enter ''RoomNo'' into the ''Column'' field.
* Save the new record and create another one for the ''AD_Client_ID'' column.
* Now switch back to the ''Table > Table Index'' view and click the ''Index Validate'' button. This will generate the constraint within the database. [[File:Tutorial TableWindowCreation 08.png|border]]

==Add the User Interface Elements==

===Generate Window, Tab and Fields as well as a Menu Entry for the new Table===
[[File:Tutorial TableWindowCreation 09.png|border|right]]
We now go back to the ''Table'' window. Rightclick ''Table'' in the breadcrumb row or hit ''ALT+Arrow Up'' on the keyboard.

Click the Process button in the tool bar and select ''Create Window, Tab and Field from Table'' from the context menu.

In the dialog that appears tick the ''Create Menu'' checkbox and hit OK.

[[File:Tutorial TableWindowCreation 10.png|border|511x511px]]

After the successfull completion of the process a confirmation dialog will pop up.
In that dialog click on ''Tab: Office Room''. This will open a new ''Window > Tab'' window.

[[File:Tutorial TableWindowCreation 11.png|border|375x375px]]

===Improve the Tab Layout===

The new Tab's layout has been generated using some default settings. Let's see if we can improve it a bit.
* hit the ''Process'' button in the toolbar of the new window and select ''Tab Editor''. [[File:Tutorial TableWindowCreation 12.png|border]]
* This opens the ''Tab Editor'' dialog. [[File:Tutorial TableWindowCreation 13.png|border|897x897px]]

The Tab editor is a very powerful tool that can't be fully covered in the course of this tutorial. We will now just reposition some of the layout elemnts. Rightclick and hold the label of the ''Building Wing'' field then move the mouse to the right of the ''Room Number'' field and release the mouse button. You have just dragged and dropped the ''Building Wing'' field to a new position.
* Now drag and drop the ''Active'' checkbox to the right of the ''Floor Number'' field.
* We want the checkbox to be vertically aligned with the editor fields in the layout column. If you find that the checkbox has landed too close to the ''Floor Number'' field change the X-Position value in the Property sidebar to the right from 4 to 5 and hit ''Enter''. This will move he checkbox to the desired position. [[File:Tutorial TableWindowCreation 14.png|border|838x838px]]
* Finally hit the ''OK'' button to save your edits and close the dialog.

=Conclusion=

Now lets view the results.
* log in to the Application as GardenAdmin. You might have to log out before in case you are still loged in as the system user
* Type ''Office Room'' into the menu filter field. [[File:Tutorial TableWindowCreation 15.png|border]] The Menu will pop up with only the ''Office Room'' entry visible.
* Click the entry to open the ''Office Room'' window. Note that the mandatory ''Room Number'' field is lined red while it is empty. [[File:Tutorial TableWindowCreation 16.png|border]]

Congregulations! You have finished this tutorial. You are now able to create your own custom tables complete with its own window and menu entry within iDempiere.

Application Dictionary - Create a Custom Table and Window

2021-05-24T12:27:51Z

Soundbytes: even more screenshots added

[[Category:Application Dictionary|P]]

__INDEX__

=Introduction=
This tutorial is brought to you by Andreas Sumerauer. If you have any questions, criticism or suggestions for improvement, feel free to join the discussion in the [https://groups.google.com/g/idempiere iDempiere google group.]

==Goal of this tutorial==
This tutorial will enable you to create your own custom Data Tables that are fully integrated within the iDempiere application framework.
You will be able to do that without writing a single line of SQL or Java code. Instead you will be introduced to the iDempiere Application Dictionary that provides the tools for the creation of wide ranging customizations and extensions to the iDempiere application.

==Example Specification==
Let's say we want iDempiere to tell us in which office room each employee's workspace is.
In the course of this tutorial we are going to lay the groundwork for this example specification by adding a new table to hold our office room data and a window to manage the data stored within that table.

==Prerequisites==
To get the most out of this tutorial it is highly recommended that before you start you have made yourself familiar with the idempiere user interface.
 Some basic understanding of the concept of the iDempiere application dictionary will be helpful but is not strictly required.
 You can greatly improve your learning experience through actively reproducing the Steps. For that you will need to have System administrator access to a sandbox iDempiere installation.

=Steps=

==Add Database Elements==
[[File:Tutorial TableWindowCreation 01.png|alt=Table and Column window|border|right|386x386px]]

===Create a new Table Definition===
We will start by adding the Office Room table to our data base.
Log in as the SuperUser. Then open the Table & Column window and add a new table.
Now fill in the following fields:
* DB Table Name: ''SB_OfficeRoom''
* Name: ''Office Room''
* Data Access Level: ''Client + Organization''
* Save the new record.

[[File:Tutorial TableWindowCreation 02.png.png|border|right|325x325px]]
[[File:Tutorial TableWindowCreation 03.png.png|thumb|379x379px]]

====Generate Mandatory Columns====

We will now add a number of columns to the new table. A table that has a window is required to have a number of mandatory columns that are used by iDemiere for house keeping purposes.
These columns can be generated very easily by copying the table schema from another existing table that meets those requirements:
* Click the process button (gear icon) in the tool bar.
* Select Copy Columns from Table. A good candidate to be used as a template would be ''C_Subscription_Delivery''. Enter that name into the dialog that pops up and hit OK. The newly generated columns will appear in the Column sub tab right under the main edit area.
* We are going to need all of these columns except for ''C_Subscription_ID''. To remove it tick the checkbox at the left side of the column's row and hit the ''Delete Record'' button ('-' icon).

====Add Custom Columns to the Table====

Now add the ''RoomNo'' column:
* Click the ''Create New'' Button ('+' icon) in the ''Column'' tab tool bar. The ''Table > Column'' window is opened with the new record loaded.
* [[File:Tutorial TableWindowCreation 04.png.png|right|239x239px]]Rightclick the Entity Type field and select new from the context menu.
* Fill in the required fields in the QuickEntry dialog then hit OK:
** DB Column Name: ''RoomNo''
** Name: ''Room Number''
** Print Text: ''Room Number''
* Back in the Column window fill in these fiels then save the new record:
** Reference: ''String''
** Length: ''30''

Obviously it does not make sense to have a room without a number. So let's make the Room Number field mandatory:

:* Tick the ''Mandatory'' checkbox. A new ''Office Room'' record can now only be saved when the ''Room Number'' field is not empty.

Repeat the above steps to create two more new columns: ''FloorNo'' (''Floor Number'') and ''BuildingWing'' (''Building Wing''). Leave the ''Mandatory'' checkbox unticked for these two columns.

[[File:Tutorial TableWindowCreation 05.png.png|border]]

===Generate the Table within the Database===

The new table and its columns are now defined as part of the iDempiere application dictionary.
To create all of them in the database hit the ''Synchronize Column'' button in the ''Table > Column'' window.
Note that this button works a bit differently for a table that already exists in the database.
It will then only create or update the currently edited column.

===Add a Unique Constraint===

Since our customization only manages a single building we can safely assume that room numbers will be unique.
To avoid user errors we are going to create a UNIQUE constraint on that column. We have to make sure that different tenants can still have rooms with the same number. Because of that the constraint has to include the ''AD_Client_ID'' column as well.
* In the subtab bar click the ''Table Index'' tab and then the ''Create New'' button of that tab. [[File:Tutorial TableWindowCreation 06.png.png|border]]
* Enter ''Unique_RoomNo_per_Tenant'' into the Name field of the ''Table > Table Index'' window that has just opened.
* Tick both the ''Create Constraint'' and the ''Unique'' checkboxes.
* Save the new record.
* Now we need to add the index columns. Hit the ''Create New'' button of the ''Index Column'' subtab. [[File:Tutorial TableWindowCreation 07.png|border]]
* The edit view will switch to ''Table > Table Index > Index Column''. Here enter ''RoomNo'' into the ''Column'' field.
* Save the new record and create another one for the ''AD_Client_ID'' column.
* Now switch back to the ''Table > Table Index'' view and click the ''Index Validate'' button. This will generate the constraint within the database. [[File:Tutorial TableWindowCreation 08.png|border]]

==Add the User Interface Elements==

===Generate Window, Tab and Fields as well as a Menu Entry for the new Table===
[[File:Tutorial TableWindowCreation 09.png|border|right]]
We now go back to the ''Table'' window. Rightclick ''Table'' in the breadcrumb row or hit ''ALT+Arrow Up'' on the keyboard.

Click the Process button in the tool bar and select ''Create Window, Tab and Field from Table'' from the context menu.

In the dialog that appears tick the ''Create Menu'' checkbox and hit OK.

[[File:Tutorial TableWindowCreation 10.png|border|511x511px]]

After the successfull completion of the process a confirmation dialog will pop up.
In that dialog click on ''Tab: Office Room''. This will open a new ''Window > Tab'' window.

[[File:Tutorial TableWindowCreation 11.png|border|375x375px]]

===Improve the Tab Layout===

The new Tab's layout has been generated using some default settings. Let's see if we can improve it a bit.

[[File:Tutorial TableWindowCreation 12.png|border]]
* hit the ''Process'' button in the toolbar of the new window and select ''Tab Editor''.
* This opens the ''Tab Editor'' dialog.

[[File:Tutorial TableWindowCreation 13.png|border|897x897px]]

The Tab editor is a very powerful tool that can't be fully covered in the course of this tutorial. We will now just reposition some of the layout elemnts. Rightclick and hold the label of the ''Building Wing'' field then move the mouse to the right of the ''Room Number'' field and release the mouse button. You have just dragged and dropped the ''Building Wing'' field to a new position.
* Now drag and drop the ''Active'' checkbox to the right of the ''Floor Number'' field.
* We want the checkbox to be vertically aligned with the editor fields in the layout column. If you find that the checkbox has landed too close to the ''Floor Number'' field change the X-Position value in the Property sidebar to the right from 4 to 5 and hit ''Enter''. This will move he checkbox to the desired position. [[File:Tutorial TableWindowCreation 14.png|border|838x838px]]
* Finally hit the ''OK'' button to save your edits and close the dialog.

=Conclusion=

Now lets view the results.
* log in to the Application as GardenAdmin. You might have to log out before in case you are still loged in as the system user
* Type ''Office Room'' into the menu filter field. [[File:Tutorial TableWindowCreation 15.png|border]] The Menu will pop up with only the ''Office Room'' entry visible.
* Click the entry to open the ''Office Room'' window. Note that the mandatory ''Room Number'' field is lined red while it is empty. [[File:Tutorial TableWindowCreation 16.png|border]]

Congregulations! You have finished this tutorial. You are now able to create your own custom tables complete with its own window and menu entry within iDempiere.

File:Tutorial TableWindowCreation 16.png

2021-05-24T12:26:15Z

Soundbytes:

Office Room Window

File:Tutorial TableWindowCreation 15.png

2021-05-24T12:24:12Z

Soundbytes:

iDempiere Menu Filter

File:Tutorial TableWindowCreation 14.png

2021-05-24T12:22:32Z

Soundbytes:

Tab Editor - X-Position

File:Tutorial TableWindowCreation 13.png

2021-05-24T12:20:10Z

Soundbytes:

Tab Editor

File:Tutorial TableWindowCreation 12.png

2021-05-24T12:18:39Z

Soundbytes:

Window, Tab & Field - Process Menu

File:Tutorial TableWindowCreation 11.png

2021-05-24T12:16:12Z

Soundbytes:

Confirmation Dialog

File:Tutorial TableWindowCreation 10.png

2021-05-24T12:14:14Z

Soundbytes:

Create Window, Tab & Field dialog

File:Tutorial TableWindowCreation 09.png

2021-05-24T12:12:11Z

Soundbytes:

Table window Process Menu

Application Dictionary - Create a Custom Table and Window

2021-05-24T12:09:46Z

Soundbytes: more screenshots added

File:Tutorial TableWindowCreation 08.png

2021-05-24T12:02:09Z

Soundbytes:

Index Columns

File:Tutorial TableWindowCreation 07.png

2021-05-24T11:59:33Z

Soundbytes:

Table > Table Index > Index Column tab

File:Tutorial TableWindowCreation 06.png.png

2021-05-24T11:56:07Z

Soundbytes:

Table > Table Index tab

File:Tutorial TableWindowCreation 05.png.png

2021-05-24T11:53:40Z

Soundbytes:

Window > Column Grid View

Application Dictionary - Create a Custom Table and Window

2021-05-24T11:51:47Z

Soundbytes: screenshots added

File:Tutorial TableWindowCreation 04.png.png

2021-05-24T11:49:51Z

Soundbytes:

Element Quick Entry

File:Tutorial TableWindowCreation 03.png.png

2021-05-24T11:43:01Z

Soundbytes:

Copy Columns from Table Dialog

File:Tutorial TableWindowCreation 02.png.png

2021-05-24T11:39:36Z

Soundbytes:

Table&Window Process Menu

File:Tutorial TableWindowCreation 01.png

2021-05-24T11:31:11Z

Soundbytes:

Table and Column Window

Application Dictionary - Create a Custom Table and Window

2021-05-24T11:24:24Z

Soundbytes: /* Introduction */ removed personal email

Application Dictionary - Create a Custom Table and Window

2021-05-24T11:18:44Z

Soundbytes: Restricted the tutorial scope to creation of table window, tab, field and menu.

[[Category:Application Dictionary|P]]

__INDEX__

=Introduction=
This tutorial is brought to you by Andreas Sumerauer. If you have any questions, criticism or suggestions for improvement, feel free to contact me [mailto:ansum@soundbytes.de via email]

==Goal of this tutorial==
This tutorial will enable you to create your own custom Data Tables that are fully integrated within the iDempiere application framework.
You will be able to do that without writing a single line of SQL or Java code. Instead you will be introduced to the iDempiere Application Dictionary that provides the tools for the creation of wide ranging customizations and extensions to the iDempiere application.

==Example Specification==
Let's say we want iDempiere to tell us in which office room each employee's workspace is.
In the course of this tutorial we are going to lay the groundwork for this example specification by adding a new table to hold our office room data and a window to manage the data stored within that table.

==Prerequisites==
To get the most out of this tutorial it is highly recommended that before you start you have made yourself familiar with the idempiere user interface.
 Some basic understanding of the concept of the iDempiere application dictionary will be helpful but is not strictly required.
 You can greatly improve your learning experience through actively reproducing the Steps. For that you will need to have System administrator access to a sandbox iDempiere installation.

=Steps=

==Add Database Elements==

===Create a new Table Definition===

We will start by adding the Office Room table to our data base.
Log in as the SuperUser. Then open the Table & Column window and add a new table.
Now fill in the following fields:
* DB Table Name: ''SB_OfficeRoom''
* Name: ''Office Room''
* Data Access Level: ''Client + Organization''
* Save the new record.

====Generate Mandatory Columns====

We will now add a number of columns to the new table. A table that has a window is required to have a number of mandatory columns that are used by iDemiere for house keeping purposes.
These columns can be generated very easily by copying the table schema from another existing table that meets those requirements:
* Click the process button (gear icon) in the tool bar.
* Select Copy Columns from Table. A good candidate to be used as a template would be ''C_Subscription_Delivery''. Enter that name into the dialog that pops up and hit OK. The newly generated columns will appear in the Column sub tab right under the main edit area.
* We are going to need all of these columns except for ''C_Subscription_ID''. To remove it tick the checkbox at the left side of the column's row and hit the ''Delete Record'' button ('-' icon).

====Add Custom Columns to the Table====

Now add the ''RoomNo'' column:
* Click the ''Create New'' Button ('+' icon) in the ''Column'' tab tool bar. The ''Table > Column'' window is opened with the new record loaded.
* Rightclick the Entity Type field and select new from the context menu.
* Fill in the required fields in the QuickEntry dialog then hit OK:
** DB Column Name: ''RoomNo''
** Name: ''Room Number''
** Print Text: ''Room Number''
* Back in the Column window fill in these fiels then save the new record:
** Reference: ''String''
** Length: ''30''

Obviously it does not make sense to have a room without a number. So let's make the Room Number field mandatory:

:* Tick the ''Mandatory'' checkbox. A new ''Office Room'' record can now only be saved when the ''Room Number'' field is not empty.

Repeat the above steps to create two more new columns: ''FloorNo'' (''Floor Number'') and ''BuildingWing'' (''Building Wing''). Leave the ''Mandatory'' checkbox unticked for these two columns.

===Generate the Table within the Database===

The new table and its columns are now defined as part of the iDempiere application dictionary.
To create all of them in the database hit the ''Synchronize Column'' button in the ''Table > Column'' window.
Note that this button works a bit differently for a table that already exists in the database.
It will then only create or update the currently edited column.

===Add a Unique Constraint===

Since our customization only manages a single building we can safely assume that room numbers will be unique.
To avoid user errors we are going to create a UNIQUE constraint on that column. We have to make sure that different tenants can still have rooms with the same number. Because of that the constraint has to include the ''AD_Client_ID'' column as well.
* In the subtab bar click the ''Table Index'' tab and then the ''Create New'' button of that tab.
* Enter ''Unique_RoomNo_per_Tenant'' into the Name field of the ''Table > Table Index'' window that has just opened.
* Tick both the ''Create Constraint'' and the ''Unique'' checkboxes.
* Save the new record.
* Now we need to add the index columns. Hit the ''Create New'' button of the ''Index Column'' subtab.
* The edit view will switch to ''Table > Table Index > Index Column''. Here enter ''RoomNo'' into the ''Column'' field.
* Save the new record and create another one for the ''AD_Client_ID'' column.
* Now switch back to the ''Table > Table Index'' view and click the ''Index Validate'' button. This will generate the constraint within the database.

==Add the User Interface Elements==

===Generate Window, Tab and Fields as well as a Menu Entry for the new Table===

We now go back to the ''Table'' window. Rightclick ''Table'' in the breadcrumb row or hit ''ALT+Arrow Up'' on the keyboard.
Click the Process button in the tool bar and select ''Create Window, Tab and Field from Table'' from the context menu.
In the dialog that appears tick the ''Create Menu'' checkbox and hit OK.
After the successfull completion of the process a confirmation dialog will pop up.
In that dialog click on ''Tab: Office Room''. This will open a new ''Window > Tab'' window.

===Improve the Tab Layout===

The new Tab's layout has been generated using some default settings. Let's see if we can improve it a bit.
* hit the ''Process'' button in the toolbar of the new window and select ''Tab Editor''.
* This opens the ''Tab Editor'' dialog.

The Tab editor is a very powerful tool that can't be fully covered in the course of this tutorial. We will now just reposition some of the layout elemnts. 
* Rightclick and hold the label of the ''Building Wing'' field then move the mouse to the right of the ''Room Number'' field and release the mouse button. You have just dragged and dropped the ''Building Wing'' field to a new position.
* Now drag and drop the ''Active'' checkbox to the right of the ''Floor Number'' field.
* We want the checkbox to be vertically aligned with the editor fields in the layout column. If you find that the checkbox has landed too close to the ''Floor Number'' field change the X-Position value in the Property sidebar to the right from 4 to 5 and hit ''Enter''. This will move he checkbox to the desired position.
* Finally hit the ''OK'' button to save your edits and close the dialog.

=Conclusion=

Now lets view the results.
* log in to the Application as GardenAdmin. You might have to log out before in case you are still loged in as the system user
* Type ''Office Room'' into the menu filter field. The Menu will pop up with only the ''Office Room'' entry visible.
* Click the entry to open the ''Office Room'' window. The mandatory ''Room Number'' field is lined red while it is empty.

Congregulations! You have finished this tutorial. You are now able to create your own custom tables complete with its own window and menu entry within iDempiere.

Application Dictionary - Create a Custom Table and Window

2021-05-23T11:52:44Z

Soundbytes: /* Add a new Column and Data Relation to the User Table */

[[Category:Application Dictionary|P]]

__INDEX__

=Introduction=
This tutorial is brought to you by Andreas Sumerauer. If you have any questions, criticism or suggestions for improvement, feel free to contact me [mailto:ansum@soundbytes.de via email]

==Goal of this tutorial==
This tutorial will enable you to create your own custom Data Tables that are fully integrated within the iDempiere application framework.
You will be able to do that without writing a single line of SQL or Java code. Instead you will be introduced to the iDempiere Application Dictionary that provides the tools for the creation of wide ranging customizations and extensions to the iDempiere application.
You will learn how to create data relations to existing tables to make your new table accessible to the database.
Lastly You will be taught how to create and customize the user interfaces that iDempiere supplies for entering, deleting and managing your custom data seamlessly within the Application.

==Example Specification==

In the course of this tutorial we are going to implement a small example specification: Let's say we want iDempiere to tell us in which office room each employee's workspace is.
 To make that possible we will need a new ''Office Room'' table and also a new window to manage the data stored within that table.
 We are going to add a new ''SB_OfficeRoom_ID'' column to the ''User'' table and will add the referring editor field to the ''User'' window. These elements will establish the relation between the existing ''User'' table and our new ''Office Room'' table.
 As a last step we are going to configure iDempiere's ''QuickEdit'' dialog. It allows us to add or modify a user's office room without having to switch away from the ''User'' window to the ''Office Room'' window.


==Prerequisites==
To get the most out of this tutorial it is highly recommended that before you start you have made yourself familiar with the idempiere user interface.
 Some basic understanding of the concept of the iDempiere application dictionary will be helpful but is not strictly required.
 You can greatly improve your learning experience through actively reproducing the Steps. For that you will need to have System administrator access to a sandbox iDempiere installation.



=Steps=

==Add Database Elements==

===Create a new Table Definition===

We will start by adding the Office Room table to our data base.
Log in as the SuperUser. Then open the Table & Column window and add a new table.
Now fill in the following fields:
* DB Table Name: ''SB_OfficeRoom''
* Name: ''Office Room''
* Data Access Level: ''Client + Organization''
* Save the new record.

====Generate Mandatory Columns====

We will now add a number of columns to the new table. A table that has a window is required to have a number of mandatory columns that are used by iDemiere for house keeping purposes.
These columns can be generated very easily by copying the table schema from another existing table that meets those requirements:
* Click the process button (gear icon) in the tool bar.
* Select Copy Columns from Table. A good candidate to be used as a template would be ''C_Subscription_Delivery''. Enter that name into the dialog that pops up and hit OK. The newly generated columns will appear in the Column sub tab right under the main edit area.
* We are going to need all of these columns except for ''C_Subscription_ID''. To remove it tick the checkbox at the left side of the column's row and hit the ''Delete Record'' button ('-' icon).

====Add Custom Columns to the Table====

Now add the ''RoomNo'' column:
* Click the ''Create New'' Button ('+' icon) in the ''Column'' tab tool bar. The ''Table > Column'' window is opened with the new record loaded.
* Rightclick the Entity Type field and select new from the context menu.
* Fill in the required fields in the QuickEntry dialog then hit OK:
** DB Column Name: ''RoomNo''
** Name: ''Room Number''
** Print Text: ''Room Number''
* Back in the Column window fill in these fiels then save the new record:
** Reference: ''String''
** Length: ''30''

Repeat the above steps to create two more new columns: ''FloorNo'' (''Floor Number'') and ''BuildingWing'' (''Building Wing'').

===Generate the Table within the Database===

The new table and its columns are now defined as part of the iDempiere application dictionary.
To create all of them in the database hit the ''Synchronize Column'' button in the ''Table > Column'' window.
Note that this button works a bit differently for a table that already exists in the database.
It will then only create or update the currently edited column.

===Add a Unique Constraint===

Since our customization only manages a single building we can safely assume that room numbers will be unique.
To avoid user errors we are going to create a UNIQUE constraint on that column. We have to make sure that different tenants can still have rooms with the same number. Because of that the constraint has to include the ''AD_Client_ID'' column as well.
* In the subtab bar click the ''Table Index'' tab and then the ''Create New'' button of that tab.
* Enter ''Unique_RoomNo_per_Tenant'' into the Name field of the ''Table > Table Index'' window that has just opened.
* Tick both the ''Create Constraint'' and the ''Unique'' checkboxes.
* Save the new record.
* Now we need to add the index columns. Hit the ''Create New'' button of the ''Index Column'' subtab.
* The edit view will switch to ''Table > Table Index > Index Column''. Here enter ''RoomNo'' into the ''Column'' field.
* Save the new record and create another one for the ''AD_Client_ID'' column.
* Now switch back to the ''Table > Table Index'' view and click the ''Index Validate'' button. This will generate the constraint within the database.

===Configure the Record Identifier String===
ToDo

===Add a new Column and Data Relation to the User Table===

Now it is time to establish a relation from the database to the new table.

* open the Table & Columnn window and load the AD_User table.
* ToDo: Add Steps.

==Add the User Interface Elements==

===Generate Window, Tab and Fields as well as a Menu Entry for the new Table===

We now go back to the ''Table'' window. Rightclick ''Table'' in the breadcrumb row or hit ''ALT+Arrow Up'' on the keyboard.
Click the Process button in the tool bar and select ''Create Window, Tab and Field from Table'' from the context menu.
In the dialog that appears tick the ''Create Menu'' checkbox and hit OK.
After the successfull completion of the process a confirmation dialog will pop up.
In that dialog click on ''Tab: Office Room''. This will open a new ''Window > Tab'' window.

===Improve the Tab Layout===

The new Tab's layout has been generated using some default settings. Let's see if we can improve it a bit.
* hit the ''Process'' button in the toolbar of the new window and select ''Tab Editor''.
* This opens the ''Tab Editor'' dialog.

The Tab editor is a very powerful tool that can't be fully covered in the course of this tutorial. We will now just reposition some of the layout elemnts. 
* Rightclick and hold the label of the ''Building Wing'' field then move the mouse to the right of the ''Room Number field'' and release the mouse button. You have just dragged and dropped the ''Building Wing'' field to a new position.
* Now drag and drop the ''Active'' chackbox to the right of the ''Floor Number'' field.
* We want the checkbox to be vertically aligned with the editor fields in the layout column. If you find that the checkbox has landed too close to the ''Floor Number'' field change the X-Position value in the Property sidebar to the right from 4 to 5 and hit ''Enter''. This will move he checkbox to the desired position.
* Finally hit the ''OK'' button to save your edits and close the dialog.

===Make selected Fields available to the Quick Entry Dialog===

We are now going to make a few of the newly created fields available to the Quick Entry dialog.
In the Field subtab select the ''Room Number'' row and click the Edit Record button.
* Tick the ''Quick Entry'' checkbox in ''the Window > Tab > Field'' view that the window that has switched to. This makes the field available to the QuickEntry dialog.

Repeat that last step for both the ''Floor Number'' and ''Building Wing'' fields.

Hint: Do not forget to save your last edit. iDempiere will autosave any of your changes when you load another record into the active window or switch to a parent tab or subtab. Manual saving is required in all other cases. that is when you change the focus to any other tab in the hierarchy that is not a parent or child of the previous one.

===Add a new field to a factory provided window.===

As a final step we are now going to add a new ''Office Room'' field to the 'User > User Contact' window tab.

Todo: Add office room field.

==View the results==

Todo: List UI customization elements: Menu, new Window, field in existing Window, QuickEntry Dialog enabled for new Element.
Todo: Login as client admin or user
Todo: Menu and Window Office Room
Todo: Usage QuickEntry

Application Dictionary - Create a Custom Table and Window

2021-05-23T11:47:49Z

Soundbytes: Created page with "P __INDEX__ =Introduction= This tutorial is brought to you by Andreas Sumerauer. If you have any questions, criticism or suggestions for..."

[[Category:Application Dictionary|P]]

__INDEX__

=Introduction=
This tutorial is brought to you by Andreas Sumerauer. If you have any questions, criticism or suggestions for improvement, feel free to contact me [mailto:ansum@soundbytes.de via email]

==Goal of this tutorial==
This tutorial will enable you to create your own custom Data Tables that are fully integrated within the iDempiere application framework.
You will be able to do that without writing a single line of SQL or Java code. Instead you will be introduced to the iDempiere Application Dictionary that provides the tools for the creation of wide ranging customizations and extensions to the iDempiere application.
You will learn how to create data relations to existing tables to make your new table accessible to the database.
Lastly You will be taught how to create and customize the user interfaces that iDempiere supplies for entering, deleting and managing your custom data seamlessly within the Application.

==Example Specification==

In the course of this tutorial we are going to implement a small example specification: Let's say we want iDempiere to tell us in which office room each employee's workspace is.
 To make that possible we will need a new ''Office Room'' table and also a new window to manage the data stored within that table.
 We are going to add a new ''SB_OfficeRoom_ID'' column to the ''User'' table and will add the referring editor field to the ''User'' window. These elements will establish the relation between the existing ''User'' table and our new ''Office Room'' table.
 As a last step we are going to configure iDempiere's ''QuickEdit'' dialog. It allows us to add or modify a user's office room without having to switch away from the ''User'' window to the ''Office Room'' window.


==Prerequisites==
To get the most out of this tutorial it is highly recommended that before you start you have made yourself familiar with the idempiere user interface.
 Some basic understanding of the concept of the iDempiere application dictionary will be helpful but is not strictly required.
 You can greatly improve your learning experience through actively reproducing the Steps. For that you will need to have System administrator access to a sandbox iDempiere installation.



=Steps=

==Add Database Elements==

===Create a new Table Definition===

We will start by adding the Office Room table to our data base.
Log in as the SuperUser. Then open the Table & Column window and add a new table.
Now fill in the following fields:
* DB Table Name: ''SB_OfficeRoom''
* Name: ''Office Room''
* Data Access Level: ''Client + Organization''
* Save the new record.

====Generate Mandatory Columns====

We will now add a number of columns to the new table. A table that has a window is required to have a number of mandatory columns that are used by iDemiere for house keeping purposes.
These columns can be generated very easily by copying the table schema from another existing table that meets those requirements:
* Click the process button (gear icon) in the tool bar.
* Select Copy Columns from Table. A good candidate to be used as a template would be ''C_Subscription_Delivery''. Enter that name into the dialog that pops up and hit OK. The newly generated columns will appear in the Column sub tab right under the main edit area.
* We are going to need all of these columns except for ''C_Subscription_ID''. To remove it tick the checkbox at the left side of the column's row and hit the ''Delete Record'' button ('-' icon).

====Add Custom Columns to the Table====

Now add the ''RoomNo'' column:
* Click the ''Create New'' Button ('+' icon) in the ''Column'' tab tool bar. The ''Table > Column'' window is opened with the new record loaded.
* Rightclick the Entity Type field and select new from the context menu.
* Fill in the required fields in the QuickEntry dialog then hit OK:
** DB Column Name: ''RoomNo''
** Name: ''Room Number''
** Print Text: ''Room Number''
* Back in the Column window fill in these fiels then save the new record:
** Reference: ''String''
** Length: ''30''

Repeat the above steps to create two more new columns: ''FloorNo'' (''Floor Number'') and ''BuildingWing'' (''Building Wing'').

===Generate the Table within the Database===

The new table and its columns are now defined as part of the iDempiere application dictionary.
To create all of them in the database hit the ''Synchronize Column'' button in the ''Table > Column'' window.
Note that this button works a bit differently for a table that already exists in the database.
It will then only create or update the currently edited column.

===Add a Unique Constraint===

Since our customization only manages a single building we can safely assume that room numbers will be unique.
To avoid user errors we are going to create a UNIQUE constraint on that column. We have to make sure that different tenants can still have rooms with the same number. Because of that the constraint has to include the ''AD_Client_ID'' column as well.
* In the subtab bar click the ''Table Index'' tab and then the ''Create New'' button of that tab.
* Enter ''Unique_RoomNo_per_Tenant'' into the Name field of the ''Table > Table Index'' window that has just opened.
* Tick both the ''Create Constraint'' and the ''Unique'' checkboxes.
* Save the new record.
* Now we need to add the index columns. Hit the ''Create New'' button of the ''Index Column'' subtab.
* The edit view will switch to ''Table > Table Index > Index Column''. Here enter ''RoomNo'' into the ''Column'' field.
* Save the new record and create another one for the ''AD_Client_ID'' column.
* Now switch back to the ''Table > Table Index'' view and click the ''Index Validate'' button. This will generate the constraint within the database.

===Configure the Record Identifier String===
ToDo

===Add a new Column and Data Relation to the User Table===

Now it is time to establish a relation from the database to the new table.
We will now add a new custom SB_
* open the Table & Columnn window and load the AD_User table.

==Add the User Interface Elements==

===Generate Window, Tab and Fields as well as a Menu Entry for the new Table===

We now go back to the ''Table'' window. Rightclick ''Table'' in the breadcrumb row or hit ''ALT+Arrow Up'' on the keyboard.
Click the Process button in the tool bar and select ''Create Window, Tab and Field from Table'' from the context menu.
In the dialog that appears tick the ''Create Menu'' checkbox and hit OK.
After the successfull completion of the process a confirmation dialog will pop up.
In that dialog click on ''Tab: Office Room''. This will open a new ''Window > Tab'' window.

===Improve the Tab Layout===

The new Tab's layout has been generated using some default settings. Let's see if we can improve it a bit.
* hit the ''Process'' button in the toolbar of the new window and select ''Tab Editor''.
* This opens the ''Tab Editor'' dialog.

The Tab editor is a very powerful tool that can't be fully covered in the course of this tutorial. We will now just reposition some of the layout elemnts. 
* Rightclick and hold the label of the ''Building Wing'' field then move the mouse to the right of the ''Room Number field'' and release the mouse button. You have just dragged and dropped the ''Building Wing'' field to a new position.
* Now drag and drop the ''Active'' chackbox to the right of the ''Floor Number'' field.
* We want the checkbox to be vertically aligned with the editor fields in the layout column. If you find that the checkbox has landed too close to the ''Floor Number'' field change the X-Position value in the Property sidebar to the right from 4 to 5 and hit ''Enter''. This will move he checkbox to the desired position.
* Finally hit the ''OK'' button to save your edits and close the dialog.

===Make selected Fields available to the Quick Entry Dialog===

We are now going to make a few of the newly created fields available to the Quick Entry dialog.
In the Field subtab select the ''Room Number'' row and click the Edit Record button.
* Tick the ''Quick Entry'' checkbox in ''the Window > Tab > Field'' view that the window that has switched to. This makes the field available to the QuickEntry dialog.

Repeat that last step for both the ''Floor Number'' and ''Building Wing'' fields.

Hint: Do not forget to save your last edit. iDempiere will autosave any of your changes when you load another record into the active window or switch to a parent tab or subtab. Manual saving is required in all other cases. that is when you change the focus to any other tab in the hierarchy that is not a parent or child of the previous one.

===Add a new field to a factory provided window.===

As a final step we are now going to add a new ''Office Room'' field to the 'User > User Contact' window tab.

Todo: Add office room field.

==View the results==

Todo: List UI customization elements: Menu, new Window, field in existing Window, QuickEntry Dialog enabled for new Element.
Todo: Login as client admin or user
Todo: Menu and Window Office Room
Todo: Usage QuickEntry

Plugin: LBR Localization Brazil

2021-02-13T14:59:41Z

Soundbytes: replaced broken bitbucket link to source (at the page bottom)

* '''Maintainer:''' [[User:Alan.lesc1|Alan Lescano]]
* '''Status:''' in development
* '''Part of:''' [[Feature/Localization Brazil]]
* '''Source-code:''' [https://github.com/idempierelbr/idempierelbr https://github.com/idempierelbr/idempierelbr]

== Description ==

This functionality (group of plugins) adds support to Brazilian legislation related to:
* Individuals and legal entities control on Business Partner window, including CEP/ZIP (lookup address using online services);
* Taxes on sales and purchases (one of the most complex in the world, with about 15 daily new laws);
* Nota Fiscal Eletrônica (fiscal electronic document that should be generated when selling goods/services, and validated through government webservices);
* Boletos (bank bill document) and CNAB (file used to communicate exchange billing information, payments, statements, direct debit, etc);
* SPED (fiscal control);
* And many other resources needed for the Brazilian companies.

Due to the complexity (about 312 java classes, 23000 code lines, dozens of postgres/oracle scripts) the project was split into plugins:
* org.idempierelbr.core (base for Brazil; includes translation and basic columns/fields for general use);
* org.idempierelbr.tax (requires core plugin; resources for configuring automatic calculation of brazilian taxes);
* org.idempierelbr.nf (requires core and tax plugins; generate and validate Nota Fiscal Eletrônica);
* org.idempierelbr.openitem (requires core plugin; specific brazilian changes in reports and open item windows);
* org.idempierelbr.bank (requires core and openitem plugins; generate Boleto document, and bank communications);
* org.idempierelbr.bank.bankname (requires core, openitem and bank plugins; each brazilian bank as a plugin so its easier to generate new Boleto documents);
* org.idempierelbr.sped (requires core, tax and nf plugins; generates SPED, a brazilian fiscal control document).

== Screenshots ==
[[File:Screenshot_home.png|520px]] [[File:Screenshot_menu.png|520px]]

[[File:Screenshot_bpartner.png|520px]] [[File:Screenshot_product.png|520px]]

[[File:Screenshot_cep.png|520px]] [[File:Screenshot_TaxTransaction.png|520px]]

== More ==
Due the fact this is a specific brazilian localization, you can follow the project and get more information in portuguese through the link:

https://github.com/idempierelbr/idempierelbr

[[Category:Available_Plugins]]
[[Category:Localisation|B]]

Developing Plug-Ins - Models, Documents and custom accounting

2021-02-13T14:55:45Z

Soundbytes: replaced broken link to source

[[Category:Development|P]]
[[Category:Developer documentation‏‎]]
[[Category:Plug-In Development]]
__TOC__

'''WARNING: THIS PAGE NEEDS YOU! IF YOU SEE ANY ERRORS, PLEASE CORRECT THEM. IF YOU THINK SOMETHING SHOULD BE DESCRIBED IN ANOTHER WAY, PLEASE CORRECT IT! IF YOU HAVE ADDITIONAL INFORMATION WHICH COULD BE USEFUL, PLEASE ADD IT!'''

This tutorial is brought to you by Jan Thielemann from evenos GmbH (www.evenos-consulting.de). If you have questions, criticism or improvement suggestions, feel free to visit me ([[User:Jan.thielemann|Jan.thielemann]]) or write me [mailto:jan.thielemann@evenos.de an email].

If you think that something is missing here, feel free to modify this page and add your name here. Other contributors and people who helped me:
*Thomas Bayen
*Nicols Micoud
*Redhuan D. Oon
*Carlos Ruiz

=Goal of this tutorial=
In this tutorial, I want to show you how you can implement custom document types to make your own tables act like documents. I also explain the steps to provide the necessary code so that your document can make custom accounting entries. However, I am still new to the documents topic in iDempiere so I don't claim that this tutorial is complete, nor that everything I mention is 100% correct. I dare you to correct me if I am wrong!

=Prerequisites=
Before you start this tutorial, you should take a look at the following tutorials:
* [[Developing_plug-ins_without_affecting_the_trunk|Developing Plug-Ins without affecting the Trunk]]
* [[Developing_Plug-Ins_-_Get_your_Plug-In_running|Developing Plug-Ins - Get your Plug-In started]]
* [[Developing_Plug-Ins_-_IDocFactory_(Custom_Accounting)|Developing Plug-Ins - IDocFactory]]
* [[Hackers_Guide_to_Documents|Hackers Guide to Documents]] - And all the links mentioned there!

The code used in this tutorial is available here: [https://archive.softwareheritage.org/browse/origin/directory/?origin_url=https://bitbucket.org/evenos-consulting/un.kong.jim.battleplan archive.softwareheritage.org]

=tl;dr=
https://www.youtube.com/watch?v=1H7NaSY5G5k

=The Workflow=
==Statement of the problem==
Before we start writing code or other stuff, let's find an example for this tutorial. I would like to give you a concrete case where we need a new custom document type and show you how to implement it step by step. So what could be a use case where we need a document?

Let's imagine that the dictator of East-West Rokea, Jim Kong Un, wants to use iDempiere for his battle plans and to keep track of the expenses in the upcoming war against his mortal enemy, the United States of Majaica. He needs a way to let his generals create battle plans and he wants to be the only person who can approve the plans, because he is the mighty leader.

Battle plans can have war machinery attached, like order lines on a sales order, so once a battle plan is approved, accounting entries should be created for Jim to know how much money he burns in the war. Note that his generals are good in creating battle plans but only the army commanders know how much war machinery is actually available on the ground.

So we have three type of people involved in creating battle plans:
*Generals create battle plans
*Commanders attach war machinery to the battle plans
*Jim Kong Un approves battle plans

Generals and Commanders could be implemented by iDempiere Roles, but to ensure that only generals create battle plans and commanders attach war machinery to them we will require an iDempiere document and a custom workflow to manage the battle plans.

Okay, so on a fresh system, we need to create users, roles, tables, windows, a workflow, a document and also we need to write some code. Let's start.

==The Battle Plan==
So what is a battle plan and how could we represent it in a database? Let's think about it. What do we need? We need:
*The location where to attack
*The battalion which should attack
*The time when the attack should start
*The description of the strategy
*The name of the battle plan
*The person who is in charge for this plan (so he can be executed if the plan fails)

Also we need a way to represent the war machinery. For this, we create a simple table which only has a name, value and description field so we can represent a battalion. Another table is the war machinery with the following fields:
*Name/Value/Description of the machinery
*Price for this machine
*Flag indicating that this machine is in repair (we cannot send broken tanks into the battle)

And last but not least, we need to attach the machinery to the battle plans in a table like order lines with a simple reference to the machinery table. That should be all for the beginning.

==Create the database tables==
Create the following tables and please note that in this tutorial, we don't care about database constraints, table keys, grammar or orthography. It's just an example ;)

Battalion
<pre>
CREATE TABLE ROK_battalion
(
--Default Columns
rok_battalion_ID numeric(10,0) NOT NULL,
rok_battalion_uu character varying(36) DEFAULT NULL::character varying,
ad_client_id numeric(10,0) NOT NULL,
ad_org_id numeric(10,0) NOT NULL,
isactive character(1) NOT NULL DEFAULT 'Y'::bpchar,
created timestamp without time zone NOT NULL DEFAULT now(),
createdby numeric(10,0) NOT NULL,
updated timestamp without time zone NOT NULL DEFAULT now(),
updatedby numeric(10,0) NOT NULL,

--User Columns
value character varying(40) NOT NULL,
name character varying(255) NOT NULL,
description character varying(255)
)
WITH (
OIDS=FALSE
);
ALTER TABLE rok_battalion
OWNER TO adempiere;
</pre>

War Machines
<pre>
CREATE TABLE ROK_war_machine
(
--Default Columns
rok_war_machine_ID numeric(10,0) NOT NULL,
rok_war_machine_uu character varying(36) DEFAULT NULL::character varying,
ad_client_id numeric(10,0) NOT NULL,
ad_org_id numeric(10,0) NOT NULL,
isactive character(1) NOT NULL DEFAULT 'Y'::bpchar,
created timestamp without time zone NOT NULL DEFAULT now(),
createdby numeric(10,0) NOT NULL,
updated timestamp without time zone NOT NULL DEFAULT now(),
updatedby numeric(10,0) NOT NULL,

--User Columns
value character varying(40) NOT NULL,
name character varying(255) NOT NULL,
description character varying(255),
price numeric NOT NULL DEFAULT 0,
isrepairing character(1) NOT NULL DEFAULT 'N'::bpchar
)
WITH (
OIDS=FALSE
);
ALTER TABLE rok_war_machine
OWNER TO adempiere;

</pre>

Battle Plan
<pre>
CREATE TABLE ROK_battle_plan
(
--Default columns
rok_battle_plan_ID numeric(10,0) NOT NULL,
rok_battle_plan_uu character varying(36) DEFAULT NULL::character varying,
ad_client_ID numeric(10,0) NOT NULL,
ad_org_ID numeric(10,0) NOT NULL,
isactive character(1) NOT NULL DEFAULT 'Y'::bpchar,
created timestamp without time zone NOT NULL DEFAULT now(),
createdby numeric(10,0) NOT NULL,
updated timestamp without time zone NOT NULL DEFAULT now(),
updatedby numeric(10,0) NOT NULL,

--Document columns
documentno character varying(30) NOT NULL,
docstatus character(2) NOT NULL,
docaction character(2) NOT NULL,
processing character(1),
processed character(1) NOT NULL DEFAULT 'N'::bpchar,
c_doctype_id numeric(10,0) NOT NULL,
c_doctypetarget_id numeric(10,0) NOT NULL,
isapproved character(1) NOT NULL DEFAULT 'Y'::bpchar,

--Document columns to enable accounting
dateacct timestamp without time zone NOT NULL,
processedon numeric,
posted character(1) NOT NULL DEFAULT 'N'::bpchar,
c_currency_id numeric(10,0) NOT NULL,

--User columns
value character varying(40) NOT NULL,
name character varying(255) NOT NULL,
description character varying(255),
ad_user_id numeric(10,0), --in charge
rok_battalion_ID numeric(10,0),
attack_location character varying(255) NOT NULL,
attack_time timestamp without time zone NOT NULL
)
WITH (
OIDS=FALSE
);
ALTER TABLE ROK_battle_plan
OWNER TO adempiere;
</pre>

Battle Plan Line
<pre>
CREATE TABLE rok_battle_plan_line
(
--Default Columns
rok_battle_plan_line_ID numeric(10,0) NOT NULL,
rok_battle_plan_line_uu character varying(36) DEFAULT NULL::character varying,
ad_client_id numeric(10,0) NOT NULL,
ad_org_id numeric(10,0) NOT NULL,
isactive character(1) NOT NULL DEFAULT 'Y'::bpchar,
created timestamp without time zone NOT NULL DEFAULT now(),
createdby numeric(10,0) NOT NULL,
updated timestamp without time zone NOT NULL DEFAULT now(),
updatedby numeric(10,0) NOT NULL,
rok_battle_plan_id numeric(10,0) NOT NULL,

--User Columns
rok_war_machine_ID numeric(10,0) NOT NULL
)
WITH (
OIDS=FALSE
);
ALTER TABLE rok_battle_plan_line
OWNER TO adempiere;
</pre>

==Create tables, columns, windows, tabs and fields==
Now that we have our database ready, we can start creating windows for our tables. You should be able to do this by your own. You are not? Okay, okay! Sorry. Just take a look here: https://www.youtube.com/watch?v=F1lFHS2riG4&list=UUbBGUUNnLy4kIHxq19DNPbA

So the general concept is:
#Create a database table
#Login as SuperUser on System Administrator role and System client
#Open Table and Columns window and create your table and columns
#Open Window, Tab and Field window and create your window

After creating the Tables in iDempiere, you may need to change the following columns:

ROK_Battle_Plan
*Make C_DocType_ID not updatable and set default logic to "0"
*Change C_DocTypeTarget_ID reference to "Table" and set the reference key to "C_DocType". Also create a new dynamic validation and set it to here. The validation sql should look like "C_DocType.DocBaseType ='ROK'"
*Make DocumentNo not updateable and part of the identifier
*Change DocAction reference to button, change reference key to "_Document Action" and create a new process "Process Battle Plan" and attach it to the button. The Process only need a name and a search key for now. I chose "Process Battle Plan" for both. Also change the default logic to "CO"
*For DocStatus, set the reference key to "_Document Status" and set the default logic to "DR"
*Make Processed not updateable
*Change length of ProcessedOn to 20
*Change reference of Processing to Button and use Process Battle Plan as the process
*Make isApproved not updateable and set default logic to "@IsApproved@"
*Change reference of DateAcct to Date, length to 7 and use "@#Date@" as default logic
*Change reference of Posted to Button, set reference key to "_Posted Status" and default logic to "N"
*Set default logic of C_Currency_ID to "@C_Currency_ID@" and make it not updateable

ROK_Battle_Plan_Line
*Set default logic of ROK_Battle_Plan_ID to "@ROK_Battle_Plan_ID@", make it not updateable and check the Parent link column checkbox

Now create the corresponding windows. After you created them, you may need to change the following fields:

ROK_Battle_Plan window
*Hide Account Date
*Hide Approved
*Hide Process Now
*Hide Processed
*Hide Processed On
*Set display logic of Posted to "@Processed@=Y & @#ShowAcct@=Y"
*Make currency read only
*Make Document Type read only
*Make Document Status read only

Finally create the menu entries for our new windows.

==Create a custom document type in the Application Dictionary==
Now that we have our windows ready, we can start creating our new document type. To do this, first open the Reference window and search the "C_DocType DocBaseType" reference. Go to the List Validation tab and add a new entry:
*Value=ROK
*Name=Battle Plan

With this new base type, we can create a new document type. Open the Document Type window and create a new entry:
*Name=Battle Plan
*Print Text=Battle Plan
*CL Category=None
*Document BaseType=Battle Plan

Please note that if you want to use this document on a specific client, you have to create it on this client!

==IModelFactory and IDocFactory==
The Application Dictionary is now ready. Now we can implement some code. Follow the other tutorials on this wiki or take a look at evenos Consultings youtube videos. What you basically do is:
*Create a new Plug-in
*Create a ModelFactory class and implement IModelFactory
*Create a DocumentFactory class and implement IDocFactory
*Create component definitions for Model- and DocFactory (note that DocFactory has an additional parameter called "gaap" whose value is "*"
*Generate the X and I classes via model.generator app in eclipse
*Create M classes for your models
*Create a new document class called "Doc_ROKBattlePlan" which extends "Doc"
*Implement DocAction and DocOption in MROKBattlePlan

Don't forget to add the dependencies to your MANIFEST.MF

After you created the basic shell for all classes, let's get into the implementation details. Open MROKBattlePlan and make some changes to the default generated methods:

<pre>
@Override
public int customizeValidActions(String docStatus, Object processing, String orderType, String isSOTrx, int AD_Table_ID,
String[] docAction, String[] options, int index) {
if (options == null)
throw new IllegalArgumentException("Option array parameter is null");
if (docAction == null)
throw new IllegalArgumentException("Doc action array parameter is null");

// If a document is drafted or invalid, the users are able to complete, prepare or void
if (docStatus.equals(DocumentEngine.STATUS_Drafted) || docStatus.equals(DocumentEngine.STATUS_Invalid)) {
options[index++] = DocumentEngine.ACTION_Complete;
options[index++] = DocumentEngine.ACTION_Prepare;
options[index++] = DocumentEngine.ACTION_Void;

// If the document is already completed, we also want to be able to reactivate or void it instead of only closing it
} else if (docStatus.equals(DocumentEngine.STATUS_Completed)) {
options[index++] = DocumentEngine.ACTION_Void;
options[index++] = DocumentEngine.ACTION_ReActivate;
}

return index;
}

@Override
public boolean processIt(String action) throws Exception {
log.warning("Processing Action=" + action + " - DocStatus=" + getDocStatus() + " - DocAction=" + getDocAction());
DocumentEngine engine = new DocumentEngine(this, getDocStatus());
return engine.processIt(action, getDocAction());
}

@Override
public boolean unlockIt() {
return true;
}

@Override
public boolean invalidateIt() {
return true;
}

@Override
public String prepareIt() {
setC_DocType_ID(getC_DocTypeTarget_ID());
return DocAction.STATUS_InProgress;
}

@Override
public boolean approveIt() {
return true;
}

@Override
public boolean rejectIt() {
return true;
}

@Override
public String completeIt() {
setProcessed(true);
return DocAction.STATUS_Completed;
}

@Override
public boolean voidIt() {
return true;
}

@Override
public boolean closeIt() {
return true;
}

@Override
public boolean reverseCorrectIt() {
return true;
}

@Override
public boolean reverseAccrualIt() {
return true;
}

@Override
public boolean reActivateIt() {
return true;
}

@Override
public String getSummary() {
return null;
}

@Override
public String getDocumentInfo() {
return null;
}

@Override
public File createPDF() {
return null;
}

@Override
public String getProcessMsg() {
return null;
}

@Override
public int getDoc_User_ID() {
return 0;
}

@Override
public BigDecimal getApprovalAmt() {
return BigDecimal.ONE;
}
</pre>

As you see, we don't do much business logic here. Thats not necessary for our case but if you create documents for your own, you may want to add some more code here ;)
Take a look at other document model classes to see what you could do. Just search for classes which implement DocAction. A example would be MOrder, MInvoice and so on.

Also heres how the Doc_ROKBattlePlan looks like:
<pre>
public class Doc_ROKBattlePlan extends Doc{

public Doc_ROKBattlePlan (MAcctSchema as, ResultSet rs, String trxName)
{
super (as, MROKBattlePlan.class, rs, null, trxName);
}

@Override
protected String loadDocumentDetails() {
return null;
}

@Override
public BigDecimal getBalance() {
return BigDecimal.ZERO;
}

@Override
public ArrayList<Fact> createFacts(MAcctSchema as) {
ArrayList<Fact> facts = new ArrayList<Fact>();
return facts;
}
}
</pre>

For testing purposes i added a "log.warning("---------------")" to every method in my model as well as my Doc_ class.

==Create Users and Roles==
Since we want to play a little bit, we need differen users and roles. I created the following users and roles:
*User: Jim
*User: GeneralA
*User: CommanderA
*Role: Generals
*Role: Commanders

The assignment of the users to the roles should be clear i guess :P. By the way, all roles are created on the target client. I use GardenWorld for this purpose. Also make sure that all users are added to the Business Partners GardenAdmin BP or GardenUser BP or you won't find them later in the Workflow Responsible window.

==Create the workflow==
The workflow is an essential part when working with documents. The workflow describes the steps needed to make a document transition into other states. Heres an example: At first, the document has the status drafted. The Genreals enter some information and complete the document. The doc now has the status in progress because it needs approval by Jim. Once Jim approved the document, it gets the status approved. From this status it can transition into completed. Which steps exactly are necessarry are described by the workflow.

===Workflow===
So let's start by creating a new workflow on System client. I call mine ROK_Battle_Plan, set access level to all and author to Jim Kong Un, our mighty leader. The Workflow Type is Document Process because we want to process a document. The Table is ROK_Battle_Plan and the Publication Status is Released.
Then we open the report and process window and search the process we created earlier (Process Battle Plan). Here i chose my newly created workflow and save the process.
This all happend on the System Client.

===Responsibles===

Next we have to create some Workflow Responsibles. Go to the GardenWorld client and create some responsibles there.
{| class="wikitable"
|-
! Name !! Type !! Others
|-
|Jim||Human || User=Jim
|-
|Generals||Role || Role=Generals
|-
|Commanders||Role || Role=Commanders
|}

===Nodes===
Now to the more tricky part. We need to create Workflow Nodes and transitions but our responsibles are in GardenWorld and not on System client so we have to mix it a little bit:

{| class="wikitable"
|-
! Name/Search Key !! Action !! Others !! Workflow Responsible !! Client
|-
|(Start)||Wait (Sleep) || - || - || System
|-
|(DocPrepare) ||Document Action || Document Action = Prepare || - || System
|-
|(DocComplete) ||Document Action || Document Action = Complete || - || System
|-
|(DocAuto) ||Document Action || Document Action = <None> || - || System
|-
|(DocApprove) ||User Choice || Column = isApproved || Jim || GardenWorld
|-
|(AddWarMachine)||User Window|| Window = ROK_Battle_Plan || Commanders || GardenWorld
|}

When you are done, make sure that (Start) is set as the starting node in the Workflow window.

===Transitions===
The next step is to create the transitions. You need the following transitions:

{| class="wikitable"
|-
! Start Node !! Destination Node !! LineNo
|-
|(Start)||(DocPrepare) ||10
|-
|(Start)||(DocAuto) || 100
|-
|(DocPrepare)||(AddWarMachine)||10
|-
|(AddWarMachine)||(DocApprove)||10
|-
|(DocApprove)||(DocComplete)||10
|}

==Testing==
We are nearly done. Hopefully i didn't forget to mention a step i did. If something doesn't work for you like i describe it here, sent me a mail! If you find the error by yourself, then please correct this page!

However, for me it now should work so let's make a test!

Login as GeneralA:

[[File:Roktest1.png|320px|border]]

Open the ROK_Battle_Plan window and enter some details:

[[File:Roktest2.png|720px|border]]

Hit the process button in the toolbar and start the process. Chose Complete as the action:

[[File:Roktest4.png|320px|border]]
[[File:Roktest3.png|320px|border]]

Hit the button again and you will see that the workflow has started:

[[File:Roktest4.png|320px|border]]
[[File:Roktest5.png|420px|border]]

Log out and back in but this time chose CommanderA as the user:

[[File:Roktest6.png|320px|border]]

You should see that there is a Workflow Activity waiting for you:

[[File:Roktest7.png|320px|border]]

Click on the button and the Workflow Activities tab opens:

[[File:Roktest8.png|720px|border]]

Click on the window button and enter some lines. When you are done, close the window and hit the green checkmark button in the Workflow Activties tab:

[[File:Roktest9.png|720px|border]]

Open the battle plan again and try to complete it. You should see a message that the plan need approval by Jim:

[[File:Roktest10.png|720px|border]]

Finally log into the system with Jim as the user. He also has a workflow activity. Open it and chose Yes. Then hit the green Checkbox. Congratulations! You completed the document! Open the battle plan and hit the process toolbar button. You should now also see the Posted button. Press it and you will see the accounting entries which were created (no in our case).

[[File:Roktest12.png|320px|border]]
[[File:Roktest11.png|320px|border]]
[[File:Roktest13.png|720px|border]]
[[File:Roktest14.png|720px|border]]

If you take a look at the console output (if you don't see anything but it still works, you have not added "log.warning()" to your methods ;), you see that the model ran through different stages and also our DocFactory returned our Doc_ROKBattlePlan and called it's methods:

<pre>
Aug 27, 2014 2:27:31 PM un.kong.jim.model.MROKBattlePlan processIt
WARNING: Processing Action=AP - DocStatus=IP - DocAction=CO
Aug 27, 2014 2:27:31 PM un.kong.jim.model.MROKBattlePlan approveIt
WARNING: ----------------------------------------------------------------------------------
Aug 27, 2014 2:27:31 PM un.kong.jim.model.MROKBattlePlan <init>
WARNING: ----------------------------------------------------------------------------------
Aug 27, 2014 2:27:31 PM un.kong.jim.model.MROKBattlePlan processIt
WARNING: Processing Action=CO - DocStatus=AP - DocAction=CO
Aug 27, 2014 2:27:31 PM un.kong.jim.model.MROKBattlePlan completeIt
WARNING: ----------------------------------------------------------------------------------
Aug 27, 2014 2:27:31 PM un.kong.jim.model.MROKBattlePlan <init>
WARNING: ----------------------------------------------------------------------------------
Aug 27, 2014 2:27:31 PM un.kong.jim.document.Doc_ROKBattlePlan <init>
WARNING: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Aug 27, 2014 2:27:31 PM un.kong.jim.document.Doc_ROKBattlePlan loadDocumentDetails
WARNING: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Aug 27, 2014 2:27:31 PM org.compiere.acct.Doc isConvertible
WARNING: NOT from C_Currency_ID=195 to 100 - X_ROK_Battle_Plan[1000002]
Aug 27, 2014 2:27:31 PM un.kong.jim.document.Doc_ROKBattlePlan getBalance
WARNING: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Aug 27, 2014 2:27:31 PM un.kong.jim.model.MROKBattlePlan getSummary
WARNING: ----------------------------------------------------------------------------------
Aug 27, 2014 2:27:31 PM un.kong.jim.model.MROKBattlePlan getProcessMsg
WARNING: ----------------------------------------------------------------------------------
Aug 27, 2014 2:27:31 PM un.kong.jim.model.MROKBattlePlan <init>
WARNING: ----------------------------------------------------------------------------------
</pre>

All you now have to do is to implement all the methods in your model/document. I would love to explain them step by step but unfortunately i am still very new to documents and i simply cant. So please, if there is somebody who has experience with it, tell the world how to do it. However, by taking a look at other document classes you should be able to find a way to get things working.

==See Also==
*Take a look at this to solve many parts of the model creation and utilities - [[Plugin:_Aladdin_Magic_Plugin]].
*A study on Workflow is given here - http://red1.org/adempiere/viewtopic.php?f=45&t=1801

Plugin: Wordpress Soap integration

2021-02-13T14:51:18Z

Soundbytes:

* '''Maintainer:''' [[User:habib.salhi]]
* '''License:''' [http://www.gnu.org/licenses/gpl-2.0.html GPLv2] - Free as in Freedom not Free Lunch
* '''Guide: installation''' [https://bitbucket.org/hsalhi77/wp-idempiere-soap/src/7f46523665a8af30dc145b1a1f0129de7519c0ba/01-installation.ogv?at=master]
* '''Guide: demo''' [https://bitbucket.org/hsalhi77/wp-idempiere-soap/src/7f46523665a8af30dc145b1a1f0129de7519c0ba/02-demo.ogv?at=master]
* '''Sources:''' [https://archive.softwareheritage.org/browse/origin/directory/?origin_url=https://bitbucket.org/hsalhi77/wp-idempiere-soap.git archive.softwareheritage.org]

__FORCETOC__

= Description =

With The increasing popularity of wordpress, I felt that many projects in iDempiere might benefit from having a little interaction with outside users, weather it be business partners logging in to view their orders or make new orders or any form of communication with the ERP organizations.

This page will describe the process of creating the wordpress plugin that will connect to idempiere (SOAP as the communication protocol) and allow the below (functionality) interactions with wordpress site visitors.

== Installation ==

steps to implement
* download the project

on idempiere (GardenWorld):
* Pack in the included webservices (9 no) from wp-idempiere-soap/PackIn
* for each one of the 9 imported webservice, go to "WebService Access" Tab add an access for Role "Web Service Execution"
* open Role Window, find the record "Web Service Execution" and check the box for "Access Advanced" - this is required to be able to add a record to "AD_User_Roles" Table as per our example
* add a role for the newly registered users we added role "External Partner User" (AD_Role_ID=1000000)
* add a Request Type "New User Notification" (R_RequestType_ID=1000000) and a Request Category "CRM Requests" (R_Category_ID=1000000)

on wordpress:
* modify the file wp-idempiere-soap/includes/general-setting.php to adapt to your access settings (AD_Client_ID, AD_Role_ID, UserName, Password, serviceURL of your server, p_AD_Role_ID, p_R_RequestType_ID, p_R_Category_ID, p_SalesRep_ID) as per the included sample
* zip the project into wp-idempiere-soap.zip and import the plugin from wp-admin
* add a menu and the pages to the theme

== Functionality Overview ==

[puser-registration]

Here user can register to become a user of a certain Business Partner, the script will run the following 3 webservice in a compositeOperation wp-compositeWrapper:

* run wp-createUpdateUser webservice to add a new user to the chosen bPartner. The User will be locked and will have a random verification code assigned, awaiting verification
* run wp-AddUserRole and add the new user to a predefined Role
* run wp-userRQ and create a new request for the company CRM team to notify them of the new user registration and email the new user with their login credentials and a link to verify their login

[user-verification]

This page will be used by the user to verify his registration, typically they would have received an email with this format:

http://siteurl/wordpress/index.php?username=newuser&code=fsd78dfs6df

then do the following verification:

* run the wp-queryUsers webservice to query the AD_User_ID from the passed username parameter and the EMailVerify Code in iDempiere to be compared with the code parameter
* if the EMailVerify matches the passed code then run the wp-VerifyUser webservice to set the EMailVerifyDate timestamp and IsLocked to N

this will allow the user to login

[user-login]

This page has 2 forms

* User login using the wp-queryUsers webservice
* reset of the password using the wp-compositeWrapper and that internally will run 2 webservices

1. wp-createUpdateUser to change the user password with a random string

2. wp-userRQ will create a request that will email the user the new password and alert the system admin of the change

[user-profile]

after a successful login, the user is directed to this page, which again has 2 forms

1- view user profile using wp-queryUsers webservice

2- Edit user profile using the wp-createUpdateUser

[partner-orders]

This page will display the order history for the Business partner and requires 2 steps:

1- fetch the C_BPartner_ID of the logged in user by running the wp-queryUsers webService

2- run the wp-queryOrders webService and display the history of orders of that user

== Credits & Other Resources ==

special thank to evenos Consulting GmbH (Jan Thielemann) for the great educational videos (link below) that jump started the project, I will highly recommend for anyone that wants to develop webservices in iDempiere

Ameet Kumar Srivastava (amtsrivastava007@gmail.com) for doing all the php coding for the wordpress plugin

My role in the project was initiating the idea for the plugin, all the base preparation in iDempiere, XML file on SmartBear (soupui), sponsoring, guiding and testing the implementation and documenting the open source project

[[Category:Available_Plugins]]
[[Category:Broken_Link_Bitbucket]]

Swing Maintenance Team

2021-02-13T14:43:47Z

Soundbytes:

This page is for everyone who wants to improve the Swing client. It was done in the weekly meeting of 2013-23-01. (There is a page about [[Comparison of Clients]] also.)

Features that are worth a jira ticket and will be worked on can be collected as "blocking" on jira tracker [http://idempiere.atlassian.net/browse/IDEMPIERE-588 IDEMPIERE-588 Swing Client improvement].

We began by collecting missing features:

== missing features ==
* Start Info Windows from the menu tree
* WebStart ([http://idempiere.atlassian.net/browse/IDEMPIERE-591 IDEMPIERE-591])
* Toolbar is not configurable ([http://idempiere.atlassian.net/browse/IDEMPIERE-234 IDEMPIERE-234])
* List View Columns are not configurable
* http://wiki.idempiere.org/en/Swing_Client_Security
* form layout http://wiki.idempiere.org/en/NF001_FormLayout
: CarlosRuiz: that one is maybe the most important IMHO - because it is creating some duplicate effort to try to maintain both different approaches to position fields
* http://wiki.idempiere.org/en/NF001_QuickEntry
* http://wiki.idempiere.org/en/NF001_CustomWindowToolbarButton
* http://wiki.idempiere.org/en/NF001_ColumnToolbarButton
* <CarlosRuiz>active session and broadcast message (even if i have no idea on how to do it in swing) ([http://idempiere.atlassian.net/browse/IDEMPIERE-294 IDEMPIERE-294])
* <CarlosRuiz> - on the Welcome screen the Recent Items
* <CarlosRuiz> and the new portlets to show reports (not sure if this works on swing)
* <CarlosRuiz> - the little "new" icon in front of menu and favourites options
* <a42niem> and the calendar stuff
* <CarlosRuiz> - setup wizard form doesn't have swing counterpart
* <nmicoud> Print format wizard
* <CarlosRuiz> and the tab editor
* <CarlosRuiz> in zk we implemented some zoom functionality from the ending message of a process - or the process log ([http://idempiere.atlassian.net/browse/IDEMPIERE-370 IDEMPIERE-370 Implement link from process ending message to next records])
* <Deepak> We added link when process called from button generating a document. This link can be used to navigate to newly generated record

* at the end of a process, ability to return to parameter panel
* Field group labels is not hidden when attached field is not displayed ([http://idempiere.atlassian.net/browse/IDEMPIERE-349 IDEMPIERE 349])

* '''in progress'''
** scroll wheel works in very small steps in Swing Client ([http://idempiere.atlassian.net/browse/IDEMPIERE-572 IDEMPIERE-572])
** Swing text areas break user flow when cycling focus with tab key ([http://idempiere.atlassian.net/browse/IDEMPIERE-573 IDEMPIERE-573])
** Swing AutoReducible ComboBox not reduced when used with cursor keys ([http://idempiere.atlassian.net/browse/IDEMPIERE-574 IDEMPIERE-574])
** Swing: Toolbar Button to start Process from button fields ([http://idempiere.atlassian.net/browse/IDEMPIERE-587 IDEMPIERE-587])
** Restricted items on Combobox ([http://idempiere.atlassian.net/browse/IDEMPIERE-90 IDEMPIERE-90])
** DocAction button is showing now just "Action" instead of the name of an action (part of [http://idempiere.atlassian.net/browse/IDEMPIERE-594 IDEMPIERE-594])

* '''done'''
** SaveAndCreate Button (raised by nmicoud but [https://bitbucket.org/idempiere/idempiere/commits/all/tip/keyword%28SaveAndCreate%29 done by hengsin]. ;-)

= Ticketing and Peer Review Procedures =

The Team consists of
* Nicolas Micoud
* Thomas Bayen
* Dirk Niemeyer
* ...you?

=== Our workflow ===

* everyone can write an issue into the above '''list of missing features'''
* everyone can create a '''JIRA ticket'''. A JIRA ticket means either that the issue is of special significance or that the reporter takes responsibility that someone work on this ticket. (We do not want to create a bunch of dead tickets that noone reads and resolves.)
* Every issue where the Swing Maintenance Team should be responsible becomes the following attributes:
: - Component '''"Swing Client"'''
: - Label '''"SwingUI"'''
: - Link the new issue as '''blocking to IDEMPIERE-588''' (Swing Client improvement)
* If one wants to work on an issue he sets himself as the Assignee. (Others may comment at any time or give code if they want.)
* If one really does work he sets the status to '''"Progress"'''. Others are aware to ask him before they do code on the same issue
* If the Assignee thinks his code is well done he changes status to '''"Peer Review"'''. He needs to give a link to his contribution in the comment.
* If one experienced member of the Swing Maintenance Team has reviewed he may reopen the ticket or mark it as resolved. This Team member includes the code into the iDempiere Swing Repository at https://bitbucket.org/tbayen/idempiere-swing
* If another Team member (not the Assignee and not the Reviewer) has done a second review he closes the issue. After 4 weeks (and noone else complaining) the issue may be closed by anyone who thinks it is solved.

=== The Swing Repository (BBP philosophy) ===

'''At the moment the Swing repository is *very* outdated. I will re-synchonize it with the active trunk in the first half of december. Please stay tuned...'''

The Swing Repository can be found at https://bitbucket.org/tbayen/idempiere-swing .

The first idea was to insert here peer reviewed code one patch after the other and do a pull request to the main idempiere repository from time to time. This did not work. Our peer review is not good enough to guarantee perfect quality. We can not use the same branch for our peer review (= possible unstable code) and for pull requests to the main trunk (= stable code). Often we see much more issues in our code if Carlos Ruiz or Heng Sin as Maintainers of the main Repository look onto it. But then it was not trivial to separate working patches from not working patches. We agreed that swing changes should stay in the swing directory. But half of our contributions affect other parts of idempiere so this separation is not easy possible.

The solution is: We separate them all and create a new staging area. I call this BBP (Bayen's Best Practice). :-) See [[Mercurial Bayen Best Practice]] for more.

[[Category:Broken_Link_Bitbucket]]