[[executionlog]]
= Execution Log

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


The _Execution Log_ extension provides an implementation of xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] that persists xref:refguide:applib:index/services/iactn/Execution.adoc[Execution]s using either the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] or xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] object store.


One use case is to combine with the xref:security:audittrail:about.adoc[] extension.
The _Command Log_ module logs the action invocations or property edits that the end-user makes, while the _audit trail_ logs the resultant changes in state to domain objects.
The two logs are correlated using the xref:refguide:applib:index/services/iactn/Interaction.adoc#getInteractionId_[interactionId] of the owning xref:refguide:applib:index/services/iactn/Interaction.adoc[interaction].

Sometimes the xref:commandlog:about.adoc[] extension is also configured with or instead of this extension; see the xref:#notes[notes] below to compare and contrast.


== Setup

=== Dependency Management

Add an entry for the _Execution Log_ module's own BOM:

[source,xml,subs="attributes+"]
.pom.xml
----
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.causeway.extensions</groupId>
            <artifactId>causeway-extensions-executionlog</artifactId>
            <scope>import</scope>
            <type>pom</type>
            <version>{page-causewayrel}</version>
        </dependency>
    </dependencies>
</dependencyManagement>
----

[#dependencies]
=== Dependencies

In the webapp module of your application, add the following dependency:

[source,xml]
.pom.xml
----
<dependencies>
    <dependency>
        <groupId>org.apache.causeway.extensions</groupId>
        <artifactId>causeway-extensions-executionlog-persistence-XXX</artifactId>    <!--.-->
    </dependency>
</dependencies>
----
<.> specify either `causeway-extensions-executionlog-persistence-jpa` or `causeway-extensions-executionlog-persistence-jdo`, as required


[[_update-appmanifest]]
=== Update AppManifest

In your application's `AppManifest` (top-level Spring `@Configuration` used to bootstrap the app), import the _ExecutionLog_ modules.

[source,java]
.AppManifest.java
----
@Configuration
@Import({
        ...
        CausewayModuleExtExecutionLogPersistenceXxx.class,        // <.>
        ...
})
public class AppManifest {
}
----

<.> specify either `CausewayModuleExtExecutionLogPersistenceJdo` or `CausewayModuleExtExecutionLogPersistenceJpa`, as required

If using xref:security:secman:about.adoc[], you will also need to import the xref:testing:fixtures:about.adoc[Fixture] module; SecMan uses fixture scripts to seed its entities.

[#configure-properties]
=== Configuration Properties

Add the database schema used by the _Execution Log_ entities to the configuration file:

[source,yaml]
.application.yml
----
causeway:
  persistence:
    schema:
      auto-create-schemas: causewayExtExecutionLog
----

This extension currently does not though define any configuration properties of its own.


[#menubar-layout-xml]
=== menubar.layout.xml

Once configured, the extension provides a number of menu actions.
You can use `menubars.layout.xml` to arrange these as you see fit.
To get you started, the following fragment adds all of the actions to an "Activity" secondary menu:

[source,xml]
.menubars.layout.xml
----
<mb3:secondary>
    ...
    <mb3:menu>
        <mb3:named>Activity</mb3:named>
        ...
        <mb3:section>
            <mb3:named>Execution Log</mb3:named>
            <mb3:serviceAction id="findMostRecent" objectType="causeway.ext.executionLog.ExecutionLogMenu"/>
            <mb3:serviceAction id="findExecutions" objectType="causeway.ext.executionLog.ExecutionLogMenu"/>
            <mb3:serviceAction id="findAll" objectType="causeway.ext.executionLog.ExecutionLogMenu"/>
        </mb3:section>
        ...
    </mb3:menu>
</mb3:secondary>
----


[#secman-security-roles]
=== SecMan Security Roles

If xref:security:secman:about.adoc[] extension is configured, then permissions must be granted to access the menu actions.

This can be done by granting the role set up by the xref:refguide:extensions:index/secman/applib/role/seed/CausewayExtExecutionLogRoleAndPermissions.adoc[] seed fixture script (see its `ROLE_NAME` constant).


== User Interface

The extension provides a number of menu actions and contributions.

The menu actions are as listed in xref:menubar-layout-xml[], above.
They allow the administrator to query the persisted commands.
Typically access to these actions would be restricted, see xref:secman-security-roles[security roles] above.

The extension also provides these mixins:

* xref:refguide:extensions:index/executionlog/applib/contributions/Object_recentExecutions.adoc[]
+
This contributes a `recentExecutions` collection to each and every domain object.
+
This can be explicit positioned through the domain class' own xref:userguide:fun:ui.adoc#object-layout[layout file], but this is generally not necessary: it will slot into the tab group in the layout file indicated for unreferenced collections using `<tabGroup unreferencedCollections="true">`.

* xref:refguide:extensions:index/executionlog/applib/contributions/HasUsername_recentExecutionsByUser.adoc[]
+
This contributes the `recentExecutionsByUser` collection to any domain object that implements the xref:refguide:applib:index/mixins/security/HasUsername.adoc[] interface.
+
Most notably, this is xref:security:secman:about.adoc[] extension's xref:refguide:extensions:index/secman/applib/user/dom/ApplicationUser.adoc[] entity that represents a logged-on user.
It is also supported by xref:security:sessionlog:about.adoc

* xref:refguide:extensions:index/executionlog/applib/contributions/HasInteractionId_executionLogEntries.adoc[]
+
This contributes the `executionLogEntries` property to any object implementing xref:refguide:applib:index/mixins/system/HasInteractionId.adoc[] interface.
Typically these are the entities persisted by the xref:commandlog:about.adoc[] or xref:security:audittrail:about.adoc[] extensions, making it easy to traverse between these logs.




[#notes]
== Notes

include::commandlog:partial$commandsubscriber-vs-executionsubscriber.adoc[]

== See also

* xref:refguide:applib:index/services/iactn/Interaction.adoc[interaction]
* xref:refguide:applib:index/services/iactnlayer/InteractionService.adoc[].
* xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[] SPI
* xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[] SPI
* xref:commandlog:about.adoc[] extension

