Trigger Rule via API

Nected enables you to securely trigger a rule from your systems via API for which you can choose to have private authentication using an authentication key.

Note: All production rules must be run securely using an API, but you can choose to run a staging rule either using an API or directly on the Nected platform.

Follow this procedure to trigger a rule using an API:

1. Test and publish the rule you want to trigger.

2. Go to the Trigger section of the rule, update the rule trigger settings as needed, and click three dots next to the API base URL. The API Settings window appears.

   
3. Use the information on the API settings window to trigger the API using an API platform of your choice, for example Postman.

The following list describes the options on the API settings window:

1. Authentication – The authentication method for the API. You can either select None (no authentication required) or Private (use an authentication key to trigger the API).

2. Base URL – The base URL for the rule.

3. Body Params – Body parameters that you can use to run the API.

   • environment: The default environment is production. You can set up different values based on which Rule you want to test in which environment.

     • Testing an Unpublished/Draft Rule in Staging: If you wish to test an unpublished or draft rule in the staging environment, you can use the API for testing purposes. To do this, set environment: Staging in the Body Parameters. This allows you to evaluate the rule's behavior and functionality before publishing it.

     • Running a Published Rule in Production: When you are ready to execute a rule in a live, real-time production environment, you need to trigger the API with environment: production. This action will activate the rule for real-time decision-making. If you don't pass any environment, it will automatically pick up the production instance.

     • Running a Published Rule in Staging: If you want to run a published rule in the Staging environment, you can do so by using the API with environment: Staging and isPublished: True. This enables you to simulate the rule's behavior without impacting your production processes.

4. params: This would be as defined in "Add Source" to be passed along to API. You can copy this from the API Settings page and integrate it on your frontend/backend or on any 3rd party apps via HTTP call.

5. Close the API Settings window. If you did not update the rule, then you do not need to test or publish the rule again.

The default environment is production.

By following these steps and utilizing Nected's API, you can seamlessly integrate your rules with your chosen database, allowing you to make data-driven decisions effortlessly.

Processing Multi Input Attributes in API

The Nected API supports both single as well as list of input attributes, enabling flexible and efficient rule execution for single set of input attributes or list.

This helps to process your rules / flows if you need your rules to run for different set of input attributes and perhaps wants to process all in parallel and as quickly as possible. This feature is designed to accommodate scenarios where multiple data points need to be evaluated or actions triggered simultaneously, ensuring efficient, parallel processing of inputs. The inclusion of bulk parameters within the API's capabilities enables a more robust and flexible integration, facilitating complex operations without the need for multiple, individual API calls.

For developers utilizing the Nected API to automate and enhance their workflows, the capability to process bulk input parameters offers a streamlined approach to rule execution. Using this feature, you wouldn't have to call same API in loop or multiple times, thus avoiding any network latency as well as need of merging the outcome of all API calls in one.

Single Input Parameters

For operations involving a single data point, the API expects a payload structured with a params key. This approach is ideal for straightforward, singular operations.

Example Payload for Single Input:

{
  "environment": "staging",
  "params": {
    "customer_location": "Domestic",
    "product_name": "Tshirt"
  }
}

Response Structure for Single Input: The response for a single input parameter execution returns detailed information about the execution status, including the rule ID, execution time, and the output data specific to the input parameters provided.

{
  "code": "success",
  "message": "Success",
  "data": {
    "action": {},
    "additionalOutput": {},
    "executionId": "rule:7:6598f6c324c168c75b5f6397:1704531268965849",
    "executionTime": "119ms",
    "output": [{"discount_perc": 10, "product_name": "Tshirt"}],
    "ruleId": "6598f6c324c168c75b5f6397"
  }
}

Bulk Input Parameters

To enhance efficiency, the API supports the execution of rules with bulk input parameters. This functionality allows the API to process multiple sets of parameters in parallel, though the response is unified and returned at once.

Example Payload for Bulk Input:

{
  "environment": "staging",
  "bulkParams": [
    {"customer_location": "Domestic", "product_name": "Tshirt"},
    {"customer_location": "Domestic", "product_name": "Kurta"},
    {"customer_location": "International", "product_name": "Tshirt"}
  ]
}

