IMPORT GRCPROJECT command

Creates an Analytics table by importing a HighBond Projects table.

Syntax

IMPORT GRCPROJECT TO table import_filename PASSWORD num FROM org_id/type_id <FIELD name AS display_name <...n>>

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, PASSWORD 2 specifies that password #2 is used.

For more information about supplying or setting passwords, see:

Note

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

Analytics

(online activation)

PASSWORD is not required.

The current user's HighBond access token is automatically used.

Analytics

(offline activation)

PASSWORD is required.
Robots
Analytics Exchange
Analysis App window

FROM org_id/type_id

The organization and type of information that defines the data being imported:

  • org_id the Projects organization you are importing data from
  • type_id the type of information you are importing

The org_id value and the type_id value must be separated by a slash, with no intervening spaces: FROM "125@eu/audits".

The entire string must be enclosed in quotation marks.

Organization ID

org_id must include the organization ID number, and if you are importing from a data center other than North America, the data center code. The organization ID number and the data center code must be separated by the at sign (@): FROM "125@eu".

The data center code specifies which regional HighBond server you are importing the data from:

  • ap – Asia Pacific
  • au – Australia
  • ca – Canada
  • eu – Europe
  • us – North America

You can use only the data center code or codes authorized for your organization's instance of HighBond. The North America data center is the default, so specifying "@us" is optional.

If you do not know the organization ID number, use the Analytics user interface to import a table from Projects. The organization ID number is contained in the command in the log. For more information, see Defining ACL GRC data.

Type ID

type_id specifies the type of information you are importing. Information in Projects is contained in a series of related tables.

For type_id, use one of the values listed below. Enter the value exactly as it appears and include underscores, if applicable:

  • audits - Projects
  • control_test_plans - Control Test Plans
  • control_tests - Control Test
  • controls - Controls
  • finding_actions - Actions
  • findings - Issues
  • mitigations - Risk Control Associations
  • narratives - Narratives
  • objectives- Objectives
  • risks - Risks
  • walkthroughs - Walkthroughs

Tip

For information about how the tables in Projects are related, and the key fields that you can use to join the tables once you have imported them to Analytics, see Defining ACL GRC data.
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 must exactly match the physical field name in the Projects table, including matching the case
  • 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.

Tip

To get the physical field names, use the Analytics user interface to import the appropriate table from Projects. The physical field names are contained in the command in the log.

Subsequent imports can be scripted.

Examples

Importing all fields from the Projects table

You import all fields from the Projects table for all active projects belonging to organization 286 to an Analytics table named All_Projects. You include a numbered password definition to authenticate the connection:

IMPORT GRCPROJECT TO All_Projects "C:\ACL GRC Project Data\All_Projects.fil" PASSWORD 1 FROM "286@us/audits"

Importing specified fields from the Projects table

You import specified fields from the Projects table for all active projects belonging to organization 286 to an Analytics table named All_Projects:

IMPORT GRCPROJECT TO All_Projects "C:\ACL GRC Project Data\All_Projects.fil" FROM "286@us/audits" FIELD "id" AS "Id" FIELD "description" AS "Description" FIELD "name" AS "Name" FIELD "start_date" AS "Start date" FIELD "status" AS "Status" FIELD "created_at" AS "Created at"

Importing all fields from the Issues table

You import all fields from the Issues table for all active projects belonging to organization 286 to an Analytics table named All_Issues:

IMPORT GRCPROJECT TO All_Issues "C:\ACL GRC Project Data\All_Issues.fil" FROM "286@us/findings"

Remarks

Note

For more information about how this command works, see the Analytics Help.

Creating a password definition and specifying a password value

PASSWORD command

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

For more information, see PASSWORD command.

SET PASSWORD command

If you use the SET PASSWORD command to create the numbered password definition for connecting to HighBond, a password value is specified, so no password prompt is displayed, which is appropriate for scripts designed to run unattended.

For more information, see SET PASSWORD command.

HighBond access token

Regardless of which method you use to create the password definition, the required password value is a HighBond access token:

  • PASSWORD method – Users can acquire an access token by selecting Tools > HighBond Access Token, and then signing in to HighBond. An access token is returned, which users can copy and paste into the password prompt.
  • SET PASSWORD method – To insert an access token into the SET PASSWORD command syntax in an Analytics script, right-click in the Script Editor, select Insert > HighBond Token, and sign in to HighBond. An access token is inserted into the script at the cursor position.

Caution

The returned access token matches the account used to sign in to HighBond. As a scriptwriter, using your own access token may not be appropriate if you are writing a script to be used by other people.

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.

[ Back to top ]

ACL Scripting Guide 14.1