9.1

Edit

Usage report tool

To make the updates of a customer environment safe and easy, WorkFusion utilizes anonymized statistics from the environment. Using these statistics, WorkFusion specialists can introduce safe changes to the system and delete obsolete functionality without compromising quality. The usage report tool improves customer experience during upgrades and enables early checks for deprecated functionality.

The resulting report data are stored securely within WorkFusion, whereas customer details are removed from it.

Get usage report tool

To get a usage report tool, build from sources (internal):

  1. Clone the repository.

  2. Build via Maven using the following command:

    mvn clean package

You can find the prepared artifact in the target/usage-report-tool-<VERSION>.jar archive.

Download a binary file:

Run usage report tool

  1. Copy the binary file to a machine with access to a MySQL server, preferably to the database host, for faster data retrieval.

  2. Create an application.properties file next to the tool with connection settings. Besides the connection option, you can also override the other ones in this file. In the example below, workfusion is a user with read-only access to the Control Tower (CT) database (DB).

    spring.datasource.url=jdbc:mysql://localhost:3306/wfdb?characterEncoding=UTF-8
spring.datasource.username=workfusion
spring.datasource.password=workfusion
spring.datasource.driver-class-name=com.mysql.jdbc.Driver

  3. Execute the usage report tool using the command below:

    <path_to_java>/java -jar usage-report-tool-<VERSION>.jar

    <path_to_java> is the /opt/workfusion/java/bin folder.

    Java version 8 or later is required to execute correctly the usage report tool.

Reports

You can find the generated report location in logs. See the example below:

2018-07-10 16:34:28.829  INFO 5610 --- [           main] c.w.urt.output.ExcelReportWriter         : Report was written into '/tmp/report/report/usage-report(2018-07-10 16-34-24).xlsx'

By default, it is the report folder.

In case of successful execution, the following Excel files are generated:

  • Content-based usage-report. See the sample report.
  • Execution-based audit-report. The report contains the bulk of statistical information that can be more convenient to look at using the Tableau dashboards or Platform Monitor.

Rename these reports by adding the environment type, name, and version so that you can easily identify them later.

Report checklist

  1. Double-check that reports contain no sensitive data. The Context column of the report can contain a few lines of Business Process (BP) steps.
  2. Add the environment name to the report file name.
  3. Send reports for analysis to WorkFusion, leaving a return address for WorkFusion specialists to get back to you. Alternatively, you can perform a manual review of the components based on the information in the Context column of the usage report.

Usage report

  1. By default, the usage report contains the following sheets:

    • Summary

      Contains matched entities grouped by the checker name or key.

    • Bot Configs

      Contains detailed info about the matched Bot Configs: where the Bot Config Bundle (BCB) is included (a BP or a Use Case) and its execution date. The Context column contains additional information. Supports matching inside included (nested) configurations. Standalone bot configurations are scanned but do not have a related process.

    • Bot templates

      Contains info about matched bot templates. Matching inside included configs is not supported.

  2. Each record begins with the Checker Name and Checker Key columns. The key is usually dynamic. For instance, it represents the imported class name in the import checker.

Checkers

Checker settings

  • Disable checkers via the following property in the application.properties file:

    checker.<CHECKER-NAME>.enabled=true

  • Configure the size of the match context via the following properties in the application.properties file:

     checker.<CHECKER-NAME>.context.lines.before=0
 checker.<CHECKER-NAME>.context.lines.after=0

  • Context gathering can be disabled for all checkers. This prevents gathering sensitive data from Bot Configs. To disable the context gathering, modify the following property in the application.properties file:

    analysis.checker.context.enabled=true

package-checker

Searches for import <class> statements. Configure a list of included or excluded packages via the following properties in the application.properties file:

#comma-separated list of included packages
checker.import-checker.included.packages=com.workfusion,com.freedomoss
#comma-separated list of excluded packages
checker.import-checker.excluded.packages=com.freedomoss.crowdcontrol.webharvest,com.freedomoss.crowdcontrol.webharvest.plugin.datastore.dto

plugin-usage-checker

Searches for <PLUGIN-NAME> statements. Configure a list of plugins via the following property in the application.properties file:

#comma-separated list of checked plug-in names
checker.plugin-usage-checker.names=web-service-builder,get-ie-content,cc-database,captcha,to-csv

raw-sql-checker

Searches for the following SQL-related strings:

  • com.mysql.jdbc
  • JdbcTemplate.class
  • mysql:jdbc:.*(wfdb|mturk)

It is used to identify direct CT or DB interaction via JDBC or JdbcTemplate. For successful troubleshooting, the match context should be as broad as possible.

spring-context-usage

Matches against the following regular expression:

ApplicationContextProvider.getContext\\(\\).getBean\\((?<key>[A-Za-z.]*)\\)

Use the check to retrieve Spring services from the context, for instance, jdbcTemplate to work with the CT DB.

system-exit-checker

Searches for the usage of the system.exit command in the content as it is considered bad practice. Do not use system.exit in Bot Configs.

Additional resources

Sample configuration for usage report tool

spring.datasource.url=jdbc:mysql://localhost:3306/mturk?characterEncoding=UTF-8
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.driver-class-name=com.mysql.jdbc.Driver

logging.level.com.workfusion=DEBUG

content.analysis.report.enabled=true
audit.report.enabled=true

#### Import Statement Checker Config ####
checker.package-checker.enabled=true
checker.package-checker.context.lines.before=0
checker.package-checker.context.lines.after=0
#comma-separated list of included packages
checker.package-checker.included.packages=com.workfusion,com.freedomoss
#comma-separated list of excluded packages
checker.package-checker.excluded.packages=com.freedomoss.crowdcontrol.webharvest,com.freedomoss.crowdcontrol.webharvest.plugin.datastore.dto,\
com.freedomoss.workfusion.utils.gson

#### Webharvest Plug-in Checker Config ####
checker.plugin-usage-checker.enabled=true
#comma-separated list of checked plug-in names
checker.plugin-usage-checker.names=web-service-builder,get-ie-content,cc-database,captcha,to-csv
checker.plugin-usage-checker.context.lines.before=0
checker.plugin-usage-checker.context.lines.after=1

#### MySQL Queries Plug-in Checker Config ####
checker.raw-sql-checker.enabled=true
checker.raw-sql-checker.context.lines.before=5
checker.raw-sql-checker.context.lines.after=5

#### Spring Context Queries Plug-in Checker Config ####
checker.spring-context-usage.enabled=true
checker.spring-context-usage.context.lines.before=1
checker.spring-context-usage.context.lines.after=1

#### Report Content Settings ####
#report sheets titles
report.sheet.summary.title=Summary
report.sheet.bot.config.title=Bot Config
report.sheet.bot.template.title=Bot Template

#### Report Output Settings ####
#output folder to contain generated report file
output.folder=report
#output content report file format with placeholder %s for timestamp
output.content.report.file.name=usage-report(%s)
#output audit report file format with placeholder %s for timestamp
output.audit.report.file.name=audit-report(%s)

#flag to turn on/off context gathering in case of passed check
analysis.checker.context.enabled=true
#how many lines are added to context before and after matched line by default
analysis.context.surrounding.lines=1

Sample report

To download a sample report, click the link.

← PreviousNext →