Exporting exceptions to the Results app in Diligent One

If you use Diligent One, 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.

Results is a remediation and workflow automation app that manages exception data, adds human context through questionnaires, and makes your monitoring continuous with triggers and metrics. For more information, see Working with data in Results.

Security requirements

The ability to export exception data to a control test in Results requires a specific Diligent One 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.

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

For more information, see Results app permissions.

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 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 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 dropdown 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 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.

   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 Diligent One 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)
     • jp – Asia Pacific (Tokyo)
     • 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 Diligent One. 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. In the Scope panel, select the appropriate option:

   • All
   • First
   • Next
   • While
   Show me more

   Scope option	Details
   All	(Default) Specifies that all records in the view are processed.
   First	Enter a number in the text box. Starts processing at the first record in the view and includes only the specified number of records.
   Next	Enter a number in the text box. Starts processing at the currently selected record in the view and includes only the specified number of records. The actual record number must be selected in the leftmost column in the view, not data in the row.
   While	Use a WHILE statement to limit the processing of records in the view based on a particular criterion or set of criteria. 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 First or Next options reference either the physical order or the indexed order of records in a table. First or Next disregard any filtering or quick sorting applied to a table view. However, output 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.

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 need to specify a password to export to Results in either of these situations:

• you used offline activation to activate your copy of Analytics

• you use a script to export to Results, and you run the script in Robots

The required password value is a HighBond access token.

Acquire a HighBond access token

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 Diligent One.

   Access to the Manage API tokens page through Analytics is a convenience feature. You can also sign in to Diligent One 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 Diligent One 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. Diligent One 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 Diligent One 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 data access and password definition method you are using, do one of the following:

   Analytics user interface

   Paste the copied token into a password prompt that appears when accessing Diligent One manually.

   Analytics script

   • PASSWORD command Paste the copied token into a password prompt that appears during script execution.

   • SET PASSWORD command 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.