Auditing and logging

Rules – The Audit Log

By Mark Kehoe © MI Consulting

1

Save Harbour Statement This document may include predictions, estimates or other information that might be considered forward-‐looking. While these forward-‐looking statements represent our current judgment on what the future holds, they are subject to risks and uncertainties that could cause actual results to differ materially. You are cautioned not to place undue reliance on these forward-‐looking statements, which reflect our opinions only as of the date of this presentation. Please keep in mind that we are not obligating ourselves to revise or publicly release the results of any revision to these forward looking statements in light of new information or future events. Throughout today’s discussion, we will attempt to present some important factors relating to our business that may affect our predictions.

Pre-‐requisites In order to get the most out of the document you will have had some training in the Oracle | RightNow CX product around administration and analytics. You’ll also be familiar with editing reports and with what rules do, and might have had a go at writing rules. The document has some complicated analytics but the report you need is available to import. This document covers some new functionality on the system, and anyone who has been around the product for a few years is going to be pleased that a new table and a new piece of functionality has been exposed. The CX version used for this document is Feb ’13. This document has been written an informal style, to impart experience rather than as a formal training document. If you would like to receive training on rules, administration or any aspect of Oracle | RightNow CX contact us at [email protected] or on 1300 732 783 or via LinkedIn.

Introduction Writing clear and concise rules is part of good systems administration and I’ve covered this topic in an earlier document. This document will focus on audit reports around incident rules. We’re aiming to empower our agents to understand how the system works. Often people say “the system just did it on it’s own” without any thought that a person has either written the system to do something in a particular way or they’ve made an honest mistake and are struggling to find the problem.



2

Topics Covered This document is written to allow you to pick the parts that you need, but based around audit reports.

1. Outer Joins 2. DECODE 3. Using Message Bases within reports

A lot of stuff came up when I tried to write the most complete document I could, so if you run a multi-‐language implementation there’s a section in the analytics to enable you to multi-‐language your reports. To recap something I’ve already raised in ‘Rewriting the rules’. Here I’m trying to make the rules as human-‐readable as possible:

Figure 1: Detailed rule log

This shows how rules can be made to be as clear as possible to the systems administrator, but next we’re going to offer the new clarity to our agents too.

Rule log table vs. transactions table Notice that I’m referring back to the rule log rather than the audit trail. We’ve looked at the readable rule log (which is a system function); now let’s look a the audit trail against the workspace for the same incident:



3

Figure 2: Incident Audit Log

The audit log report contained on the workspace contains less information and appears to have jumbled up the queue assignment. Actually the rules fire so fast that the fractions of a second for the same function (queue) have the same date/time stamp. On older releases there would be nothing you could do to improve this report, but now the rule_log table has been exposed and the workspace control for the incident audit log has been exposed and is available as a standard report. This new workspace report exists in:

Service à Views – Service à Editor Reports – Service It is called ‘Incident Audit Log’. This is a very clever report, but misses out on our rich reporting found in the log viewer (for those of us who have been around the system awhile will remember this report used to be hard-‐coded into the audit control within the workspace designer). We now have a new table called ‘rule_log’ that contains the additional information used in log viewer (again, those of us who have been around the system awhile will know that this too was a hard-‐coded report). We need to produce a better audit trail for our users in the workspace to help them help us administrators spot errors in the system. Note to the wise: There is a system utility called agedatabase. It is designed to purge some of the system audit tables (such as the rule_log table) that accumulate a lot of information. Remember to change the system parameter to a longer period according to your business requirements. We need to combine the best of the Log Viewer and Audit Log against the incident workspace. Let’s copy the Incident Audit Log report to our work area and edit it:



4

Figure 3: Incident Audit Report

We would like to change this report to include additional audit details, but a quick look around the report is pretty daunting. First, lets look at the table joins:

Figure 4: Table joins

We can see that there are lots of tables and they all have outer joins. Let’s look at the queues join:

Figure 5: Outer join against queues table



5

The outer join states: transactions.id1 = queues.queue_id AND transactions.trans_type = 17 AND queues.qtype = 1 The trans_type = 17 is a really important part of this report. We are going to be referring to this a lot in this document. Okay, let’s break this down:

