Skip to content

User Guide: Integration > Configure the Integration Service > HCL AION Adapter

HCL AION Adapter

HCL AION (formerly OpenAPI Specification) is a framework that defines interfaces. It helps you design, build, document, and consume REST APIs.

To configure an HCL AION service in Volt Foundry, provide a JSON or YAML file (and any dependent files) that includes the API specifications. Volt Foundry imports the files, reads the metadata, and displays the APIs.

Starting with V10 Servicepack 2, Volt Foundry supports HCL AION.
For more information about HCL AION, see A Guide to What’s New in HCL AION.

Configuring an HCL AION End-point Adapter

To configure an HCL AION adapter in Integration Service Definition tab, follow these steps:

  1. On the Integration Service Definition page, from the Service Type list, select HCL AION.

  2. Configure the service definition parameters. For more information, refer to the following sections.

    ParameterDescription
    NameSpecifies the name that Foundry uses to identify the service on the console.
    VersionSpecifies the version number of the service. The version number ranges from 1.0 to 999.99. If you are creating a new service, the version number is 1.0 by default, and it cannot be changed.
    DescriptionSpecifies the description of the service that is displayed on the console.

    Connection Parameters
    ParameterDescription
    HCL AIONSpecifies the JSON, or YAML file that contains the required API specifications. You can also upload a zip file that contains the JSON or YAML file. To upload an HCL AION specification file, click Upload, and then select a file from your local system. After you upload a file, Foundry displays additional parameters based on the HCL AION spec version that is mentioned in the file.
    Note: Volt Foundry V10FP2 GA supports uploading of HCL AION spec 3.0 versions. To upload an HCL AION specification file, click Upload, and then select a file from your local system. After you upload a file, Foundry displays additional parameters based on the HCL AION spec version that is mentioned in the file.

    Connection Parameters for HCL AION

    ParameterDescription
    Server URLSpecifies the URL of the server that hosts the APIs. The default URL is the first server URL in the specification file. For information about how Foundry parses the URLs, refer to the Miscellaneous section. For example: https://subdomain.site.com/version
    Server DescriptionSpecifies the description for the server that is specified by the URL. For example: Development Server

    Authentication
    ParameterDescription
    Use Existing Identity ProviderSpecifies the identity provider that you want to use to authenticate users for the service. You can select any Identity Service that is created on the VoltMX Foundry cloud. For information about creating an Identity Service, refer to Configure Identity Service.

    Advanced

    Field Description
    Custom code Specifies any custom JAR files that you want to associate with the service. To associate a JAR file with the service, follow either of the following steps. From the Select Existing JAR list, select a JAR file from the Volt Foundry cloudClick Upload New, and then select a JAR file from the file explorer> Note: For on-premises instances of Foundry, make sure that the JAR file that is built on the same JDK version that is used to install the Foundry Integration.
    API Throttling Specifies whether Foundry must limit the number of request calls in a minute. To use API Throttling, follow these steps.

    In the Total Rate Limit box, type a required value. This limits the total number of requests that are processed by the service.

    In the Rate Limit Per IP box, type a required value. This limits the number of requests based on the IP Address of the request.

    You can also override throttling from the Volt Foundry App Services Console. For more information, refer to Override API Throttling Configuration.

  3. After you configure all the parameters, click SAVE.

    Note: If you want to add operations to the service, click SAVE AND ADD OPERATIONS.

Creating Operations for HCL AION

After you create a service, you can view existing operations and create new ones on the Operations List tab. For an HCL AION endpoint, the operations correspond to the paths defined in the specification file (for example, POST AI Agent model or PUT AI Agent model).

