Business Intelligence integration

To add a new synchronization configuration

1. From the Main menu, select Administration > Utilities > Integration > BI Integration.

2. In the configuration drop-down, select  New configuration to open the dialog box.

3. Complete the following fields.

   Field	Description
   Name	Enter a name for the configuration. The name cannot be modified after the configuration is created.
   Ongoing query policy	Select an ongoing query policy: Ongoing full operations stack query. Export all updates occurred on the specified record types and fields during the specified time frame. No data are exported if no updates were made. Ongoing last snapshot query. Export the latest updates occurred on the specified record types and fields during the specified time frame. Note For the Service Level Target-related record types and expense line, the latest updates occurred during the specified time frame are exported for both ongoing query policies.
   File preserving time	Specify how long the output files are saved in the system: 3 days 1 week 2 weeks 1 month 2 months

4. Click Save.

To define record type data to synchronize

1. From the Main menu, select Administration > Utilities > Integration > BI Integration.
2. On the left, under Record types, select a record type from the drop-down list. For example, select Incident.

3. Open the fields tab (Incident fields) and select the fields to be synchronized for incident records. You can search for a field in the search window.

   After you select fields, the Selected tab appears, which displays only the selected fields.

4. Open the many to many relationships tab (Incident many to many relationships) and select the relationships to be synchronized for incident records. You can search for a relationship in the search window.

   After you select relationships, the Selected tab appears, which displays only the selected relationships.

5. Click  Save on the toolbar.

6. You are now prepared to run the BI integration API. Before performing an actual integration, it is recommended to run a mock integration of a full sync using sample data to help understand the integration more thoroughly. The mock integration runs more quickly than an actual integration and involves a smaller impact on your system.

   Follow these steps:

   1. Click the Download test data button to run the sync.
   2. An output file is generated for each selected record type and relationship type. The record data in the files is based on actual data from the tenant. The relationships are based on sample data (not on actual data).
   3. The format of the sample data output files follows the format of regular BI sync output files. For more information, see Output format. The record type output files contain a maximum of 100 records. The relationship type output files contain a maximum of 50 relationships.

To remove a record type synchronization configuration

1. Select the required record type configuration in the list on the left.

2. Click Remove on the toolbar and click Confirm to confirm the deletion.

The following best practices provide an outline of the main phases of the integration for customer administrators:

1. Define the synchronization configuration based on your need.

2. Configure the integration.

   • Configure the sync process by specifying a list of record types with properties and relationships to be exported. It is usually only necessary to export a subset of data (record types, fields, and relationships). It is recommended to select the Id and LastUpdateTime fields for every selected record type to facilitate the proper identification and ordering of the generated records.

   • Create an integration user in Suite Administration to be used specifically for the integration. The user should be assigned only the Service Portal User and Business Intelligence Integration roles, and should be used for the BI integration exclusively.

3. Perform the initial sync.

   • Run an initial sync using the BI integration Initial data sync API. This generates an initial data snapshot as a set of ZIP/CSV files.

   • Check the status of the initial sync using the BI integration Get Status API until the job is complete.

   • Access the results of the initial sync using the BI integration Get Status API as a list of links to FRS ZIP/CSV files.

   • Retrieve the ZIP/CSV files for the initial sync using the FRS API.

4. Perform the ongoing sync.

   • Run an ongoing sync using the BI integration Ongoing data sync API. This generates a list of all updates or the last updates for the specified record types and fields that occurred since the previous sync based on your sync configuration.

   • Check the status of the ongoing sync using the BI integration Get Status API until the job is complete.

   • Access the results of the ongoing sync using the BI integration Get Status API as a list of links to FRS ZIP/CSV files.
   • Retrieve the ZIP/CSV files for the ongoing sync using the FRS API.

   • Repeat this phase periodically as required.

The following example demonstrates how to run the BI integration:

1. To perform the integration, define two users as follows:

   • a tenant admin user
   • a basic user with only two roles: Service Portal User and Business Intelligence Integration

