This documentation supports releases of BMC Helix Dashboards up to December 31, 2021. To view the latest version, select the version from the Product version menu.

Running the migration tool

The migration tool migrates the reports to BMC Helix Dashboards in the same folder structure as in BMC Helix ITSM: Smart Reporting. If a folder does not exist in BMC Helix Dashboards, the migration tool automatically creates the folder. For example, if a report resides in the BMC Remedy Operational Reporting folder in BMC Helix ITSM: Smart Reporting , the tool migrates it into the same folder in the BMC Helix Dashboards. We recommend that you validate the migrated reports after the migration is complete and make sure that they were migrated successfully.

Important

If BMC Helix Dashboards already contains a dashboard with a similar name, migration fails for that specific report.

The following report types can be migrated by using the migration tool:

  • Tabular report
  • Bar charts:
    • 3D Horizontal Bar
    • 3D Vertical Bar
    • Histogram
    • Horizontal Bar
    • Horizontal Cylinder
    • Layered Bar
    • Proportional Bar
    • Stacked Horizontal Bar
    • Stacked Vertical Bar
    • Vertical Bar
  • Pie charts:
    • 3D Pie
    • Multi Pie
    • Pie
    • Ring

Important

  • If your report type does not fall into the above categories, the migration tool migrates such reports in a tabular format to BMC Helix Dashboards. After migration, these reports are suffixed with the text _TABULAR (for example, <reportname>_TABULAR).
  • If there are duplicate reports, the report name will be appended with the report ID and _TABULAR after the migration. For example, <reportname>_reportID_TABULAR.
  • Reports in BMC Helix ITSM: Smart Reportingthat use the cross-tab plug-in will be converted to BMC Cross-Tab in BMC Helix Dashboards
  • Reports in BMC Helix ITSM: Smart Reporting that uses the Numeric Display chart type will be converted to Stat in BMC Helix Dashboards.  
  • The migration tool can migrate dashboards with multiple charts, such as bar chart, pie chart, table, and so on. If the chart type is not supported, the migration tool migrates the panel in table format. If there are multiple panels with similar chart types, the panels will display the similar titles after migrating to BMC Helix Dashboards irrespective of their title in BMC Helix ITSM: Smart Reporting. The user needs to manually update the panel titles in BMC Helix Dashboards.

To manually copy the reports that cannot be migrated by using the migration tool, see Copying reports and dashboards from BMC Helix ITSM: Smart Reporting to BMC Helix Dashboards.

Before starting migration, you must understand the end-to-end process for migrating the reports:

 

Before you begin

Make sure that the following prerequisites are met: 

  • Assess the BMC Helix ITSM: Smart Reporting environment. For more information, see Assessing the BMC Helix ITSM: Smart Reporting environment.
  • Identify the reports that you want to migrate. You can run the SQL queries to determine the reports that you want to migrate. For more information, see Assessing the BMC Helix ITSM: Smart Reporting environment.
  • Apply the following hotfixes based on your Smart Reporting version:
    • If you are using the Smart Reporting 21.3 version, apply 21.3.03 HF5.
    • If you are using the Smart Reporting 21.05 version , apply 21.05.03 HF8.
  • In the Remedy AR server, create a user with a floating or fixed license type. This user should also have access to all the reports in Smart Reporting. Assign the following roles and permissions to the user in Smart Reporting:
    • Add Web Service Permission to a role and assign the role to the newly-created user. For information about creating and assigning roles and permissions, see Managing Smart Reporting user roles Open link .
    • Add super user permission to the role that is assigned to the newly-created user. For more information, see Granting Content Super User permission to access and manage all content Open link . The super user permission helps you to migrate the private reports or reports residing in a secured folder. You must add the required permissions for those reports after migrating to BMC Helix Dashboards. For more information about adding permissions, see Adding dashboard permissions.
      After assigning the super user permission, the newly-created user will be able to migrate private reports and reports from the secured folders.

    • Add the newly-created user to the default client organization. For more information, see Defining a Smart Reporting administrator for the default client organization Open link .
    • Set password for the newly-created Smart Reporting user.

      • Log in to the BMC Helix ITSM: Smart Reporting console as the siadmin user by entering the following URL in a browser:
        http://SmartReportingWebServerName:portNumber/SmartReporting
      • Select the Default Client Organization and click Login. 
        This option is displayed when the siadmin user has access to multiple client organizations.
      • Select Administration > AdminConsole and expand the Users section.
      • Select System Administrator > Edit.
      • In the Password field, enter and confirm the password and click Update.
      • Click Save.
    • Change the password for the newly-created user.
      For more information, see  Changing the Smart Reporting super admin password after installation Open link .

  • The BMC Helix Dashboards tenant is updated to version 22.2 or later. 
  • Java version 11 is installed on the machine where you want to run the migration tool.
  • JAVA_HOME path is set where you want to run the migration tool.


