Adding analytic headers

An analytic header is a series of declarative tags enclosed in a comment at the beginning of a script. The header includes input parameters that a user populates in advance, which allows the analytic to run unattended, either immediately, or at a scheduled time.

After you develop scripts in an ACL project, you must add an analytic header before you can commit the scripts to Robots, or use the project as an analysis app on AX Server or in the Analysis App window.

Analytic header requirements

An analytic header must conform to certain requirements. If it does not conform, the analytic script fails when run.

For detailed information about analytic header syntax, and a full list of analytic tags, see Analytic headers and tags.

Enclose analytic headers in a comment block

Analytic headers must be completely defined in a comment block that starts on the first line of the script.

COMMENT
Analytic tags go here.
END

Declare inputs and outputs

In the analytic header, you must declare any inputs required by the analytic, and any outputs that are copied to Robots or AX Server, or written out as results in the Analysis App window:

Inputs Outputs
  • tables
  • fields
  • parameters
  • input files
  • password prompts
  • data files
  • results tables
  • log files

Declare input values

Analytic headers must also declare any input values that users will specify when they run or schedule the analytic.

Use the PARAM tag to add input parameters that accept user-specified input values and store them in variables. For example, if you want an analytic to select data based on a date range, you need to add Start Date and End Date input parameters that allow users to specify these dates.

Validating analytic headers

After you add an analytic header to one or more scripts, use tools in ACL to validate the header syntax to ensure that it is correct. Perform the validation before committing scripts to Robots, or packaging analysis apps, so that the analytics do not fail when they run.

One tool validates individual analytic headers at the script level. The other tool validates all the analytic headers in a project at once. The two types of validation focus on different things.

Validate an individual analytic header

Script-level validation of an analytic header focuses on the syntax of individual analytic tags and reports errors with accompanying line numbers.

  1. Open the script containing the analytic header.
  2. On the Script Editor toolbar, click Validate Analytic Header  .

    A message appears telling you that the analytic header is valid, or specifying an error and the line number where the error occurs.

  3. If the analytic header contains an error, correct the error and click Validate Analytic Header  again to ensure that there are no further errors.

    Tip

    If the nature of the error is not apparent based on the error message, review the Help topic for the associated analytic tag. Carefully compare the syntax in the topic with the syntax in the line of the analytic header. Errors can be caused by minor discrepancies in the analytic header syntax.

Validate all the analytic headers in a project

Project-level validation of the analytic headers checks two things:

  • at least one analytic header exists in the project
  • names of multiple analytics are unique

    Note

    Refers to the name specified in the ANALYTIC tag, not the script name in the Overview tab in the Navigator.

Project-level validation is performed automatically when you commit scripts to Robots. You can also perform the validation manually if you add the Check Scripts button to the ACL toolbar.

  1. If necessary, add the Check Scripts button to the ACL toolbar:
    1. Double-click an empty spot on the toolbar to open the Customize Toolbar dialog box.
    2. In the Available toolbar buttons list, select the Check Scripts button and click Add.
    3. In the Current toolbar buttons list, select the Check Scripts button and click Move Up or Move Down to change the location of the button.

      The order of the buttons from top to bottom corresponds to their location from left to right on the toolbar.

    4. Click Close to save your changes.

  2. On the toolbar, click Check Scripts .

    A message appears telling you that the analytic headers in the project are valid, or specifying one or more errors.

  3. If the analytic headers contain an error, correct the error and click Check Scripts again to ensure there are no further errors.

Example analytic header

COMMENT
//ANALYTIC Identify missing checks
  This analytic identifies missing check numbers
//TABLE v_table_payments Payments Table
  Select a table that lists payments and includes a check number column
//FIELD v_check_num CN Check Number
  Select the field that contains the check numbers
//PARAM v_start_date D OPTIONAL Start Date (Optional)
  Enter the start date for the analysis
//PARAM v_end_date D OPTIONAL End Date (Optional)
  Enter the end date for the analysis
//PARAM v_region C MULTI SEPARATOR , QUALIFIER ' Region(s)
  Enter one or more regions to include in the analysis
//RESULT LOG
//RESULT TABLE MissingChecks
//RESULT FILE MissingCheckDetails.xls
END

(C) ACL Services Ltd. All Rights Reserved.

Saturday, April 20, 2019