To create an operation, follow these steps:

  1. On the Service Definition page, open the Operations List tab.
    Alternatively, click the + icon in the left pane, and then select Add New Operation.

  2. On the Operations List tab, select the operations you want to add from the drop-down list.
    When you select a path (operation), Volt Foundry automatically populates all the fields associated with that operation.

  3. After you select the operations, click ADD OPERATION. Volt Foundry adds the selected operations to the Operations List tab.

  4. Under Configured Operations, click an operation to view its details.

    Volt Foundry displays the selected operation in edit mode. You can configure the parameters to update the operation. For more information, see the following table.

    Field Description
    Name Specifies the name that Foundry uses to identify the operation on the console.
    Operation Security Level Specifies the authentication that is required to invoke the operation. Contains the following options: Authenticated App User – It restricts the access to clients who have successfully authenticated using an Identity Service associated with the app. Anonymous App User – It allows the access from trusted clients that have the required App Key and App Secret. Authentication through an Identity Service is not required. Public – It allows any client to invoke this operation without any authentication. This setting does not provide any security to invoke this operation and you should avoid this authentication type if possible. Private - It blocks the access to this operation from any external client. It allows invocation either from an Orchestration/Object Service, or from the custom code in the same run-time environment.
    Description Specifies the description of the service that is displayed on the console.

  5. Configure the parameters in the Advanced section as required. For more information, see the following table.

    Advanced
    Custom Code InvocationYou can add pre and post processing logic to services to modify the request inputs. When you test, the services details of various stages in the service execution are presented to you for better debugging. All options in the Advanced section are optional. For more details, refer to Preprocessor and Postprocessor.
    Additional Configuration PropertiesAdditional Configuration Properties allows you to configure service call time out cache response. For information on different types of configuration properties, refer Properties.
    Front-end APIFront-end API allows you map your endpoint (or) backend URL of an operation to a front-end URL. For detailed information, refer Custom Front-end URL.
    Server EventsUsing Server Events you can configure this service to trigger or process server side events. For detailed information, refer Server Events.

  6. After you configure the required parameters, click SAVE.

Configuring Request Parameters

Volt Foundry picks the request input parameters from the uploaded HCL AION specification file. Any changes you make to the parameters from the console are ignored.

Important: Ensure that the input parameters are form-url-encoded.

To create a new parameter on the Request Input tab, follow these steps:

  1. On the Body tab, click Add Parameter.
    Volt Foundry adds a new row to the parameters table.

  2. Configure the fields (columns) for the input parameter. For more information, see the following table.

    Field Description
    Name Specifies a unique identifier for the parameter. The name is the key of the parameter in the request.
    VALUE Specifies the source of the value of the parameter. Contains the following options. request The value is picked from the configuration of the request parameter. If you select request as the source, you need to configure the TEST VALUE and DEFAULT VALUE fields. session The value is picked from the session context. If you select session as the source, the TEST VALUE and DEFAULT VALUE fields are disabled. constant The value is a constant that is defined on the Foundry console. If you select constant as the source, you need to type a value for the parameter. identity The value is picked from the response that is sent by the specified identity provider. If you select identity as the source, you need to configure the provider, attribute, and value. For example: sampleAuth.profile.userID
    Note: For more information on Externalizing Identity Services, refer to Replace the Identity Service references in a Foundry app.
    TEST VALUE Specifies the value of the parameter that is used while testing the service.
    DEFAULT VALUE Specifies the value of the parameter that is used if the test value is empty.
    DATA TYPE Specifies the data type of the parameter. Contains the following options: string A combination of alpha-numeric and special characters. Supports all formats (including UTF-8 and UTF-16) with no maximum size limit. boolean A value that can be true or false. number An integer or a floating point number. date A value that contains the day, month, year, and time. collection A set of multiple records. record A set of multiple objects. > Note: The binary data type is not supported for operations in HCL AION.
    Record ID Specifies the ID of the record that contains the parameter. This field is applicable for nested payloads.
    Collection ID Specifies the ID of the collection that contains the parameter. This field is applicable for nested payloads.
    Description Specifies the description for the request parameter.

  3. After you configure all the parameters, validate the details by testing the service operation. For more information, see the Test a Service Operation.

Configuring Response Parameters

You can view the details such as the name, scope, and data type of the response parameters using the Response Output tab.

The Restrict Parameters to HCL AION definition check box is selected by default. This option determines whether Volt Foundry picks parameters from the HCL AION definition file or from the Foundry console configuration.

