Creating external record definitions

An external record definition is a record definition that maps the external data, for example, from AR System forms so that the external data appears in the BMC Helix Innovation Studio as a local record instance. 

You can do the following with an external record definition:

  • Map the objects such as View components, Processes, Rules, and Named Lists to an external record definition like the regular record definition.
  • Perform CRUD (create, read, update, and delete) operations on external data sources so that they appear in BMC Helix Innovation Studio.

Important

The changes you make to external data in BMC Helix Innovation Studio also appear in the external data sources. However, if the external data sources do not provide the permissions to modify the external data, the external data operations fail in BMC Helix Innovation Studio.

  • Create external record definitions for AR System and Web API data source types.

Related topics

View-definition-components

Creating-a-view-for-a-record-instance-by-using-record-editor

Creating-a-REST-API-web-service-request-definition

Before you begin

Make sure you have created a project by using Maven and Archetype and deployed it in BMC Helix Innovation Studio. For more information, see Creating-a-Project-using-Maven-and-the-Archetype.

Important

Application business analysts can customize the objects developed in their applications and that are marked customizable by the administrator, but cannot customize the objects developed in com.bmc.arsys in Best Practice Customization mode. For example, objects in core BMC applications like Foundation, Approval, and Assignment cannot be customized in Best Practice Customization mode. For more information, see Customization-layer.

To create an external record definition for the AR System data source

  1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab. 
  2. Select the application for which you want to create a record definition.
  3. Select Records > New > External record. 

  1. In the Create new external record dialog box, complete the fields as described in the following table:

    Tab

    Field

    Action

    Data source

    Data source type

    Select AR System.

    Data source name

    From the list, select the name of the data source that you have configured.
    Important: All the data sources that you have configured for AR Systemare displayed in the list.

    Table selection

    Table

    Select a table name that represents the table in the external data source.

    Record ID fields

    Record ID field mappings

    To map the external field IDs to the BMC Helix Innovation Studio record ID fields, select the Record ID fields by using the External record ID field and External field ID. 

    Record ID fields are used to uniquely identify record instances. Typically, external record ID fields are automatically mapped to the BMC Helix Innovation Studio ID fields. Verify that the mappings are correct, and select the appropriate external record ID fields. 

    Field selection

    Available fields

    Select the fields from the table that you selected earlier.

    Important: On the Field selection tab, if you do not select the fields, the server implicitly adds them. The following image shows the Field selection tab:

    22_1_Create_new_external_record.png

  2. Click Save.

To create an external record definition for the Web API data source

  1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab. 
  2. Select the application for which you want to create a record definition.
  3. Select Records > New > External Record.

  4. In the Create New External Record window, complete the fields as described in the following table:

    Tab

    Field

    Action

    Data source

    Data source type

    From the list, select Web API.

    Data source name

    From the list, select the name of the data source that you have configured.
    Important: All the data sources that you have configured for Web API are displayed in the list.

    Web API selection

    Web API

    Select the Web API that you have configured.

    Document selection

    Documents

    Select the document that you have created for the Web API.

    Field selection

    Available fields

    In Available fields, the fields from the document that you selected are displayed. Select the fields that you want to add to the record definition, and click 2002_Add document fields in RD.png. These fields are displayed in the Selected fields section.

    The following image shows the Field selection tab:

    22_1_external_record_web_api_fields.png

    Map to Helix Display ID (Field ID =1)

    If you have a unique field in your record, you can map it with any of the following fields:

    • Map to Helix Display ID (Field ID = 1)
    • Map to Helix ID (Field ID = 379)

    Map to Helix ID (Field ID = 379)

    Operation selection

    Operation

    To get the data from the external record definition via web API, select GET.

    Web API request name

    Select the web API request that you created.

  5. In the Create New External Record window, click Save.

    Important

    When you create an external record definition for a web API, the system generates the fields for header, query parameters, path parameters, and body in the web API.

    For more information about web APIs, see Integrating with REST services in a codeless way.

To add fields to an external record definition

  1. Click New field and select the required datatype for the field.
  2. In the Add Fields From External Record section, select the available fields.
  3. Click Add Fields. 

Limitations when creating a report

Consider the following limitations when creating a report in the BMC Helix Dashboard by using the data from an external record definition or vendor form:

  • Use only the SELECT query with a simple qualification as shown in the following example:

    Example of the SELECT query
    "sql": "SELECT DISTINCT `com.bmc.dsm.chatbot:Conversation
    Raw Data`.`BotId` AS C1, `com.bmc.dsm.chatbot:Conversation
    Raw Data`.`Channel` AS C2, `com.bmc.dsm.chatbot:Conversation
    Raw Data`.`SessionId` AS C3 FROM `com.bmc.dsm.chatbot:Conversation
    Raw Data` where `GET_QUERY_PARAMETER_fromDate` = '2023-05-01T00:00:00.000'
    AND GET_QUERY_PARAMETER_toDate ='2023-05-31T00:11:00.000' GROUP BY C1 "    ,

    Functions such as case when/then, substring in qualifications do not work.

  • Aggregate functions, unions, join queries, or subqueries do not work.
  • The query returns all the data from the vendor form, irrespective of the number of records.
  • The value you specify in the Max Entries Returned By GetList field on the Server Information form is not honored.

Important

The following operations are not supported for external record definitions: 

  • Record inheritance 
  • Associations 
  • Global transactions across external and local record instances
  • FTS, if the data source type is AR System


Where to go from here

Use the information in the following table to navigate to the topic relevant to your goal:

Description

Task

(Mandatory) Add fields to the record definition according to the organization's requirement.

Modify the details of the existing record fields.

By default, a record definition is visible only to the administrators. To provide access to a record definition for other users, you must add permissions to a specific group or a role.

Limit the use of the record definition within the same application or library, or enable the use of the record definition for all the applications or libraries.

Copy custom fields from a regular record to the same record.