Domino Adapter tutorial

The tutorial guides you in creating an app in Foundry and connecting the app to your Domino database as an endpoint via the Domino REST API, and testing the methods.

Before you start

• You have completed the Volt MX Go installation.
• You have created your Foundry admin account.

• You have added and configured a schema and a scope in the Domino REST API.

  Tip

  For more information, see Using Admin UI in the Domino REST API documentation.

• Your schema should have a configured form with a dql mode similar to the default mode.

Log in to Volt MX Foundry

1. Open  the Foundry hostname concatenated with /mfconsole/ in your browser.

   Tip

   Use the Console URL in the Install Complete window or from the Installation Complete details that appear in the command line to log in to Volt MX Go Foundry.

   1. Enter your username and password on the Sign in to your account page.
   2. Click Sign In.  

The Volt MX Foundry Console opens with the Apps page shown by default. 

Create an app in Volt MX Foundry

1. On the Apps page, click Add New.
2. A new app is added, and you are directed to the Configure Services → Identity page of the new app.
3. Click the Edit App Name icon to give a unique name to your app.

Tip

For more information, see How to Add Applications in the HCL Volt MX documentation.

Configure an Identity service

1. On the Identity page, click Configure New.
2. Enter a name for the identity service in the Name text box.
3. From the Type of Identity drop-down list, select OAuth2.0.

4. Under Provider Details:

   1. Select Authorization Code in the Grant Type dropdown list.

   2. Enter the Domino REST API server URL concatenated with /oauth/authorization in the Authorize Endpoint field.

      Example: [Domino REST API server URL]/oauth/authorization

   3. Enter the Domino REST API server URL concatenated with /oauth/token in the Token Endpoint field.

      Example: [Domino REST API server URL]/oauth/token

   4. In the Callback URL text box, click Copy.
      You need the callback URL when configuring your app in Domino REST API.

   5. Create and configure an application in Domino REST API.

      Important

      You need to pause the execution of the Configure an Identity Service procedure without saving your initial changes and complete the creation and configuration of an app in Domino REST API before proceeding.

   6. Enter the name of the scope that you have configured in your app in Domino REST API in the Scope text box.

      Important

      Make sure that the name of the scope you enter in the Scope text box matches the name of the scope that you have configured in your app in Domino REST API.

   

5. Under Client Details:

   1. Select Basic authentication as the Client Assertion Type.
   2. Enter the App ID of your app in Domino REST API in the Client ID text box.
   3. Enter the App Secret of your app in Domino REST API in the Client Secret text box.

   Tip

   The App ID and App Secret are generated when you add an app in Domino REST API. For more information, see Using Web UI in the Domino REST API documentation.

6. Under Advanced:

   1. Select Form Param as the Client Authentication Scheme.
   2. Use the default for the rest of the settings.

7. Click Save.

Tip

You can click Test Login to verify if the configured Identity service works. If the configuration works, a Domino REST API login dialog opens where you need to enter your Domino REST API administrator username and password. After successful login, click Allow in the Domino REST API Access consent required dialog. If the configuration doesn't work, an error message is shown.

Add an environment

1. On the left pane on the Volt MX Foundry Console, click Environments.
2. On the Environments page, click Add New. The Add a New Environment dialog opens.

3. In the Environment Name text box, enter an environment name.

   Note

   Your environment name can only contain letters, numbers, and hyphens (-). A hyphen can't appear at the beginning or at the end of a name. A number can't appear at the beginning of a name. A name should be a minimum of three characters and a maximum of 20 characters long.

4. In the Server tab, enter the URL of your Volt MX Foundry in the URL text box. The URL format is: <http or https>://<server_host>:<server_port>

   For example: http://mbaastest30.hcl.net:53504

5. Click Test Connection to verify that the entered URL is correct. If the test is successful, a check mark appears beside the Server tab.

6. Click Save.

   

Configure an Object service

1. On the left pane on the Volt MX Foundry Console, click Apps.
2. On the Apps page, select the app you created.
3. Go to Configure Services → Objects, and then click Configure New.
4. Enter the object service name in the Name text field. For example, EmployeeModelSchema.
5. Select HCL Domino under Business Adapters for the Endpoint Type.

6. Set the Metadata Security Level to Authenticated App Users to restrict the download of object service metadata to users that have successfully authenticated using the Identity Service.

   

