Skip to main content
Skip table of contents

Custom Connection Parameters

LAST UPDATED: JUNE 25, 2025

Custom integrations, like built-in integrations, typically rely on a defined set of custom connection parameters to establish connectivity with the D3 platform. These parameters may include server URL, access token, API version, username, password, client secret, or others, depending on the specific requirements of the integration.

Custom Connection Parameter Interface

Configuring custom connection parameters modifies the connection setup modal to include input fields, where users can enter values for the defined parameters.

Frame 1-20250623-183409.png

FORMATTING REQUIREMENT

Use only lowercase letters in the Parameter Name field.

Connection Setup Modal

Before Creating Custom Connection Parameters

Frame 2 (2)-20250623-222844.png

After Creating One of Each Type of Custom Connection Parameter

87e0666c-9ad4-47fc-8b99-ad21fb66a95f.png

READER NOTE

The Connection Health Check checkbox is included by default.

Using Custom Connection Parameters

Example - Using Custom Connection Parameters

OBJECTIVE – Learn to use custom connection parameters in a custom Python script.


  1. Create and save one of each type of custom connection parameter.

    Frame 7-20250624-001348.png
  2. Create a custom Python command.

    Frame 10-20250624-012843.png
  3. Navigate to the Test tab, click on the button, input custom values for the custom connect parameters configured in step 1, then click on the button.

    Frame 8 (2)-20250624-003328.png
  4. Input the following code into the editor, then click on the button.

    PY
    def TestConnection():
      
        connector = runtime["connector"]
    
        custom_param_stp = connector.get("short_text_param")
        custom_param_ltp = connector.get("long_text_param")
        custom_param_cp  = connector.get("checkbox_param")
        custom_param_dp  = connector.get("dropdown_param")
        custom_param_dtp = connector.get("date_time_param")
        custom_param_np  = connector.get("number_param")
    
        pb.log(f"Custom Param 1: {custom_param_stp}")
        pb.log(f"Custom Param 2: {custom_param_ltp}")
        pb.log(f"Custom Param 3: {custom_param_cp}")
        pb.log(f"Custom Param 4: {custom_param_dp}")
        pb.log(f"Custom Param 5: {custom_param_dtp}")
        pb.log(f"Custom Param 6: {custom_param_np}")
    
        rawData     = "placeholder_value"
        resultData  = "placeholder_value"
        returnData  = "placeholder_value"
        keyFields   = "placeholder_value"
        contextData = "placeholder_value"
        error       = "placeholder_value"
    
        return pb.returnOutputModel(
            resultData,
            returnData,
            keyFields,
            contextData,
            rawData,
            error
        )

    CODE BREAKDOWN

    • Lines 3: The connector variable provides access to the parameters configured in step 1.

    • Lines 5-10: Retrieve user-entered values from step 3, using get(<parameter name>).

    • Lines 12-17: Log the retrieved values to the Test Result > Custom Log tab (step 5).

    • Lines 19-33: Placeholder output values used to ensure that the Custom Log tab renders in the test result popover (step 5).

    Frame 5 (5)-20250623-235123.png

    Ensure that the function name exactly matches the internal command name displayed in the Overview > Settings tab, directly beneath the command display name.

    Frame 9-20250624-012229.png
  5. Click on the Custom Log tab to observe the values.

    Frame 6-20250623-235516.png

Establishing Connections

Establishing connections for custom integrations involves configuring the vendor-side environment, identifying appropriate endpoints for connectivity validation, and setting up the D3 platform with corresponding connection parameters that support those endpoints.

The example below demonstrates a simplified process of establishing connectivity, using minimal vendor-side setup and widely used connection parameters.

Example - Mistral AI (Server URL, API Version, API Key)

OBJECTIVE – Establish connectivity for a custom Mistral AI integration using custom connection parameters.


  1. Log in to https://console.mistral.ai/home.

  2. Click on the API Keys item within the left sidebar.

    Frame 11-20250624-174626.png
  3. Click the Choose a plan button. Skip to step 8 if you see a Create new key button.

    Frame 12-20250624-174804.png
  4. Click on the Experiment for free button.

    Frame 13-20250624-174900.png
  5. Tick the checkbox, then click on the Subscribe button.

    Frame 14 (1)-20250624-175128.png
  6. Verify you phone number.

    Frame 15 (1)-20250624-181859.png
    Frame 36-20250624-223339.png
  7. Click on the Go to La Plateforme button.

    Frame 17 (1)-20250624-181927.png
  8. Navigate back to the API Keys page, then click on the Create new key button.

    Frame 18 (3)-20250624-181938.png
  9. Enter a key name, then click on the Create new key button.

    Frame 19 (1)-20250624-181949.png
  10. Store the API key securely.

    Frame 20 (1)-20250624-181959.png
  11. Visit https://docs.mistral.ai/api/#tag/models, then locate the GET /v1/models endpoint under the List Models section.

    Frame 22 (3)-20250624-183323.png

    GET

    TEXT
    https://api.mistral.ai/v1/models