To create a parameter based on the back-end response, follow the below steps:

  1. Clear the Restrict Parameters to HCL AION definition check box.

  2. From the Select Environment list, select a run-time environment, and then click Save and Fetch Response.
    Volt Foundry displays the back-end response in the Test window, and the Backend Response pane shows the response nodes in a tree view.

  3. Hover over to the node that you want to add to the response output parameters, and then click Create Response.

    Volt Foundry adds a new row to the Response Output tab with the details of the selected node.

To create a parameter manually, follow these steps:

  1. Clear the Restrict Parameters to HCL AION definition check box.

  2. Click Add Parameter. Volt Foundry adds a new row to the parameters table.

  3. Configure the fields for the parameters. For more information, see the following table.

    Field Description
    Name Specifies a unique identifier for the parameter. The name is the key of the parameter in the response.
    Scope Specifies the scope at which the parameter is available. Contains the following options. response The parameter is available in the response. session The parameter is available throughout the user session. > Note: If the parameters inside a record are defined as the session, the session scope is not reflected for the parameters.
    DATA TYPE Specifies the data type of the parameter. Contains the following options: string A combination of alpha-numeric and special characters. Supports all formats (including UTF-8 and UTF-16) with no maximum size limit. boolean A value that can be true or false. number An integer or a floating point number. date A value that contains the day, month, year, and time.collection A set of multiple records. record A set of multiple objects. > Note: The binary data type is not supported for operations in HCL AION.
    Record ID Specifies the ID of the record that contains the parameter. This field is applicable for nested payloads.
    Collection ID Specifies the ID of the collection that contains the parameter. This field is applicable for nested payloads.
    Description Specifies the description for the request parameter.

  4. After you configure all parameters, click SAVE OPERATION.

    Note: To test the operation, select a run-time environment from the drop-down list, and then click SAVE AND FETCH RESPONSE.

Note: You can view the service in the Data Panel in Volt Iris. The Data Panel lets you link back-end data services to your application UI elements with low-code to no code development. For more information about the Data Panel, see here.

Testing the Operation

After you create an operation and configure the request and response parameters, you can test the operation to validate the configuration.

To test an operation, select an environment from the Select Environment list, and then click SAVE AND FETCH RESPONSE. Volt Foundry displays the result of the operation.

For more information, see Test a Service Operation.

Note: For POST or PUT methods that contain nested payloads, you cannot test the service from the Volt Foundry Console. You must send the request from the App Services Console or from Postman.

Miscellaneous

HCL AION in Foundry V10 Servicepack 2

  • With the HCL AION Specification, you can add multiple URLs to your definition and also include parameters in the URL. For more information, refer to A Visual Guide to What's New in HCL AION.
    • While creating a service for HCL AION in Volt Foundry V10 Servicepack 2, you can select only one URL as the Server URL. If your specification file contains multiple URLs, Foundry picks the first URL by default.
    • You can change the URL before you publish the service to the run time by re-configuring the service before a publish. For more information, refer to Service Reconfiguration.
    • Parameters in the URL are not supported. Make sure that you add static server URLs to your specification file.
  • Extension data is not supported as Foundry parses only one specification file. If your specification file contains references to any external files, the console displays an error.
    For example, if your file contains the following code snippet, the console displays an error: 
{
    "$ref": "PayInOutExtension.json#/components/schemas/customFields"
    }
  • The trace HTTP method is not supported and the APIs that use the trace method are ignored.
    APIs that use other HTTP methods are parsed by Foundry to create operations.
  • If the HTTP response code is not 200, the console displays the response from the back-end server as is.
  • OpenID Connect (OIDC) is not supported for authentication.
  • Callbacks, which are used to define Webhooks, are not supported. Links, which are used to define the output one operation as input for another operation, are not supported. Make sure that you remove Callbacks and Links from your HCL AION spec before you upload it to Foundry.
  • Serialization of parameters, which includes style (defines the delimiter for multiple parameters) and explode (specifies whether objects of an array are generated as separate parameters), is not supported.
  • Foundry does not parse or validate examples from the specification file.
  • Foundry HCL AION adapter does not support the BinarySchema, ByteArraySchema, FileSchema and MapSchema.