7. Under Connection Parameters:

   1. Enter the Domino REST API server URL in the Domino REST API Base URL text field.
   2. Enter a value in the Connection Timeout text field. By default, the value is set to 30 ms.

   Note

   The Connection Timeout is the period for waiting for a new connection to happen before aborting the connection attempt, and is in milliseconds.

   

   Tip

   To test the connection parameters, select the environment you added from the Select an Environment drop-down list and then click Test Connection. You will see a "Connection Successful" message if the configured connection parameters are correct.

8. Under Authentication:

   1. Select the Use Existing Identity Provider radio button.
   2. Select the identity service you configured in the drop-down list.

   Tip

   To test the authentication, click Test Login. If the configuration works, a Domino REST API login dialog opens where you need to enter your Domino REST API administrator username and password. After successful login, click Allow in the Domino REST API Access consent required dialog. A Test Login Successful message is then displayed.

   

9. Click Save and Configure.

Configure a data model

1. On the Data Model tab, click Generate.
2. In the Domino REST API Access consent required dialog, click Allow. The Import Objects from Backend dialog appears.
3. Expand the scope, Forms, and View Entities.

4. Select the checkboxes corresponding to the forms and view entities you want to import.

   

5. Click Next. The Backend Object Name and Data Model Object Name of the selected forms and view entities are shown.

   

   Tip

   • You can change the data model object names of the selected forms and view entities.
   • For more information on naming limitations, see naming limitations.

6. Click Generate. The forms and view entities are now added to the Data Model.

Test the GET method by viewing a record

1. Click the Mapping tab, and then click the expand icon corresponding to a data model name to display a list of available methods.
2. From the list, click GET.
3. Expand the base mapper1, and then select the Test tab.
4. Click Send.
5. All records are displayed on the Response console. Click Save after viewing.

To view a filtered record

1. Expand the base mapper1, and then select the Test tab.

2. Enter a query parameter in the Enter the Query Params text box.

   

3. Click Send.

4. The record is displayed on the Response console.

For more information on supported parameters, see Supported OData filter parameters, form-based GET and Supported OData filter parameters, view-based GET.

Test the POST method by creating a record

1. Click the Mapping tab, and then click the expand icon corresponding to a data model name to display a list of available methods.
2. From the list, click POST.
3. Expand the base mapper1, and then select the Test tab.
4. On the Request Payload, the fields of the data model should be displaying.
5. Beside the fields, input the values, then click Send.

6. The ID of the record is displayed on the Response console after the successful insertion of the record.

   Tip

   Save the ID for updating or deleting the record using PUT or DELETE method, respectively.

Test the PUT method by updating a record

1. Click the Mapping tab, and then click the expand icon corresponding to a data model name to display a list of available methods.
2. From the list, click PUT.
3. Expand the base mapper1, and then select the Test tab.
4. On the Request Payload, the fields of the data model should be displaying.

5. Beside the fields, input the updated values, then click Send.

   Note

   All fields, updated or not, must be specified to maintain the fields in the note after the update.

   

6. The Response console shows the fields with updated values and the number of updated records.

   

Test the DELETE method by deleting a record

1. Click the Mapping tab, and then click the expand icon corresponding to a data model name to display a list of available methods.
2. From the list, click DELETE.
3. Expand the base mapper1, and then select the Test tab.
4. On the Request Payload, the field of the data model should be displaying.

5. Beside the field, input the ID of the record to be deleted, then click Send.

   

6. The Response console shows the number of deleted records.

   

Test the PATCH method by updating a record

1. Click the Mapping tab, and then click the expand icon corresponding to a data model name to display a list of available methods.
2. From the list, click PATCH.
3. Expand the base mapper1, and then select the Test tab.
4. On the Request Payload, the fields of the data model should be displaying.

5. Beside the fields, input the updated values, then click Send.

   

6. The Response console shows the fields with updated values and the number of updated records.

   

Additional procedure

Create and configure an application in Domino REST API

1. Log in to Domino REST API.

   Tip

   For more details, see Access Domino REST API.

2. Select Application Management - OAuth from the home page.

3. On the Application Management page, click Add Application.
4. Under Add New Application, fill in the form:
   1. Enter an Application Name.
   2. Provide a Description.
   3. Paste the callback URL that you have copied when configuring the Identity Service in Foundry in the Callback URLs text box.
   4. Provide the application startup page URL under Startup Page.
   5. Select and add a scope in the Scope field.
5. Click Add.
6. Hover over the application tile and click Generate Application Secret. Take note of the App secret and the App ID.

Note

Make sure to take note of the App ID and App secret as you need these details in configuring the Identity Service in Foundry.

---

Last update: November 20, 2023