IMPORT GRCPROJECT command
Concept Information
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>> <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:
|
|||||||
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.
|
|||||||
FROM org_id/type_id |
The organization and type of information that defines the data being imported:
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 IDorg_id must include the organization ID number, and if you are importing from a data center other than North America (US), the data center code. The organization ID number and the data center code must be separated by the at sign ( @ ) and a hyphen ( - ): FROM "125@-eu" Note If you specify the North America (US) data center code it uses a slightly different format, without a hyphen: FROM "125@us" The data center code specifies which regional HighBond server you are importing the data from.
You can use only the data center code or codes authorized for your organization's instance of HighBond. The North America (US) 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 Import HighBond Projects data. Type IDtype_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:
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 Import HighBond Projects 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.
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. |
|||||||
CHARMAX max_field_length optional |
The maximum length in characters for any field in the Analytics table that originates as character data in the Projects table. Data in the Projects table 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:
|
Examples
Importing specified fields from the Projects table
You import specified fields from the Projects table for all active projects belonging to organization 286 (US region) to an Analytics table named All_Projects:
IMPORT GRCPROJECT TO All_Projects "C:\HighBond Projects 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 Projects table
You import all fields from the Projects table for all active projects belonging to organization 286 (US region) to an Analytics table named All_Projects. You include a numbered password definition to authenticate the connection:
IMPORT GRCPROJECT TO All_Projects "C:\HighBond Projects Data\All_Projects.fil" PASSWORD 1 FROM "286@us/audits"
Limiting field length when importing from the Projects table
You import all fields from the Projects table to an Analytics table named All_Projects. You use the CHARMAX parameter to limit field length.
IMPORT GRCPROJECT TO All_Projects "C:\HighBond Projects Data\All_Projects.fil" PASSWORD 1 FROM "286@us/audits" CHARMAX 200
In the resulting Analytics table, all fields that originate as character data in Projects are limited to the specified length of 200 characters. Any field values that exceed the limit are truncated to 200 characters.
Importing all fields from the Issues table
You import all fields from the Issues table for all active projects belonging to organization 11594 (European region) to an Analytics table named All_Issues:
IMPORT GRCPROJECT TO All_Issues "C:\HighBond Projects Data\All_Issues.fil" FROM "11594@-eu/findings"
Remarks
For more information about how this command works, see Import HighBond Projects data.
Creating a password definition and specifying a password value
When you run a script in Robots that imports a HighBond Projects table, you need to include a password definition with the IMPORT GRCPROJECT 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.
-
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.
-
-
Do one of the following:
-
Use an existing token
-
In the Token column, click the partially masked token that you want to use.
-
Enter your HighBond account password and click Confirm.
The unmasked token is displayed.
-
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
-
Click Add token > Analytics.
-
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. -
Click Generate token.
-
Click Copy to copy the token.
Tip
Do not close the side panel containing the token until you have successfully pasted the token.
-
-
-
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.
-
-
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.