To download and extract the migration tool

  1. Log in to BMC Support Central and access the  Knowledge article 000398185 Open link .
  2. Download the migration tool BMC_Helix_ITSM_Smart_Reporting_to_BHD_Conversion_Tool from the Attachments section of the knowledge article, and extract to a new folder.


To retrieve the list of reports for migration

If your organization has a large number of reports to be migrated, you can retrieve the list of reports in a CSV file. The report list can be retrieved either for the tabular report type or for all report types in your account. The following information is captured in the CSV file:

  • Report Name
  • Report ID
  • Folder Name
  • Subfolder Name
  • Last Modified By
  • Report Type
  • Last Modified Date

To retrieve the list of the tabular reports

Run the following command to retrieve the list of the tabular reports in your account:

conversioncli.bat --action=getTabularReports

To retrieve the list of all reports

Run the following command to retrieve the list of all reports in your account:

conversioncli.bat --action=getAllReports


To run the migration tool

  1. After the migration tool is downloaded and extracted, specify the parameters of BMC Helix ITSM: Smart Reportingand BMC Helix Dashboards in the cliconfig.properties file from the extracted folder.

    ParameterDescription
    srurlSmart Reporting URL from where the reports will be migrated.
    reportuserReport user name.
    reportpasswordReport user password.
    clientorg

    Default client organization of the server user.

    Important

    If you have multi-tenant configured in BMC Helix ITSM: Smart Reporting, ensure to perform the following actions:

    • Enter the clientorg name as it appears in the Smart Reporting system. 
      The clientorg name is case-sensitive.
    • The clientorg name may contain a single backslash followed by any one of the following characters - f, n, r, t. Alternatively, the backslashes should be included in pairs only.
    • The client org name may contain single or double quotes but should not be combined with any backslashes.
    • In the clientorg name, do not enter tab spaces.
    bhd_url

    BMC Helix Dashboards URL where the reports should be migrated. For example, https://helixdashboards.bmc.com/dashboards/.

    bhd_user

    User name of the BMC Helix Dashboards administrator.

    bhd_password

    BMC Helix Dashboards administrator's password.

    bhd_accesskey

    BMC Helix Dashboards access key.
    You can obtain the access key from BMC Helix Portal. For more information, see  Setting up access keys for programmatic access Open link .

    bhd_secretkey

    BMC Helix Dashboards secret key.

    You can obtain the secret key from BMC Helix Portal. For more information, see  Setting up access keys for programmatic access Open link .

    bhd_tenant_id

    BMC Helix Dashboards tenant ID.

    You can obtain the tenant ID from BMC Helix Portal. For more information, see  Setting up access keys for programmatic access Open link .

    api_service_url

    API service URL of BMC Helix Dashboards. For example, https://helixdashboards.bmc.com/.

    report_csv_pathPath to the CSV file that contains the list of reports to be migrated.  
    truststorepassword <optional>Truststore file password of the conversion utility if the server is secured.
  2. Create a CSV file in the extracted migration tool folder and specify the name of the reports that you want to migrate exactly the way they appear in BMC Helix ITSM: Smart Reporting
    You can get the name of the reports from the list that you retrieved in To retrieve the list of reports for migration.
    If the BMC Helix Dashboards tenant contains a report with same name, specify the report ID along with the report name separated by comma in the CSV file; for example, Compliance,60932. If there are multiple reports with similar names, the migration tool appends the report ID to the report name.

    Important

    For better performance, we recommend that you migrate the reports in smaller batches. Do not edit the CSV file while the migration tool is running.
  3. Open the command prompt and run one of the following commands to generate the Smart Reporting metadata for the reports listed in the CSV file:

    • If you want to generate the Smart Reporting metadata in the extracted migration tool folder, run the following command:

      conversioncli.bat --action=getSRmetadata
    • If you want to generate the Smart Reporting metadata in a different folder, run the following command:

      conversioncli.bat --action=getSRmetadata -fp "<output json file location (optional param)>"
    • If you do not want to specify the password in the cliconfig.properties file, comment out the password parameters in the cliconfig.properties file, run the following command, and enter the passwords when prompted:

      conversioncli.bat -a getSRmetadata -srap -srrp

      The above commands generate the following files:

      • reportmeta.json: Contains the details of each report, such as report attributes, filters, SQL, category, subcategory, report type.
        You can validate the reportmeta.json file to ensure that all the reports identified in the CSV file have been successfully included for the migration.

      • sr_bhd_conversion.log: Contains all entries of the migration activity.

      • reportstatus.csv: Provides the status of each report.

        Important

        If you want to migrate reports with same name in both the applications and you are not aware of the report ID of a specific report, run the following command to migrate all reports that have same names in both the applications:

        conversioncli.bat --action=getSRmetadata --allow_duplicate=true


  4. Run one of the following commands to migrate reports to BMC Helix Dashboards:

    • If the Smart Reporting metadata is stored in the extracted migration tool folder, run the following command from that folder:

      conversioncli.bat --action=createDashboardsContent
    • If the Smart Reporting metadata is stored in a different folder, run the following command:

      conversioncli.bat --action=createDashboardsContent -fp "<output json file location (optional param)>"
    • If you do not want to specify the password in the cliconfig.properties file, comment out the password parameters in the cliconfig.properties file. Run the following command and enter the password when prompted:

      conversioncli.bat -a createDashboardsContent -bhdap