1. Only show me the queue if it matches the queue in this transaction 2. Only show me the transaction types of 17 (queue type transactions) 3. Only show me queues of type 1 (incident queues rather than chat queues)

You might need a strong cup of tea at this point, and this is the easy part! I want to hijack this report and it currently looks like this:

Figure 6: Incident Audit Report in the Reports Explorer

Basically anything ‘Changed queue’ by ‘Administrator’ (The System) needs to be removed and I need to insert the data from the log viewer. When reading the report ‘Changed Queue’ doesn’t really do justice to what’s happening here. I’m not just changing queue, I’m sorting out Smart Assistant, setting the priority and assigning an SLA. My rule_log report that looks like this:

Figure 7: Log Viewer Report



6

So before changing the ‘Incident Audit Report’ lets create a new report called ‘Log Viewer Report’. We’ll look at my ‘Log Viewer Report’ and pick up some new skills as we go:

Figure 8: Table joins for rule_log

The incidents table is there to pass the incidents.i_id to the report so that I can report on a single incident. The fields in the rule_log table are fairly self-‐explanatory (just throw them all onto the workspace) and we don’t need to do anything to the Rule Name column; it comes out perfect. Add a filter for incident.i_id and sort it by sequence and we’re golden. The Action Clause column (rule_log.rule_type) needs some work. It returns 0 for THEN and 1 for ELSE. I’ve had to convert the 0’s and 1’s into human-‐readable words. To do this I have a couple of choices. The obvious method is this: IF(RULE_LOG.RULE_TYPE = 0,’Then’,’Else’) If we have a zero, show the word ‘Then’, otherwise show the word ‘Else’. Simples? Well not if this is a multi-‐language site, and actually when we come to look at the Incident Audit Report later on we need another skill. This is how I’ve written the Action Clause column: decode(rule_log.action_clause,0,msg_lookup(7996),msg_lookup(7948)) The first thing you’ll notice is MSG_LOOKUP. This enables me to return a word from the message base that relates to a particular word or phrase. Why? Well, this is a multi-‐language report – but more importantly the other report, Incident Audit Report, uses this function heavily so this is an introduction to something you might not be familiar with. It also uses DECODE quite a bit too, so I’m easing you in gently. MSG_LOOKUP To find a corresponding word in the message base for a word we want to use, open up the Message Bases and search for your word (I’ve looked for the word ‘else’):



7

Figure 9: Using message bases in reports

Now select the one you want with a click and open it up. The message base entry ID isn’t obvious (in fact I can’t see it displayed anywhere). The only way you can find it is by hovering over the open message base item with your mouse (can mice hover?):

Figure 10: Message base entry ID

Hopefully the following statement makes more sense now: decode(rule_log.action_clause,0,msg_lookup(7996),msg_lookup(7948)) Clearly 7996 represents THEN and 7948 represent ELSE but we could put in any word from the message bases we like. This is handy if you have an English, French and Swedish interface and don’t want three different reports.

Incident Audit Report With Log Viewer Report written let’s move onto the Incident Audit Report. The first thing to do is drop the ‘Changed Queue’ / ‘Administrator’ part of the report and insert our Log Viewer Report.



8

Figure 11: Incident Audit Report in the Reports Explorer

To do this, the rule_log table need to be added in as we had it in our little log report from earlier:

Figure 12: Table join



9

Figure 13: Joining the rule_log table

The join here is an outer join. Why? We are going to replace the existing queue stuff with the log stuff for the current incident. I’ve re-‐joined the incidents table against the queue table and checked that the new incidents table (INCIDENTS2) is for the same incident as the top level incident. This is because we want ONLY the rule_log data to match the incident we are currently outputting. This is a tricky concept so I’d recommend you try removing the outer join and see the results bothways. if(incidents.i_id=incidents2.i_id,1)

