-
Notifications
You must be signed in to change notification settings - Fork 0
/
auditlog.html
116 lines (95 loc) · 8.13 KB
/
auditlog.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
---
layout: default
head_title: "LESK: Audit log"
title: Audit log
---
<div class="row">
<div class="12u">
<p>To enable the optional audit log simply set the <em>AUDIT_ENABLED</em> variable to <em>true</em> in the <em>.env</em> file as shown
below:</p>
<pre><code>AUDIT_ENABLED=true</code></pre>
<p>By default the audit log is disabled. When enabled some user actions can log an entry in the application audit log by calling the static function <em>Audit::log()</em> as demonstrated below:</p>
{% highlight php %}
// Create simple audit log entry
Audit::log(Auth::user()->id, 'User', 'Access list of users.');
{% endhighlight %}
<p>The full parameter list for the <em>log()</em> function is:</p>
{% highlight php %}
log($user_id, $category, $message, Array $attributes = null, $data_parser = null, $replay_route = null)
{% endhighlight %}
<p>Parameter info:</p>
<ul>
<li><em>$user_id:</em> The id of the user that triggered the action, can be null when a user is not authenticated.</li>
<li><em>$category:</em> Free text to group log entries, later we should be able to filter and search by the category.</li>
<li><em>$message:</em> Free text containing the main message.</li>
<li><em>$attributes:</em> An array containing any additional data that should either be displayed on the <em>show</em> page or be used by the replay action.</li>
<li><em>$data_parser:</em> The full name, including namespace and class name of the function to call to parse the data array stored in <em>$attributes</em>.</li>
<li><em>$replay_route:</em> The name of the Laravel route that will be called to replay this action.</li>
</ul>
<h4>Replay action</h4>
<p>The replay action feature, as the name suggests, allows to replay or repeat an action that was previously logged from the audit log. For the replay action to be available both the <em>attributes</em> and the <em>replay_route</em> parameters must be specified.
Perhaps the best and easiest way to understand how it functions is to follow a concrete example. Below I will describe how the replay action is used in the case of a user edit.</p>
<h5>Creating a replay-able audit log entry</h5>
<ol>
<li>
<p>The operator (human) click on the link to edit the entry of a user, say ID #3, the URL would look something like this <em><a href="http://lesk/admin/users/3/edit">http://lesk/admin/users/3/edit</a></em>.</p>
</li>
<li>
<p>The controller <em>UsersController</em> and its function <em>edit</em> are invoked. The <em>edit</em> function prepares the data that will be displayed and edited then pass it all to the view <em>admin.users.edit</em>. Note that in the <em>edit</em> function an audit log entry is created stating that the operator initiated the edition of the user. This is just a simple audit log entry that does not save any <em>attributes</em> or sets the <em>replay_route</em>, it is there simply for audit purposes.</p>
</li>
<li>
<p>The view is built and returned to the operator to see in his browser.</p>
</li>
<li>
<p>The operator makes the changes that are required and submits the form.</p>
</li>
<li>
<p>The controller <em>UsersController</em> and its function <em>update</em> are invoked. As expected <em>update</em> function will capture the data and update the user's record in the database, but it will also create an audit log entry that can be replayed. Here are the steps required in details:</p>
</li>
<li>
<p>Capture the posted attributes from the request:</p>
<p><pre><code>$attributes = $request->all();</code></pre></p>
</li>
<li>
<p>Add any data that would be needed by the replay function, here we want to make sure to add the id of the user since it was passed as a separate parameter to the <em>update</em> function:</p>
<p><pre><code>$replayAtt["id"] = $id;</code></pre></p>
</li>
<li>
<p>Finally, create the audit log entry:</p>
{% highlight php %}
Audit::log( Auth::user()->id, 'User', "Edit user: $user->username",
$replayAtt, "App\Http\Controllers\UsersController::ParseUpdateAuditLog", "admin.users.replay-edit" );
{% endhighlight %}
</li>
</ol>
<p>That is it, you are done, a replay-able audit log entry has been created. Note the 4th and 6th parameters.
The 4th parameter (<em>replayAtt</em>) is the array of attributes that will be filtered to remove the session token and passwords, then converted into JSON and stored in the <em>data</em> column.
The 6th parameter (<em>admin.users.replay-edit</em>) is the name of the Laravel route that will be invoked when a replay action is requested.
The 5th parameter is the fully qualified function name that will be used to parse the <em>data</em> field. That will be described in a section below on displaying entry details and custom rendering partials.</p>
<h5>Triggering a replayable entry</h5>
<p>Following the example above, here is a description of how triggering a replayable action function:</p>
<ol>
<li>The operator (human) access the audit log page at: <em>http://lesk/admin/audit">http://my-lesk-site/admin/audit</em></li>
<li>Locates the replay-able entry by it's spinning recycling icon in the action column, and click on it.</li>
<li>The <em>replay</em> function of the <em>AuditsController</em> controller is invoked. The <em>replay</em> function locates the audit log entry from the id passed in, and redirect to the Laravel route that is stored in the <em>replay_route</em>. In this case, it is <em>admin.users.replay-edit</em>.</li>
<li>The <em>admin.users.replay-edit</em> route triggers the function <em>replayEdit</em> in the <em>UsersController</em> controller, as defined in the <em>app\Http\routes.php</em> file.</li>
<li>The <em>replayEdit</em> function performs the following:</li>
<li>Locates the audit log entry from the ID passed in from <em>AuditsController::replay()</em>.</li>
<li>Grabs the data field and decodes it from json the associative array.</li>
<li>Locates the user object in question from the ID field of the data array.</li>
<li>Creates a new audit log entry for good measure.</li>
<li>Update or overwrite the value of the user object with the value from the data array.</li>
<li>Save the user object.</li>
<li>Redirect to the user's edit page for the operator to confirm or edit some more.</li>
</ol>
<h5>Displaying entry details and custom rendering partials</h5>
<p>An audit log entry that is replayable will most likely have some data attributes that make it unique and has to be processed
in order to be displayed properly. In the call to the <em>Audit::log()</em> function above that creates the replay-able entry, the
5th parameter, the <em>data_parser</em>, is the fully qualified name of a function that will get called to prepare the data before
returning the view displaying the details to the browser.
Additionally, the <em>data_parser</em> function can add to the <em>data</em> array an entry with a key of <em>show_partial</em> that points to
a partial blade file that will be responsible for rendering the parsed data of the audit log entry. If no <em>show_partial</em> is
specified the default behaviour is to use <em>var_dump()</em> to simply dump the value on the page.</p>
</div>
</div>
{% include footer.html prev_page="persistentsettings" prev_title="Persistent settings" next_page="jqgrid" next_title="jqGrid datatables & reports" %}