Migration module 1.2 and later only.

The Reporting Service is part of the Migration module. It's purpose is to log details about module migration and provide them in a report. You can write your own log statements and have the reporting service store them in the repository. The details you log can include errors, stack traces and code snippets. For example, during template script migration you can log attributes and values that should be added to template definitions. You can also use the Reporting Service for troubleshooting. It is unlikely that the migration works without a hitch on the first attempt. By logging error details you can fix them quicker.

When should I use the Reporting Service?

  • If your module is very straightforward, based on the STK or basic templating, you don't need the Reporting Service. You only need to add the ready-made migration tasks into your version handler. You don't need to write your own migration tasks.
  • If your module provides anything special such as custom logic you should write your own migration tasks. See the ready-made migration tasks for examples. You will need the Reporting Service to log and report details on the progress and errors.

Using the Reporting Service

Open the DefaultReportingServiceTest class and look at the examples at the end. You can find example log statements that range from simple to advanced. Copy the statements to your code and adapt them to your needs by changing the attributes. See the Reporting Service Javadoc for possible attributes and their value.

Getting the service instance

Start by getting the service.

ReportingService service = Components.getComponent(ReportingService.class);

Setting the detail level

Set the logging detail level.

  • WARN: Use of deprecated APIs, poor use of API, "almost" errors, other runtime situations that are undesirable or unexpected but not necessarily wrong.
  • INFO: Runtime events such as starting and stopping, moving to another process.
  • SYSTEM (default): Messages that can be important in case of failure. This is the default setting and usually enough.
  • DEBUG: High level of detail.
Java task
service.setLoggingLevel(task, ReportingLevel.DEBUG);
Groovy script
service.setScriptLoggingLevel(ReportingLevel.WARN);

Reporting a message

Use the report method to log a message. See the DefaultReportingServiceTest class and Javadoc for examples.

Java task
service.report(task, ReportingLevel.SYSTEM, "Message to log", RecordType.PLAIN, MessageType.INFORMATION, componentId);
Groovy script
service.report(scriptId, ReportingLevel.SYSTEM, "Message to log", RecordType.PLAIN, MessageType.INFORMATION, componentId);

Attributes

  • Task: Use task for Java update tasks and scriptId for Groovy scripts.
  • ReportingLevel: Detail level to capture.
    • DEBUG
    • ERROR
    • INFO
    • SYSTEM (default). Usually this is enough.
    • WARN
  • Message string to log.
  • RecordType: Format to write.
    • PLAIN
    • HTML
    • STACKTRACE
  • MessageType: 
    • INFORMATION. Information for the user reading the message.
    • MANUAL_ACTION_REQUEST. Something the user needs to do after the task has finished, such as edit a template script.
    • CODE_SNIPPET. Code that needs to be copied somewhere else.
  • componentId helps identify what component is the subject of the message. For example, if you log a code snippet that should be copied into the component's template script, identify the component here.

Setting the result

The result is the outcome of the migration task. This is where you tell the user whether the task failed or succeeded or whether more work is left. In case of failure, report any errors or details that help resolve the issue.

Success
service.setResult(task, TaskResult.SUCCESS, "Yupeeee!");
There's more work to be done.
service.setResult(scriptId, TaskResult.ATTENTION, "Please add the generated code snippets to your code.");

Viewing the report

The Reporting Service stores the logged statements in the repository. You can generate a report from the statements in AdminCentral.

  1. Go to Tools > Migration Report.
  2. Choose whether you want view the report as a single Web page or multiple files compressed into a zip file.

If you choose the zip option the service generates reports (HTML/PLAIN) in a hierarchical way. Main summary report and child pages). Define a common interface in order to add Report information from the migration task.

How does the service work

Producing the log

interface ReportingService
class ReportingServiceImpl

obtained via injection;

Storing the "logs" into JCR (CONFIG workspace - /server/install/migration-data/logs)

One node per module. Properties:

  • successes: number of successfully completed tasks
  • attentions: number of tasks that require attention
  • errors: number of failed tasks

Each task as a numbered subnode (ordered). Properties:

  • result: SUCCESS, ATTENTION, FAIL
  • info: string message

Each record as a numbered "sub-subnode" (e.g. /.../logs/standard-templating-kit/000001/000001). Properties:

  • level (system,debug,info,warn,error);
  • type (report, manual action request, code snippet);
  • contentType (plain,html,stacktrace,...?);
  • componentId (optional, ID of the component the record is about, e.g. template name);
  • message;

Methods

  • report(task,level,message); // type by default plain
  • report(task,level,message,type);
  • report(task,exception); // level = error, type = stacktrace, message = exception.getMessage();
  • setResult(task,result);
  • setResult(task,result,info); // adds the info to the task log's info property (doesn't overwrite!)
  • addInfo(task,info);