2. Log into Service Management application as a tenant admin user. Navigate to the BI Integration page. For more information on the BI Integration user interface, see Business Intelligence integration and Configure a synchronization.

3. Define multiple synchronization configurations as needed and select the following record types and fields for synchronization:

   • For Request, select Active, Description, Phase Id, Title, Category, Created time, SLT, Status, Assignment Group, Assignee, Service, and Priority.
   • For Incident, select Active, Description, Phase Id, Title, Category, Created time, SLT, Status, Assignment Group, Assignee, Service, and Priority. Also select one relationship: Incident caused by request.
   • For Person, select Email, First name, Id, Last name, Name, Office phone number, and User principal name.
   • For Group, select Company, Group type, Id, Name, Owner, and User principal name.
   • For Service Level Target, select Id, Name, Parent, Parent type, Priority, Record type, Service, Status, Target date, and Target type.
   • For Actual service, select 1st level support, Description, Display label, Id, Name, Owner, and Subtype.
4. Log out and log in again as the basic user.

5. In an external REST tool, create a JSON file with the following parameters:

   • X-XSRF-TOKEN
   • Accept:application/json
   • Content-Type:application/json

6. Run the BI Initial data sync REST call: POST: <host>:<port>/rest/<tenantId>/bi/initial/new. The body should be {"BiSyncConfigurationName":"<configuration name>"}.

   For an example of the response JSON, see Initial data sync.

7. Using the syncId from the response JSON, run the Status REST call: GET: <host>:<port>/rest/<tenantId>/bi/status/<syncId>.

   For an example of the response JSON, see Get status.

   Save the output in an external tool for later reference. The status response includes a status for each output file. If they are all COMPLETE, you can proceed. If not, run the status command again. Save the fileId value from each section of the response JSON in an external tool.

8. For each fileId, construct a URL as follows: <host>:<port>/rest/<tenantId>/bi/file-list/<fileId>. Save this in an external tool. Paste each URL into the address bar of another browser tab of the same window to execute the FRS REST call and automatically download the file to your downloads directory. For information on the format of the output files, see Output format.

   Note  

   • If the system contains a large amount of data, the output files may be split into multiple files. Thus, it is possible to have more than one file per record type.
   • The FRS files are deleted from the system after the defined preserving time exceeds. Make sure to download the files before they are deleted.

9. Update some requests and incidents, making sure to change some of the properties defined in the BI configuration. In addition, create some new requests and incidents.

10. In an external REST tool, create a JSON file with the same parameters as above.

    Run the BI Ongoing data sync REST call: POST: <host>:<port>/rest/<tenantId>/bi/ongoing/new. The body should be: {"BiSyncConfigurationName":"<configuration name>","LastUpdateTime":"<timestamp>","SyncEndTime":"<timestamp>"}. For time of previous sync, enter the LastUpdateTime value from the output of the Status REST call in step 7.

    For an example of the response JSON, see Ongoing data sync.

    Note Some of the files may not contain any data, depending on the time between initial sync and the ongoing sync and the number of updates performed.

11. Using the syncId from the response JSON, run the Status REST call: GET: <host>:<port>/rest/<tenantId>/bi/status/<syncId>.

    Save the output in an external tool for later reference. The status response includes a status for each output file. If they are all COMPLETE, you can proceed. If not, run the status command again. Save the fileId value from each section of the response JSON in an external tool.

12. For each fileId, construct a URL as follows: <host>:<port>/rest/<tenantId>/frs/file-list/<fileId>. Save this in an external tool. Paste each URL into the address bar of another browser tab of the same window to execute the FRS REST call and automatically download the file to your downloads directory. For information on the format of the output files, see Output format.

    Note  

    • If the system contains a large amount of data, the output files may be split into multiple files. Thus, it is possible to have more than one file per record type.
    • The FRS files are deleted from the system after the defined preserving time exceeds. Make sure to download the files before they are deleted.