IMPORT GRCRESULTS command

Concept Information

Import HighBond Results data

Creates an Analytics table by importing a HighBond Results table or interpretation.

Syntax

IMPORT GRCRESULTS TO table import_filename PASSWORD num FROM Results_resource_path <FIELD name AS display_name <...n>> <CHARMAX max_field_length>

Parameters

Name Description
TO table

The name of the Analytics table to import the data into.

Note

Table names are limited to 64 alphanumeric characters. The name can include the underscore character ( _ ), but no other special characters, or any spaces. The name cannot start with a number.

import_filename

The name of the Analytics data file to create.

Specify import_filename as a quoted string with a .FIL file extension. For example, "Invoices.FIL".

By default, the data file (.FIL) is saved to the folder containing the Analytics project.

Use either an absolute or relative file path to save the data file to a different, existing folder:

  • "C:\data\Invoices.FIL"
  • "data\Invoices.FIL"
PASSWORD num

The password definition to use.

You do not use PASSWORD num to prompt for, or specify, an actual password. The password definition refers to a password previously supplied or set using the PASSWORD command, the SET PASSWORD command, or the PASSWORD analytic tag.

num is the number of the password definition. For example, if two passwords have been previously supplied or set in a script, or when scheduling an analytic script, PASSWORD 2 specifies that password #2 is used.

For more information about supplying or setting passwords, see:

The required password value is a HighBond access token. For more information, see Creating a password definition and specifying a password value.

PASSWORD num may or may not be required, depending on the environment in which the script runs.

Environment where script runs PASSWORD num requirement
Analytics

(online activation)

PASSWORD num is not required.

The current user's HighBond access token, stored in their Windows registry, is automatically used.
Analytics

(offline activation)

PASSWORD num is required.
Robots

FROM Results_resource_path

The path to the data you are importing.

The form of the path varies depending on the data you are importing. For details about the form of the path, see Results path.

Note

The form of the Results path is supplied by an API, and is subject to change. The easiest and most reliable way to acquire the correct and current syntax for the path is to perform a manual import of the target data, and copy the path from the command log.
FIELD name AS display_name <...n>

optional

Individual fields in the source data to import. Specify the name.

If you omit FIELD, all fields are imported.

Name

name must exactly match the physical field name in the Results table, including matching the case. To view the physical field name, do one of the following:

  • In Results, click a column header in the Table View. The physical field name appears after Field Name.
  • In Analytics, when you import a Results table, the physical field name appears in parentheses after the display name in the dialog box that allows you to select fields.

Note

The Results physical field name is not the display name used for column headers in the Table View.

Also see Field name considerations when importing and exporting Results data.

Display name

display_name (alternate column title) is the display name for the field in the view in the new Analytics table. You must specify a display name for each FIELD name. Specify display_name as a quoted string.

Use a semi-colon (;) between words if you want a line break in the column title.

Unlike some other IMPORT commands in Analytics, you cannot specify a blank display_name as a way of using the FIELD name as the display name.
CHARMAX max_field_length

optional

The maximum length in characters for any field in the Analytics table that originates as character data in the Results table or interpretation.

Data in the Results table or interpretation that exceeds the maximum field length is truncated when imported to Analytics.

The ability to truncate fields prevents occasional long values from expanding the overall record length beyond what is supported by the import process:

  • 32,767 characters (non-Unicode Analytics)

  • 16,383 characters (Unicode Analytics)

Examples

Importing specified fields from a table in Results

You import specified fields from a table in Results to an Analytics table named T and E exceptions:

IMPORT GRCRESULTS TO T_and_E_exceptions "C:\Secondary Analysis\T_and_E_exceptions.fil" PASSWORD 1 FROM "results/api/orgs/11594/control_tests/185699/exceptions" FIELD "metadata.status" AS "Status" FIELD "EmpNo" AS "Employee Number" FIELD "DATE" AS "Date" FIELD "CARDNUM" AS "Card Number" FIELD "CODES" AS "MC Codes" FIELD "AMOUNT" AS "Amount" FIELD "DESCRIPTION" AS "Description"

Importing all fields from a table in Results

You import all fields from a table in Results to an Analytics table named T and E exceptions:

IMPORT GRCRESULTS TO T_and_E_exceptions "C:\Secondary Analysis\T_and_E_exceptions.fil" PASSWORD 1 FROM "results/api/orgs/11594/control_tests/185699/exceptions"

Limiting field length when importing from a table in Results

You import all fields from a table in Results to an Analytics table named T and E exceptions. You use the CHARMAX parameter to limit field length.

IMPORT GRCRESULTS TO T_and_E_exceptions "C:\Secondary Analysis\T_and_E_exceptions.fil" PASSWORD 1 FROM "results/api/orgs/11594/control_tests/185699/exceptions" CHARMAX 200