Validate the migration

After running the migration tool, check the log summary report in the sr_bhd_conversion.log file. This report provides the details about the conversion rate of the reports from BMC Helix ITSM: Smart Reporting to BMC Helix Dashboards. Take any necessary actions based on the details in the log file. We recommend that you validate the visualization, formatting, and filters in the migrated dashboards. You can manually update the dashboards if they have not been migrated appropriately. Also validate the existing cross-launch links, report schedules, and update them, if needed.


Results of the migration

After migrating the reports from BMC Helix ITSM: Smart Reporting to BMC Helix Dashboards, view the migrated reports in the BMC Helix Dashboards.

After migrating the reports to BMC Helix Dashboards, you can configure additional panels and queries on your dashboards. For more information, see Setting up dashboards.

Important

Only the tenant administrator can view the migrated dashboards and folders in BMC Helix Dashboards. Add the required permissions for other users to view and edit the dashboards and folders. For more information, see Adding dashboard permissions.


Limitations of the migration tool

The migration tool has the following limitations:

Issue symptomsCauseResolution

BMC Helix Dashboards fails to migrate the cross-launch URLs.

After migrating the reports, the cross-launch URLs will not be functional anymore.

Manually add the cross-launch URLs in the migrated reports by using BMC Helix Dashboards. For more information, see Adding reverse cross-launch links from BMC Helix Dashboards to BMC Helix ITSM applications.

BMC Helix Dashboards sets the predefined date and time range to 30 days after migration.

The reports in BMC Helix ITSM: Smart Reporting contain a different predefined date and time range. 

Set the required date and time range by using BMC Helix Dashboards after migration. For more information, see To configure time range.

BMC Helix Dashboards fails to display the calculated field names after migration.

The BMC Helix Dashboards fails to render the correct labels for calculated fields. 

Manually set the calculated field names in BMC Helix Dashboards after migration. For more information, see Service Management query.

BMC Helix Dashboards fails to display data for reports with a filter condition, and fails to display data for filters.

The report from the BMC Helix ITSM: Smart Reporting system has a filter defined for complex queries or the report contains cascading filters or calculated fields.

After migrating the reports, update the filters by using variables, and manually update the SQL query to see the correct list of values in the filters.

BMC Helix Dashboards fails to display the field names in pie charts.

This issue occurs due to a Grafana limitation.

Edit the dashboard panels to specify the field names in pie charts.

BMC Helix Dashboards represents multiple slices in pie chart in same color.

This issue occurs due to a Grafana limitation.

There is no workaround at this time.

Conditional formatting and table calculations are not migrated.

The report in BMC Helix ITSM: Smart Reporting contains conditional formatting and calculation within a table. 

