Resource Directory
Within the Boltic Integration boilerplate, the resources directory contains JSON schemas for specific resources related to your integration. Each schema is designed to define the parameters and operations associated with that specific resource. This organization ensures that each resource comes with its own configurable parameters and operational logic.
These schemas represent the fundamental data types that your integration will interact with. By leveraging the Resource parameter, targeted operations can be performed within an activity, optimizing the handling of different data types. Each file contained in the resources folder outlines the behavior of a particular resource, including its structure, required fields, validation rules, and interaction patterns with external systems.
The Resource parameter plays a crucial role in facilitating targeted operations within various activities, enabling the effective manipulation of specific data types.
Components Resource Directory
The resources/ directory can contain several files, each representing a distinct resource type (e.g., Contact, Deal, Account). These files define the schema and behavior for how each resource interacts with the external service.
Each resource file typically includes the following components:
Parameters
Each resource schema includes an array of parameters that define the inputs required for the operations associated with that resource. This array defines the input parameters for a specific operation within the integration. Boltic supports multiple input components, which can be found in the Components section.
Example Code
The following is a sample code snippet to show how Parameters can be implemented in Resources.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
"parameters": [
{
"name": "operation",
"meta": {
"displayName": "Operation",
"displayType": "select",
"placeholder": "Select an operation",
"description": "Select the operation you want to perform.",
"options": [
{
"label": "Add User",
"value": "users.usersCreate"
},
{
"label": "Update User",
"value": "users.usersUpdate"
},
{
"label": "Delete User",
"value": "users.usersDelete"
},
{
"label": "Get User",
"value": "users.usersGet"
},
{
"label": "Get All User",
"value": "users.usersList"
}
],
"validation": {
"required": true
},
"dependencies": {
"conditions": [
{
"field": "resource",
"operator": "EQUALS",
"value": "users"
}
]
}
}
}
],
Expected Output (Dashboard View)
Once the above integration is configured and triggered, here’s how the feature will appear on the dashboard:
Operations
Each operation defines specific actions that can be performed on resources, such as creating/deleting an account or creating a contact. Understanding these operations helps to implement the correct functionality in your integration. The schema outlines the various operations that can be performed on the resource, such as creating, updating, and deleting it. Each operation includes its own set of parameters and configurations.
Example Code
The following is a sample code snippet to show how to define the Create Account resource structure in a Freshsales integration.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
{
"create": {
"definition": {
"method": "post",
"url": "{{secrets.api_url}}/api/sales_accounts",
"headers": {
"Authorization": "Token token={{secrets.api_key}}"
},
"qs": {},
"body": "{{parameters}}",
"response": {
"output": "{{response.data}}",
"error": {
"message": "{{response.data.errors.message}}",
"code": "{{response.data.errors.code}}"
}
}
},
"parameters": [
{
"name": "view",
"meta": {
"displayName": "View ID",
"displayType": "select",
"placeholder": "Enter the view ID",
"description": "Enter the view ID to filter the list of accounts.",
"validation": {
"required": true
},
"options": [],
"value": "",
"config": {
"urlType": "options",
"method": "post",
"url": "integrations/options",
"body": {
"name": "freshsales",
"resource": "account",
"operation": "account.list",
"secret": "{{parameters.secret}}",
"loadOptionsMethod": "getAccountViews"
},
"labelKey": "name",
"valueKey": "id"
},
"dependencies": {
"conditions": [
{
"field": "secret",
"operator": "NOT_EMPTY"
},
{
"field": "resource",
"operator": "EQUALS",
"value": "account"
},
{
"field": "operation",
"operator": "EQUALS",
"value": "account.list"
}
]
}
}
}
],
"output": {
"schema": [
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
],
"samples": [] // or {}
},
"config": {
"urlType": "parameters",
"method": "post",
"url": "integrations/parameters",
"body": {
"name": "freshsales",
"resource": "account",
"secret": "{{parameters.secret}}",
"loadParametersMethod": "getMoreParameters"
}
}
},
...
}
Each operation within a resource schema is structured to define how the operation functions. The structure consists of four main components:
Definition
The Definition (definition) schema is used to make an API call when an activity run from the workflow UI. This includes:
| Keys | Description |
|---|---|
| method | The HTTP method to be used (e.g., get, post, put, or delete). |
| url | The endpoint to which the request is sent, often including placeholders for dynamic data. |
| headers | Any required headers for the request, such as authorization tokens or content type. |
| qs (Query Strings) | Any query parameters that need to be sent with the request. |
| body | The structure of the data sent in the request body uses placeholders for dynamic values derived from user input. |
| response | The expected structure of the response, including how to extract output and handle errors. |
-
To control which values are included or excluded from your payload during processing using request payload filters, refer to Filters in Definition for detailed implementation and examples.
-
To dynamically manipulate or customize your request URLs, headers, query parameters, request bodies, or responses using JavaScript-based transformations, refer to Transform in Definition.
-
To dynamically render integration parameters through API calls, allowing definitions to adapt based on changing conditions or external data, refer to Rendering Dynamic Parameters for detailed implementation and examples.
-
To efficiently handle large datasets using Boltic’s built-in pagination methods like Page, Offset, Cursor, URL, Body, and Header-based pagination, refer to the Pagination in Definition documentation for implementation details and examples.
Example Code
The following is a sample code snippet to show how Definition schema can be implemented in Operation.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
"definition": {
"method": "put",
"url": "https://integrations.boltic/v1/conversations/conversations/{{parameters.id}}",
"headers": {
"Accept": "application/json",
"x-integration-id": "{{secrets.integration_id}}",
"x-integration-token": "{{secrets.integration_token}}",
"Content-Type": "application/json"
},
"qs": "{{parameters.query_params}}",
"body": {
"title": "{{parameters.title}}",
"meta": "{{parameters.meta}}"
},
"response": {
"output": "{{response.data}}",
"error": {
"message": "{{response.data.message}}",
"code": "{{response.status}}"
}
}
},
Operation's Parameters
The Parameters (parameters) section defines the inputs required for the operation. For possible input types, refer Components.
Example Code
The following is a sample code snippet to show how Parameters schema can be implemented in Operation.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
"parameters": [
{
"name": "hostId",
"meta": {
"displayName": "Host ID",
"displayType": "text",
"description": "External ID of the user",
"validation": {}
}
},
{
"name": "name",
"meta": {
"displayName": "Name",
"displayType": "text",
"description": "Name of the user",
"validation": {}
}
},
{
"name": "email",
"meta": {
"displayName": "Email",
"displayType": "text",
"description": "email of the user",
"validation": {}
}
},
{
"name": "phone",
"meta": {
"displayName": "Phone",
"displayType": "text",
"description": "Phone number of the user",
"validation": {}
}
},
{
"name": "profilePicUrl",
"meta": {
"displayName": "Profile Pic URL",
"displayType": "text",
"description": "Profile pic of the user",
"validation": {}
}
},
]
Example Output (Dashboard View)
Once the above integration is configured and triggered, here’s how the feature will appear on the dashboard:
Output
The Output (output) section defines the expected results from the operation, including:
| Key | Description |
|---|---|
| schema | The structure of the data that will be returned in the response, helping to validate and parse the output. |
| samples | Example responses to illustrate the expected output, which can assist developers in understanding how to work with the returned data. |
Example Code
The following is a sample code snippet to show how Output schema can be implemented in Operation.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
"output": {
"schema": [],
"samples": []
}
Config
The Config (config) section is used to fetch extra data from third-party APIs. For example, in Freshsales, when the user selects the create account option from the dropdown, input fields required to create an account need to be shown, and for that, the Freshsales API is called to get all required fields. This consists of several fields explained below:
| Key | Description |
|---|---|
| urlType | Possible values can be: TK What is urlType - parameters: To fetch extra parameters. - options: To fetch options for a dropdown. - secret: To fetch secrets for a service. |
| url | The endpoint to which the request is sent, often including placeholders for dynamic data (e.g., integrations/parameters). |
| method | The HTTP method to be used (e.g., GET, POST). |
| body | The body object contains information sent with the request. Some fields explained: - name: This should match the folder name. - resource: The resource name for which the API call is being made (e.g., account). - secret: The secret used for the third-party API call. - loadParametersMethod: Assign the method name handling the API call. In the above example, it is getMoreParameters, which is defined at the resource level. |
Example Code
The following is a sample code snippet to show how Config schema can be implemented in Operation.
This is just an example. Depending on your specific use case or configuration, some parts of the code may vary.
"config": {
"urlType": "options",
"method": "post",
"url": "integrations/options",
"body": {
"name": "gemini",
"resource": "models",
"operation": "models.generate_text",
"secret": "{{parameters.secret}}",
"loadOptionsMethod": "getModels"
},
"labelKey": "name",
"valueKey": "id"
},