The ‘What’ Column We now have the extra data available now in the rule_log table. Let’s swap out the ‘Changed Queue’ (using message base entry ID 6651) word with the word ‘Rule’ from the message base – RULES_LBL (using message base entry ID 5324 in my system). Sitting comfortably? We need to change the ‘What’ column that has the following expression: decode(transactions.trans_type, 3, msg_lookup(9801), 6, msg_lookup(6653), 7, msg_lookup(9796), 8, if(transactions.source_lvl2 = 5018, nvl(channel_types.chan_type_id||' ', ''), '')||msg_lookup(9802), 14, msg_lookup(6766), 17, msg_lookup(6651), 24, if(transactions.id1 > 0, msg_lookup(31927), if(transactions.id4 > 0, msg_lookup(29301), msg_lookup(31927))) , 25, msg_lookup(20555), transactions.trans_type) To read the following: decode(transactions.trans_type, 3, msg_lookup(9801), 6, msg_lookup(6653), 7, msg_lookup(9796), 8, if(transactions.source_lvl2=5018, nvl(channel_types.chan_type_id||' ', ''), '')||msg_lookup(9802), 14, msg_lookup(6766), 17, msg_lookup(5324), 24, if(transactions.id1>0, msg_lookup(31927),



10

if(transactions.id4>0, msg_lookup(29301), msg_lookup(31927))) , 25, msg_lookup(20555), transactions.trans_type) Ouch. Try not to comprehend the whole statement, because you’ll be looking at it for a while – just concentrate on the nugget of information we’re interested in. In this case it is the trans_type = 17. Look for the 17 and figure just that little piece – then change it.

The ‘Description’ column We’re going to swap out the description from the TRANSACTIONS table with the description from the RULES_LOG table. Again, the expression is a bit of a mouthful: decode(transactions.trans_type, 2, $from_details, 3, if(transactions.source_lvl1=32001 & transactions.source_lvl2=24, msg_lookup(25240), $from_details), 4, $assigned_details, 6, inc_statuses.status_id, 8, transactions.description, 11, msg_lookup(33822) || ': ' || transactions.description, 13, '', 14, transactions.description, 15, msg_lookup(31907), 16, msg_lookup(31838) || transactions.id1, 17, queues.queue_id, 21, transactions.description, 37, msg_lookup(9614)||' '||channel_types2.chan_type_id, 48, $from_details) To make it even more difficult to understand there are a couple of variables in play, $from_details and $assigned_details. Actually without these two variables the size of the DECODE would be huge! We need to be focused on what we need without getting blinded by the long statement. Remember what we need? We want to replace the transaction details for queue (trans_type = 17) with the details from the rule log. So the decode needs to include whatever it is showing at the moment PLUS display our new field. The snippet from the decode reads: 17, queues.queue_id Let’s pull that out and put in our new field: 17, if(transactions.id1=3,rule_log.rule_name,queues.queue_id) ID1 = 3 in this case represents the queue work that has been done by The System (you’ll remember seeing ‘administrator’ as the user name in the log). That’s where we need our new rows. Anything that has been done by the agent needs to stay the same – for example where the agent has manually changed the queue. To make this more human-‐readable, I’d say that:



11

While the transaction type is for a queue, check if the system did the update. If it did, then show my rule log description otherwise just show me the queue name. The final statement looks like this: decode(transactions.trans_type, 2, $from_details, 3, if(transactions.source_lvl1=32001 & transactions.source_lvl2=24, msg_lookup(25240), $from_details), 4, $assigned_details, 6, inc_statuses.status_id, 8, transactions.description, 11, msg_lookup(33822) || ': ' || transactions.description, 13, '', 14, transactions.description, 15, msg_lookup(31907), 16, msg_lookup(31838) || transactions.id1, 17, if(transactions.id1=3,rule_log.rule_name,queues.queue_id) , 21, transactions.description, 37, msg_lookup(9614)||' '||channel_types2.chan_type_id, 48, $from_details) The finished report should now look like this:

Figure 14: Enhanced Incident Audit Report

Conclusion Good auditing makes how you use your system transparent. It enables agents to take control of their work and understand why things happen. It enables systems administrators to quickly get to the bottom of problems and combined with good rule-‐writing you’ll have a ‘get out of jail free’ card if something goes wrong and you need to fix it. Next up is my top 10 incident rules.

Auditing and logging

Technology

Transcript of Auditing and logging