Exporting exceptions to HighBond Results

If you use HighBond, you can export exception data in an Analytics table to a table in Results. To export exceptions, you use the standard procedure for exporting data from Analytics, with some minor differences.

Security requirements

The ability to export exception data to a control test requires a specific HighBond role assignment, or administrative privileges:

• Users with a Professional User or Professional Manager role for a Results collection can export results to any control test in the collection.

  Note

  Only users with the Professional Manager role can overwrite existing data in a control test.

• HighBond account admins and Results admins automatically get a Professional Manager role in all collections in the HighBond instances they administer.

Password requirement

Password not required

You do not need to specify a password to export to Results if you used online activation to activate your copy of Analytics. The password is automatically created and sent to Results based on activation information stored on your computer.

Password required

You do need to specify a password to export to Results if you used offline activation to activate your copy of Analytics. The required password value is a HighBond access token.

Acquire a HighBond access token

1. On the Analytics main menu, select Tools > HighBond Access Token.

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

2. Do one of the following:
   • Use an existing token In the Token column, click the partially masked token that you want to use and enter your HighBond account password. The unmasked token is displayed.

     Tip

     Use an existing 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.

   • Create a new token Click Create token > Analytics and enter your HighBond account password.

     A new Analytics token is created.

     Note

     If you are a Launchpad System Admin, you also have the option of creating an API token. You should reserve API tokens for their intended purpose, which is programmatic access to the HighBond platform.

3. Click Copy to copy the token.

   Tip

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

4. In Analytics, paste the token into the password prompt.
5. In Launchpad, close the dialog box 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 access tokens.

Export limits

The limits that apply when exporting to a control test in Results are shown below.

Within these limits, you can export multiple times to the same control test. If data already exists in the control test, you have the option of overwriting it, or appending the new data.

Item	Maximum
Records per export	100,000
Records per control test	100,000
Fields per record	500
Characters per field	256

Keeping fields aligned between Analytics and Results

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 ( _ )

Overwrite option and Results primary key

When you export exception data from Analytics to an existing Results table you have the option of appending the exported data to the table, or completely overwriting the table.

If the Results table has a field specified as a primary key, and the data you are exporting contains a corresponding field, the export behavior differs somewhat. (For more information about specifying a primary key in Results, see Specifying a primary key.)

The different possibilities are summarized below.

	No primary key in Results	Primary key in Results
Overwrite table option not selected	exported data is appended to the existing Results table	matching value if a matching value exists in the primary key field in Results and the corresponding field exported from Analytics, the record in Results is updated with the values present in the exported record no matching value if a matching value does not exist in the primary key field in Results and the corresponding field exported from Analytics, the record in Results is not updated and the exported record is appended to the table
Overwrite table option selected	exported data replaces (overwrites) the existing Results table	exported data replaces (overwrites) the existing Results table

Export exceptions to Results

Specify the fields to export

1. Open the table with the exception data that you want to export.
2. Select Data > Export.
3. On the Main tab, select one of the following:
   • Fields specify which fields you want to export

     When you select this option, the fields are exported using the physical field names in the table layout.

     For information about renaming fields, see Rename a field in a table layout.

   • View export all fields in the current view

     When you select this option, the fields are exported using the column display names. The fields are exported in the same order as they appear in the view.

     For information about renaming columns, see Rename columns in a view.

4. If you chose Fields, do one of the following:
   • Select the field(s) to export from the Export Fields list.

     Tip

     You can Ctrl+click to select multiple non-adjacent fields, and Shift+click to select multiple adjacent fields.

   • Click Export Fields to select the field(s), or to create an expression.

Select the export options

1. In the Export As drop-down list, select HighBond.
2. Do one of the following:
   • Append to the Results table

     If you want to append the exported data to the existing table in Results leave Overwrite table deselected.

     Note

     Analytics fields can only be appended to existing Results fields if they have matching physical field names, regardless of their display name in either application. In Analytics, the physical field name is the name in the table layout.

     The order of fields within the two applications does not affect field name matching.

     Exported fields with physical names that do not match the physical name of a field in the Results table create new columns in the table.

   • Replace (overwrite) the Results table

     If you want to replace the existing table in Results select Overwrite table.

   For more information, see Overwrite option and Results primary key.

3. (Optional) If you want to export column display names to Results, select Include field display name.

   Selecting this option makes the column display name and the physical name in Results identical to the names in Analytics.

   If you do not select Include field display name, the result depends on whether you are exporting by fields or by view:

   	Exporting Fields	Exporting View
   Include field display name selected	Field name in Results is the field name from Analytics. Display name in Results is the display name from Analytics.
   Include field display name not selected	Field name and display name in Results are the field name from Analytics.	Field name and display name in Results are the display name from Analytics.

   Note

   Do not select Include field display name if you are appending a view to a Results table that was initially created by exporting a view from an Analytics version older than 14.1. Doing so may export columns with field names that are not the same as the names in Results, which will create new columns in Results and misalign the data between applications.

Finalize the export

1. If there are records in the current view that you want to exclude from processing, enter a condition in the If text box, or click If to create an IF statement using the Expression Builder.

   Note

   The If condition is evaluated against only the records remaining in a table after any scope options have been applied (First, Next, While).

   The IF statement considers all records in the view and filters out those that do not meet the specified condition.

2. Do one of the following:

   If you know the ID number of the table you are exporting to:

   Enter the number in the To text box.

   • Enter the number without any quotation marks – for example, 99
   • Enter only the number. Do not enter a file name.
   • If you are exporting to a data center other than North America (US), you must also specify the data center code. The control test ID number and the data center code must be separated by the at sign (@) – for example, 99@eu. The data center code specifies which regional HighBond server you are exporting the data to.
     • af – Africa (South Africa)
     • ap – Asia Pacific (Singapore)
     • au – Asia Pacific (Australia)
     • ca – North America (Canada)
     • eu – Europe (Germany)
     • sa – South America (Brazil)
     • us – North America (US)

     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 ID number of the table you are exporting to, or if you want to create a new table:

   1. Click To, and in the Select Destination Test dialog box navigate to the appropriate analysis folder.
   2. Do one of the following:
      • Select an existing table and click OK.
      • Enter a name in the New data analytic field and click Create.

      You are returned to the Export dialog box and the control test ID number and data center code are prefilled in the To text box.

3. Click the More tab.

4. Select the appropriate option in the Scope panel:

   • All
   • First
   • Next
   • While
   Show me more

   All	This option is selected by default. Leave it selected to specify that all records in the view are processed.
   First	Select this option and enter a number in the text box to start processing at the first record in the view and include only the specified number of records.
   Next	Select this option and enter a number in the text box to start processing at the currently selected record in the view and include only the specified number of records. The actual record number in the leftmost column must be selected, not data in the row.
   While	Select this option to use a WHILE statement to limit the processing of records in the view based on a particular criterion or set of criteria. You can enter a condition in the While text box, or click While to create a WHILE statement using the Expression Builder. A WHILE statement allows records in the view to be processed only while the specified condition evaluates to true. As soon as the condition evaluates to false, the processing terminates, and no further records are considered. You can use the While option in conjunction with the All, First, or Next options. Record processing stops as soon as one limit is reached.
   Note The number of records specified in the First or Next options references either the physical or the indexed order of records in a table, and disregards any filtering or quick sorting applied to the view. However, results of analytical operations respect any filtering. If a view is quick sorted, Next behaves like First.

5. Click OK.

   A progress indicator appears while the exception data is exported to Results. When the export operation is complete, an entry is created in the log.