Response Structure for Bulk Input: The API returns a consolidated response that includes the outcomes of all the input sets processed in parallel. This bulkOutput array within the response contains individual results, detailing success, errors, and output for each set of parameters.

{
  "code": "success",
  "message": "Success",
  "data": {
    "bulkOutput": [
      {"Action": {}, "Error": null, "Output": [{"discount_perc": 10, "product_name": "Tshirt"}]},
      {"Action": {}, "Error": null, "Output": [{"discount_perc": 20, "product_name": "Kurta"}]},
      {"Action": {}, "Error": null, "Output": [{"discount_perc": 15, "product_name": "Tshirt"}]}
    ],
    "executionId": "rule:7:6598f6c324c168c75b5f6397:1704531450368444",
    "executionTime": "105ms",
    "ruleId": "6598f6c324c168c75b5f6397"
  }
}

Adding Bulk Input Parameters in Nected API Calls

To integrate bulk input parameters when triggering rules via the Nected API, copy the body parameters template from the API settings window, which you cannot edit directly. In your project's API call, replace the single input parameters with an array of parameter objects to represent bulk input, following the structure provided in the documentation. This approach allows you to efficiently execute multiple sets of parameters in a single API request, leveraging the API's capability to process these parameters in parallel for streamlined operations.

1. Access API Settings: Navigate to the Nected API settings window and locate the Body Params section. This area displays a JSON template for the body parameters required by the API.

2. Copy Body Parameters Template: Although you cannot edit the JSON directly in the API settings window, you can copy the template provided. This template serves as the foundation for your API request.

   
3. Modify Template for Bulk Input: In your project, when preparing to call the Nected API, replace the single input parameters template with your bulk input parameters. Use an array of objects, each object representing a set of parameters for one execution.

4. Structure Bulk Parameters: Follow the provided JSON structure for bulk parameters, encapsulating your data within a bulkParams array. Like below:

   Replace a single parameter set:

   {
     "params": {"customer_location": "Domestic", "product_name": "Tshirt"}
   }
   

   With bulk parameters:

   {
     "bulkParams": [
       {"customer_location": "Domestic", "product_name": "Tshirt"},
       {"customer_location": "Domestic", "product_name": "Kurta"},
       {"customer_location": "International", "product_name": "Tshirt"}
     ]
   }

5. Execute API Call: With your modified payload including bulk parameters, execute the HTTP request to the Nected API. Ensure your request method (GET, POST, etc.) and headers are correctly configured.

6. Handle the Response: The API will process each set of parameters in parallel and return a single, unified response containing the results of all executions.

Example Implementation:

To add bulk input parameters in your project when calling the Nected API, you need to adjust the body of your HTTP request. Here's a sample code snippet for a POST request using JavaScript's Fetch API:

fetch('<https://nected-59.nected.io/nected/rule/65a8d7f75e13XXXXXXXXXXXX>', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({
    "environment": "staging",
    "bulkParams": [
      {"customer_location": "Domestic", "product_name": "Tshirt"},
      {"customer_location": "Domestic", "product_name": "Kurta"},
      {"customer_location": "International", "product_name": "Tshirt"}
    ]
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch((error) => console.error('Error:', error));

This example demonstrates how to structure your request with bulk parameters, replacing the single parameter set with an array of objects under bulkParams. Each object represents a unique set of input parameters for the rule to process.

Guidelines for Implementation

• Ensure Accurate Payload Structure: Properly structuring your payload is crucial, whether for single or bulk operations, to align with the API's processing logic.

• Parallel Processing Awareness: When using bulk parameters, understand that the API processes these in parallel, enhancing efficiency but also necessitating careful consideration of the potential impact on system resources.

• Comprehensive Error Handling: Given the unified response for bulk operations, implementing detailed error handling mechanisms is essential to address any issues within individual parameter sets effectively.

By adhering to these detailed guidelines and examples for single and bulk input parameters, developers can leverage the Nected API's capabilities to optimize data processing and rule execution within their applications, ensuring both efficiency and accuracy.