In the resulting Analytics table, all fields that originate as character data in Results are limited to the specified length of 200 characters. Any field values that exceed the limit are truncated to 200 characters.

Importing data from an interpretation in Results

You import an interpretation in Results to an Analytics table named T and E exceptions filtered:

IMPORT GRCRESULTS TO T_and_E_exceptions_filtered "C:\Secondary Analysis\T_and_E_exceptions_filtered.fil" FROM "results/api/orgs/11594/control_tests/185699/interpretations/22699/exceptions"

Remarks

For more information about how this command works, see Import HighBond Results data.

Preserving sort order and filters

When you import data from Results, any data customization, such as sorting or filter, is retained or ignored in the resulting Analytics table depending on how you import the data:

  • import a table data customization is ignored. All the data in the table is imported, with the exception of any fields you choose to omit.
  • import an interpretation data customization is retained

Results path

Note

The form of the Results path is supplied by an API, and is subject to change. The easiest and most reliable way to acquire the correct and current syntax for the path is to perform a manual import of the target data, and copy the path from the command log.

The Results path in the FROM parameter takes the following general form:

FROM "results<-region code>/api/orgs/<org ID>/control_tests/<control test ID>/exceptions

For example:

FROM "results/api/orgs/11594/control_tests/4356/exceptions"

The org ID is displayed in the browser address bar when you log in to Launchpad. The control test ID, and the interpretation ID, are displayed in the address bar when you are viewing those tables in Results.

The table below provides variations of the Results path.

To import: Use this form of Results path:
Control test (table) data 
FROM "results/api/orgs/11594/control_tests/4356/exceptions"
Control test (table) audit trail 
FROM "results/api/orgs/11594/control_tests/4356/audit_trail"
Control test (table) comments 
FROM "results/api/orgs/11594/control_tests/4356/comments"
Interpretation 
FROM "results/api/orgs/11594/control_tests/4356/interpretations/1192/exceptions"
Data from a HighBond region other than the default region – North America (US)
  • Africa (South Africa)
    FROM "results-af/api/orgs/11594/control_tests/4356/exceptions"
  • Asia Pacific (Australia)
    FROM "results-au/api/orgs/11594/control_tests/4356/exceptions"
  • Asia Pacific (Singapore)
    FROM "results-ap/api/orgs/11594/control_tests/4356/exceptions"
  • Asia Pacific (Tokyo)
    FROM "results-jp/api/orgs/11594/control_tests/4356/exceptions"
  • Europe (Germany)
    FROM "results-eu/api/orgs/11594/control_tests/4356/exceptions"
  • North America (Canada)
    FROM "results-ca/api/orgs/11594/control_tests/4356/exceptions"
  • South America (Brazil)
    FROM "results-sa/api/orgs/11594/control_tests/4356/exceptions"

System-generated information columns

When you import data from Results, you have the option of also importing one or more of the system-generated information columns listed below.

The system-generated columns are either:

  • part of Results tables, and contain processing information related to individual records
  • additional information – collection name, table name, or record ID number

You must specify the field names of the system-generated columns exactly as they appear below. The default display names apply when you import from Results through the Analytics user interface. You are free to change the display names if you are scripting the import process.

Field name

Default display name

metadata.priority

Priority

metadata.status

Status

metadata.publish_date

Published

metadata.publisher

Publisher Name

metadata.assignee

Assignee
metadata.group Group
metadata.updated_at Updated
metadata.closed_at Closed
extras.collection Collection
extras.results_table Results Table
extras.record_id Record ID

Field name considerations when importing and exporting Results data

If you are round-tripping data between Results and Analytics, you need to ensure that all field names in the Results table meet the more stringent Analytics field name requirements. If you do not, you risk misaligning your Analytics and Results data.

For example, any special characters in Results field names are automatically converted to underscores when they are imported into Analytics, which means the field names no longer match the original names in Results. If you then export the Analytics data back to the original table in Results, fields are no longer correctly matched.

To avoid this problem with data that you intend to round-trip, make sure that before you upload the data to Results from CSV or Excel files it meets these Analytics field name requirements:

  • no special characters or spaces
  • does not start with a number
  • contains only alphanumeric characters, or the underscore character ( _ )

Creating a password definition and specifying a password value

When you run a script in Robots that imports a HighBond Results table or interpretation, you need to include a password definition with the IMPORT GRCRESULTS command. The same requirement applies to scripts run in Analytics if you used offline activation.

Regardless of which method you use to create a password definition, the required password value is a HighBond access token, which you can generate in Launchpad. For more information, see Acquire a HighBond access token.

Password definition methods

Method Description