There is no workaround at this time.

BMC Helix Dashboards fails to fetch reports with large SQL queries.

The report has SQL query exceeding 4000 characters. There is no workaround at this time. 

The migration tool fails to migrate reports which are not in English locale.

The migration tool only migrates reports which are in English locale.

There is no workaround at this time.


Troubleshooting

This section helps you troubleshoot some errors that might appear while using the migration tool:

Issue symptomsCauseResolution

Report does not exist in BMC Helix ITSM: Smart Reporting.

The report name that you specified in the CSV file is not the same to the name in the BMC Helix ITSM: Smart Reporting system. 

Specify the report names in the CSV file exactly as they appear in BMC Helix ITSM: Smart Reporting.

Preconditioned Failed - Dashboard already exists with status code: 412.

A dashboard already exists in BMC Helix Dashboards with the same name.

Rename the report in BMC Helix ITSM: Smart Reporting before migration.

Exception: Report user specified has no access to the requested report - [Error code: 66].

The user does not have permissions to view the report in BMC Helix ITSM: Smart Reporting.

Provide necessary permissions to the user to view all reports. For more information, see Managing Smart Reporting user roles Open link .

Exception occurred while executing query [Error code: -2].This error message is displayed when the migration tool connects to the database.You can ignore this error message.

BMC Helix Dashboards fails to display the appropriate column names with advanced functions configured.

The specific column has an advanced function configured.

To resolve this issue:

  1. Edit the dashboard panel. 
  2. Select Transform > Organize fields
  3. Update the column name as specified in the Smart Reporting system.

BMC Helix Dashboards fails to display the appropriate column names with subqueries.

The dashboard has subqueries configured.

To resolve this issue:

  1. Edit the dashboard panel. 
  2. Select Transform > Organize fields
  3. Update the column name as specified in the Smart Reporting system.

BMC Helix Dashboards fails to display the correct order of the fields in Cross-tab reports after migration.

The reportmeta.json file changed the order of field names.

To resolve this issue:

  1. Edit the dashboard panel.
  2. In BMC Cross-tab panel, select Fields. 
  3. Re-arrange the order of the fields and save the dashboard. 

The Smart Reporting metadata conversion summary displays the total number of reports without SQL query.

The BMC Helix ITSM: Smart Reporting contains large SQL queries.

There is no workaround at this time.


Known issues

For a list of known issues pertaining to the migration tool, see Known and corrected issues.


Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Benoit McNicoll

    Hello team,

    The link to get the ebhd_tenant_id, bhd_accesskey and bhd_secretkey is incorrect. For the Migration Tool, an API key will not work. A key type Access needs to be created after clicking the "New Key".

    Please, correct doc. Thanks

    Jul 26, 2022 02:34
    1. Shantanu Chatterjee

      Hi Benoit,

      The links have been corrected to point to the Helix Portal doc containing the steps to create an Access key type.

      Thanks,

      Shantanu

      Jul 27, 2022 06:41
  2. Steven Egan

    Hi Team, Within the parameter details, would it be possible to detail the default URL format for Helix Dashboards as below as this may not be well known to new users of Helix Dashboards?

    BMC Helix Dashboards URL where the reports should be migrated. E.g. https://.onbmc.com/dashboards/api/v1/dashboard

    Regards, Steven

    Aug 12, 2022 07:42
    1. Shantanu Chatterjee

      Thanks for your comment, Steven. 

      We've added a sample dashboards URL.

      Thanks,
      Shantanu

      Sep 12, 2022 12:19
  3. Diego felipe Rodriguez gomez
    Hello Team,
    

    Where I can find the API service URL of BMC Helix Dashboards.

    Sep 01, 2022 10:32
    1. Shantanu Chatterjee

      Hi Diego,

      We've added a sample API URL for your reference.

      Thanks,
      Shantanu

      Sep 12, 2022 12:20
  4. Parul Mittal

    Will the above steps work for migrating Smart Reporting reports from 9.1 to the Helix Dashboard?

    Nov 14, 2022 11:16
    1. Shantanu Chatterjee

      Hi Parul,

      Thanks for writing to us. 

      Smart Reporting 9.1 is not supported by the migration tool. The minimum supported versions are:

      21.3.03 HF5. 21.05.03 HF8

      Thanks, Shantanu

      Nov 15, 2022 12:41