diff --git a/docs/source/troubleshooting/troubleshooting.rst b/docs/source/troubleshooting/troubleshooting.rst index d8e304ad..a20e579a 100644 --- a/docs/source/troubleshooting/troubleshooting.rst +++ b/docs/source/troubleshooting/troubleshooting.rst @@ -104,15 +104,6 @@ Passing XML parameter to XSLT -Using an Oracle database ------------------------- - -**Question:** How to use the Frank!Framework with an Oracle database? - -**Answer:** You may be used to installing Oracle on your development computer, but this is more complicated than necessary. For example if you have a corporate laptop, you should remember to use the right user account. On a corporate laptop you might have an admin account (WSA account) with administrator rights beside your normal user account. If you log in with your normal account and install Oracle, giving the installer administrator rights, then it does not work. You should log in with your admin account and then install Oracle. - -You can avoid such issues by using a Docker container for your Oracle database. See the sources of the Frank!Framework for an example. Checkout https://github.com/frankframework/frankframework and see directory ``test/src/main/tools/setupDB/Oracle``. - Inserting from XPath expression, default value null --------------------------------------------------- @@ -127,14 +118,22 @@ You can write extra logging to (custom) log files using the ````. Whe Currently the following log categories are available: -* ``file`` (ibis4name.log) -* ``XML`` (ibis4name-xml.log) -* ``galm`` (ibis4name-galm.log) -* ``msg`` (ibis4name-messages.log) -* ``security`` (ibis4name-security.log) -* ``heartbeat`` (ibis4name-heartbeat.log) +* ``file`` (ibis4name.log) - The applications log +* ``msg-text`` (ibis4name-xml.log) - Processed messages in human readable format +* ``msg-json`` (ibis4name-xml.log) - Processed message in structured logging (JSON) format. +* ``security`` (ibis4name-security.log) - Audit logging +* ``heartbeat`` (ibis4name-heartbeat.log) - Periodic adapter status status +* ``config`` (ibis4name-galm.log) - Prints the current configuration +* ``ladybug`` (ibis4name-messages.log) - Contains all Ladybug logging + +If you which to change the log appenders, either the format or filename you can overwrite the default framework log file ``log4jibis.xml``. +Please be aware that in order to overwrite this file it must be located in the ``src/main/resources`` (``classes`` folder for non Maven projects) folder. + +.. NOTE:: + + We do not recommend editing this file, it may change between framework versions so use it at your own risk. + Instead we strongly advice to set the ``log4j.configurationFile`` as a system property, with the following value: ``log4j4ibis.xml,/my-file.xml|json|yml``. -You can also create additional log categories by configuring a custom ``log4jibis.xml`` in your ``src/main/resources`` (``classes`` folder for non Maven projects) folder. XSLT Testing with Larva ----------------------- @@ -186,7 +185,11 @@ Transaction attribute on receiver or pipeline? **Question:** Both the ```` and the ```` tag has attribute ``transactionAttribute``. Which element should you choose? -**Answer:** Normally you should choose the ````. There are two reasons for this. First, the purpose of a transaction is that all data modifications should succeed or none should happen. The ```` already does part of the work, for example accepting a message from a queue. The second reason is that a pipeline can be fed by multiple receivers. Typically, some receivers support transactions and some do not. If a receivers that supports transactions has the ``transactionAttribute``, the pipeline after the receiver will inherit the transaction. If another receiver does not support transactions, then that receiver does not have a ``transactionAttribute``. In that case, there is no transaction as intended, because there is no ``transactionAttribute`` on the pipeline and the pipeline does not inherit a transaction. +**Answer:** It really depends on what you want to achieve! The purpose of a transaction is that all data modifications should succeed or none should happen. The ```` does part of the work such as accepting a message from a queue. Its responsibility is to safely read and processes the message. Depending on additional elements on the ```` such as an ```` it also adds a fail-safe mechanism if the message cannot be processed at this time. The ```` processes the information, and can be fed by multiple receivers. Typically, some receivers support transactions and some do not. If a receivers that supports transactions has the ``transactionAttribute``, the pipeline after the receiver will inherit the transaction. + +.. WARNING:: + + If a receiver does not support transactions, regardless of the ``transactionAttribute``, and there is no ``transactionAttribute`` on the pipeline, the pipeline does not inherit a transaction! Load multiple configs at once ----------------------------- @@ -202,14 +205,14 @@ Property configurations..parentConfig **Question:** What is the use of the property configurations..parentConfig exactly? -**Answer:** It changes the classloading of files and properties. In simpler terms, for every file or property the framework has to load, it will first look it up as a global setting (eq. classpath) then in the local configuration, then (if specified) the parent configuration, and lastly the war (``src/main/resources``). Class loading is described in subsection :ref:`propertiesInitialization`, but that section needs some editing because the phrases "system property" and "classpath property" are used in a confusing way. +**Answer:** It changes the order in which files and properties are loaded. For every file or property the framework has to load, it will first look it up as a global setting (eq. classpath resource or system property) then in the local configuration, then (if specified) the parent configuration, and lastly the war (``src/main/resources``). Class loading is described in subsection :ref:`propertiesInitialization`. Authorization to turn on Ladybug -------------------------------- **Question:** Which role do you need at least to turn on Ladybug? -**Answer:** IbisDataAdmin, IbisAdmin or IbisTester. IbisDataAdmin might only work in snapshots that include https://github.com/frankframework/frankframework/pull/1294 (all after 26-11-2020). See also :ref:`deploymentSecurity`. +**Answer:** IbisDataAdmin, IbisAdmin or IbisTester. See also :ref:`deploymentSecurity`. Flow diagram images ------------------- @@ -233,8 +236,8 @@ Test ApiListener with authentication (without Larva) **Question:** How can I locally test an ApiListener with authentication (without Larva)? **Answer:** In the configuration, make the authenticationMethod a configurable property (for example ``${​​​​api.authMethod}​​​​​​​​​​​``. - -In StageSpecifics_LOC.properties, configure: + +Assuming you've set these exact properties in the DeploymentSpecifics.properties, you can 'disable' its behaviour in the StageSpecifics_LOC.properties by setting: .. code-block:: none