This documentation supports the 23.3 version of BMC Helix Innovation Suite (AR System and BMC Helix Innovation Studio).

To view an earlier version, select the version from the Product version menu.

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.

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. 
  4. In the Create new external record dialog box, complete the fields as described in the following table:

    TabFieldAction
    Data sourceData 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 selectionTable

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

    Record ID fieldsRecord 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 selectionAvailable 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:



  5. 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:

    TabFieldAction
    Data sourceData source typeFrom the list, select Web API.
    Data source nameFrom 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 selectionWeb APISelect the Web API that you have configured.
    Document selectionDocumentsSelect the document that you have created for the Web API.
    Field selectionAvailable 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 . These fields are displayed in the Selected fields section.

    The following image shows the Field selection tab:


    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 selectionOperationTo get the data from the external record definition via web API, select GET.
    Web API request nameSelect 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.

Add fields

Modify the details of the existing record fields.

Update the existing 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.

Add permissions

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.

Define a scope

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

Copy fields

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

Comments