PASSWORD analytic tag

(For scripts that run in Robots)

If you use the PASSWORD analytic tag to create the numbered password definition for connecting to HighBond, no password value is specified in the script. When you create a task to run the script in Robots, an input field in the Task Designer allows you or another user to specify the actual password.

For more information, see PASSWORD analytic tag.

PASSWORD command

(For scripts that run in Analytics, offline activation)

If you use the PASSWORD command to create the numbered password definition for connecting to HighBond, no password value is specified in the script. A password prompt is displayed when the script attempts to connect.

For more information, see PASSWORD command.

SET PASSWORD command

(For scripts that run in Analytics, offline activation)

If you use the SET PASSWORD command to create the numbered password definition for connecting to HighBond, a password value is specified in the script, so no password prompt is displayed. This approach is appropriate for scripts designed to run unattended, but it exposes an actual password in clear text in the script, which may not be appropriate for your situation.

For more information, see SET PASSWORD command.

Acquire a HighBond access token

Caution

The generated access token matches the account used to sign in to HighBond. As a scriptwriter, specifying your own access token in a script may not be appropriate if the script will be used by other people.

Safeguard access tokens like any account password.

Use an existing access token unless you have a reason for creating a new one. If the existing token does not work, create a new one. Using an existing token cuts down on the number of tokens you need to manage.

  1. Do one of the following:

    • From the Analytics main menu, select Tools > HighBond Access Token.

    • In the Script Editor, right-click and select Insert > HighBond Token.

    The Manage API tokens page opens in your browser. You may be required to first sign in to HighBond.

    Access to the Manage API tokens page through Analytics is a convenience feature. You can also sign in to HighBond and access the page through your user profile without using Analytics.

  2. Do one of the following:

    • Use an existing token

      1. In the Token column, click the partially masked token that you want to use.

      2. Enter your HighBond account password and click Confirm.

        The unmasked token is displayed.

      3. Click Copy to copy the token.

        Tip

        Do not close the dialog box containing the token until you have successfully pasted the token.

    • Create a new token

      1. Click Add token > Analytics.

      2. In the New Analytics token side panel, specify the following information:

        Field or option Description
        Description

        Enter a description that provides useful information, such as:

        • The purpose of the token
        • Where the token is used – for example, the name and location of the Analytics script, or the name and location of the robot task
        Token expiry
        • Enabled the token expires after the number of days that you specify
        • Disabled the token never expires

        Note

        Your organization may have a security policy that requires tokens to expire after a certain amount of time. Creating tokens with an expiry is a good practice. HighBond sends you an automated email notification in advance of the expiry date.

        Expires in Specify the number of days before the token expires (1 to 365).
        Password Enter your HighBond account password.

      3. Click Generate token.

      4. Click Copy to copy the token.

        Tip

        Do not close the side panel containing the token until you have successfully pasted the token.

  3. Depending on which password definition method you are using, do one of the following:

    • PASSWORD analytic tag In the Task Designer in an ACL robot, paste the copied token into a password parameter field.

    • PASSWORD command In Analytics, paste the copied token into a password prompt that appears during script execution.

    • SET PASSWORD command In Analytics, paste the copied token at the appropriate point in the SET PASSWORD command syntax in a script.

  4. In Launchpad, close the dialog box or the side panel containing the token.

    If you created a new token, a partially masked version of the token is added to the top of your list of tokens.

    For more information, see Creating and managing HighBond access tokens.

Import debug capability

A simple debug capability exists for imports from HighBond.

The imported data is temporarily stored in a JSON intermediary file in the folder containing the target Analytics project. In any folder containing an Analytics project you can create a text file that causes the JSON file to be retained, instead of being deleting after the data is imported into Analytics.

  • JSON file is present If the import from HighBond is failing, but the JSON file is present on your computer, you know that the problem is on the Analytics side, not on the HighBond side.
  • JSON file is not present If the import from HighBond is failing, and the JSON file is not present on your computer, you know that the problem is on the HighBond side.

This information can help with troubleshooting.

Configure retention of the JSON intermediary file

In the folder containing the target Analytics project, create an empty text file with exactly this name: _grc_import_debug.txt

When you import from either Results or Projects in HighBond, the JSON intermediary file is retained with the name results.json. The file is overwritten with each subsequent import from HighBond.

Importing large tables

Tables that have a large number of fields may not successfully import using a single IMPORT GRCRESULTS command. If you need to work with a single table containing a large number of fields outside of Results, use one of the following approaches:

  • Split the table use two or more IMPORT GRCRESULTS commands to import a subset of fields and then join the resulting tables in Analytics using the JOIN command
  • Export the table to file use the export to CSV format and then import the resulting file into Analytics using the IMPORT DELIMITED command