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. Response Cache - This allows you to boost performance by retrieving cached data for specified inputs rather than re-fetching it from external APIs or databases.

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

4. 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.

   • 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 front/backend or on any 3rd party apps via HTTP call.

   • Version: The version of the rule is mentioned in the API body if the environment is in production. If the environment is staging then there will be no version added to the API body.

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.

Well, as we've multi-environment along with multiple versions, it can be confusing for you while working with the API. To minimize your confusion, here is a table clarifying the API behavior based on versions and different environments:

Version	Environment	Body Param View	Explanation
✅	✅	"version":"version_value", "environment":"env_value", (staging/production)	If in your webhook URL, both are written, then simply that specific version of rule will be executed
✅	❌	"version":"version_value", "environment":"production",	While calling the API, in the body, if you've not specified the env but you've specified the version then the by default the production environment will be called of that version.
❌	✅	"version":"latest", "environment":"env_value", (staging/production)	So, if you've not specified the version but the env then the API will call the latest version of the rule of the environment that you've specified i.e. either staging or production.
❌	❌	"version":"latest", "environment":"production",	If you've not specified anything in your API body, then by default the latest live/production version of the rule will be called and executed.

This is how the API body works, so if you're triggering the rule via API, make sure you follow this and call the API accordingly.

Steps to Enable Response Caching:

Response Caching can be enabled for any type of rule—whether it's a SimpleRule, DecisionTable, or Ruleset—when configuring rule triggers. This feature allows you to boost the performance by retrieving cached data for specified inputs rather than re-fetching it from external APIs or databases.

Regardless of the rule type, response caching can be enabled by:

1. Navigating to Settings: Click on the gear (⚙️) icon located on the right-hand side and open the Trigger section.

2. Accessing API Settings: Click the gear (⚙️) icon within the Trigger section to open the API settings widget.

3. Enabling Response Caching: Locate the Response Caching toggle within the API settings and enable it.

   
4. Configuring Caching Parameters: Toggle the response caching on to use it. Then it will show you some additional fields that you need to set:

   • Key Parameters: Select input parameters that will be used to retrieve cached data. This ensures that similar inputs do not trigger new API calls but instead use stored results.

   • Cache Expiry Time: Set the duration (in Days, Hours, or Minutes) for which the cached data remains valid. After this period, data will be refreshed upon the next execution.

   • Clear Cache: Click on the dropdown button to select the environment for which you want to clear the cache. This is to clear cached data for:

     • Staging Environment: Removes all cached data for staging instances.

     • Production Environment: Clears cache for production environments, ensuring fresh data retrieval when necessary.

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.