Working with analytic headers

An analytic header is a series of analytic tags enclosed in a comment block at the beginning of a script. The tags specify either script inputs or script outputs.

For a visual overview of analytic script inputs and outputs, and associated analytic tags, see Script inputs and outputs – the big picture.

Tags that specify user-facing input parameters let a user specify script input values in advance, which means an analytic script can run unattended, either immediately, or at a scheduled time.

After you develop scripts in an Analytics project, you must add an analytic header to at least one script 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.

Using the Analytic Header Designer is the easiest way to add or modify an analytic header. You can also add or modify an analytic header manually.

The Analytic Header Designer

The Analytic Header Designer has an intuitive interface for progressively adding the analytic tags that make up an analytic header. You are free to add, modify, or delete tags as you build an analytic header.

Automated error checking and embedded guidance in the Designer help ensure that the header you build is valid and works correctly.

When you click Save in the Designer, the tags that you have configured are automatically translated into an analytic header at the top of the script. You can manually edit the analytic header if you want to, but the recommended approach is to reopen the Designer to perform edits.

Sample analytic header

The analytic header shown below, for an analytic script that identifies missing checks, was created using the tags shown in the Analytic Header Designer above. To save space, the screen capture of the Designer is sized to show only a subset of the tags in the analytic header.

COMMENT
//ANALYTIC TYPE ANALYSIS Identify missing checks
  This analytic script 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 ' VALUES |Northeast|Southeast|Central|Western|West Coast| Region(s)
  Enter one or more regions to include in the analysis
//RESULT TABLE Missing_Checks
//RESULT FILE Missing_Checks.xls
//RESULT LOG
END

COMMENT The body of the script starts here.
SET SAFETY OFF
OPEN %v_table_payments%
.
.
.
SET SAFETY ON

What each tag does

Each analytic tag in the sample analytic header above performs a specific task when a user schedules or runs the associated analytic script in a client application.

COMMENT . . . END

//ANALYTIC

//TABLE v_table_payments

//FIELD v_check_num

//PARAM v_start_date

//PARAM v_end_date

//PARAM v_region

//RESULT TABLE Missing_Checks

//RESULT FILE Missing_Checks.xls

//RESULT LOG

Build an analytic header

To build an analytic header you must know in advance what script inputs and outputs you need. For more information, see Identify script inputs and outputs.

Set up the base configuration of the analytic header

Add additional analytic tags

After setting up the base configuration of the analytic header, you can add as many additional analytic tags as you need.

You can add tags in any order.

1. In the Analytic Header Designer, click Add tag.
2. Select a Tag type.
3. To configure the tag, complete all the required fields in the tag configuration section, and any optional fields that you need.

   Guidance for configuring tags is embedded in the configuration section for each tag.

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

4. Repeat the process for each additional tag that you need in the analytic header.
5. Click Save when you are finished.

Validating analytic headers

After you add an analytic header to one or more scripts, use tools in Analytics 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 analytic scripts 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 analytic scripts are unique

  Note

  The name of the analytic script is 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 Analytics toolbar.

1. If necessary, add the Check Scripts button to the Analytics 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.