READER NOTE *

The GET /v1/models endpoint is well suited for connection validation because it:

  • Confirms functional connection via key-authorized access and valid response data

  • Simplifies usage by requiring no input parameters

  • Performs a safe, a non-destructive, read-only operation

  1. Set up a Custom Integration - Mistral AI integration on D3 vSOC.

    Frame 21 (1)-20250624-182334.png
  2. Add the following custom connection parameters:

    • server_url (display name: Server URL)

    • api_version (display name: API Version)

    • api_key (display name: API Key)

      Frame 23 (3)-20250624-183947.png
      Frame 24 (2)-20250624-191846.png
  3. Set up a connection using the:

  4. Add a custom command.

    Frame 28-20250624-195205.png
  5. Select the connection created in step 14, enter the following code into the editor, then test the command.

    PY
    import traceback
    
    def TestConnection():
        
        TIMEOUT_SECONDS         = 30
        MIN_KEY_DISPLAY_LENGTH  = 8
        MASK                    = "*****"
        MODELS_ENDPOINT         = "models"
        HTTP_OK                 = 200
        STATUS_SUCCESS          = "Successful"
        STATUS_FAILED           = "Failed"
        KEY_FLANK               = 4
    
        connector = runtime["connector"]
    
        server_url  = connector.get("server_url", "").strip().rstrip("/")
        api_version = connector.get("api_version", "").strip().strip("/")
        api_key     = connector.get("api_key", "").strip()
    
        pb.log(f"Server URL: {server_url}")
        pb.log(f"API Version: {api_version}")
        pb.log(f"API Key: {api_key[:KEY_FLANK]}{MASK}{api_key[-KEY_FLANK:]}")
    
        rawData     = ""
        resultData  = ""
        returnData  = STATUS_FAILED
        keyFields   = ""
        contextData = ""
        error       = ""
    
        try:
            url = f"{server_url}/{api_version}/{MODELS_ENDPOINT}"
            pb.log(f"Request URL: {url}")
            headers = {
                "Authorization": f"Bearer {api_key}"
            }
    
            response = requests.get(url, headers=headers, timeout=TIMEOUT_SECONDS)
    
            if response.status_code == HTTP_OK:
                rawData    = response.json()
                resultData = {"Models Count": len(rawData.get("data", []))}
                returnData = STATUS_SUCCESS
            else:
                error = f"{response.status_code} {response.reason}: {response.text}"
    
        except requests.exceptions.RequestException as ex:
            error = str(ex)
            pb.log(f"Exception Traceback: {traceback.format_exc()}")
    
        return pb.returnOutputModel(
            resultData,
            returnData,
            keyFields,
            contextData,
            rawData,
            error
        )

    CODE BREAKDOWN

    • Line 14: The connector variable provides access to the parameters configured in step 13.

    • Lines 16-22: Extracts, sanitizes, and logs all connection parameter values to the Test Result > Custom Log tab (step 17).

    • Lines 24-29: Initializes required variables for command output model.

    • Lines 32-33: Constructs and logs the full API endpoint URL used in the HTTPS GET request.

    • Lines 34-36: Prepares the HTTP headers required for API authorization.

      d7a4cff0-ff9b-4d6f-9bc6-b66b64d29703.png
    • Line 38: Sends an HTTP GET request to the constructed Mistral API URL using defined headers and timeout.

    • Lines 40-45: Processes the response from the Mistral API.

      • On success (HTTP 200), parses and counts models returned in the "data" field.

        Frame 33-20250624-213832.png
      • On failure, captures and formats the error message.

    • Lines 47-49: Logs any exceptions raised during the HTTP request.

    • Lines 51-58: Returns the results of the test connection using D3's standardized output format. The output is displayed in the Test Result popover for review.

      Frame 37-20250624-224728.png
  6. Review output tabs in the Test Result popover to verify the connection.

    Frame 32-20250624-212916.png

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.