Skip to main content

Resource Folder

  • The term Resourcerefers to entities such as accounts, contacts, deals, etc. The Resource parameter facilitates targeted operations within the activity, enabling you to manipulate specific data types effectively.

  • The resources directory contains JSON schemas for specific resources related to your integration. Each schema defines the parameters and operations that can be performed on that particular resource.

  • This structure allows you to manage various resources efficiently, ensuring that each resource has its own set of configurable parameters and operational logic.

Structure of Resource Schemas​

Parameters​

  • Each resource schema includes an array of parameters that define the inputs required for the operations associated with that resource.
{
    "parameters": [
        {
            "name": "operation", // operation = account.create
            "meta": {
                "displayName": "Operation",
                "displayType": "select",
                "placeholder": "Select an operation",
                "description": "Select the operation you want to perform.",
                "options": [
                    {
                        "label": "Create Account",
                        "value": "account.create"
                    },
                    {
                        "label": "Delete Account",
                        "value": "account.delete"
                    },
                    {
                        "label": "Get Account",
                        "value": "account.get"
                    },
                    {
                        "label": "List Accounts",
                        "value": "account.list"
                    },
                    {
                        "label": "Update Account",
                        "value": "account.update"
                    }
                ],
                "validation": {
                    "required": true
                },
                "dependencies": {
                    "conditions": [
                        {
                            "field": "resource",
                            "operator": "EQUALS",
                            "value": "account"
                        }
                    ]
                }
            }
        }
    ]
}
  • This array defines the input parameters for a specific operation within the integration. Boltic supports multiple types of input components, which you can refer to here.

Operations​

  • Each Operation defines specific actions that can be performed on resources, such as creating or 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, or deleting the resource. Each operation includes its own set of parameters and configurations.

Example​

  • Create: Below is an example of a JSON schema for the Freshsales create account resource.
{
    "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"
            }
        }
    },
    "getMoreParameters": {
        "definition": {
            "method": "get",
            "url": "{{secrets.api_url}}/api/settings/sales_accounts/fields",
            "headers": {
                "Authorization": "Token token={{secrets.api_key}}"
            },
            "qs": {},
            "response": {
                "output": "{{response.data.fields}}",
                "error": {
                    "message": "{{response.data.errors.message}}",
                    "code": "{{response.data.errors.code}}"
                },
                "transformOutput": "const result = output.sort((a, b) => a.position - b.position).map((ele) => { const excludeParameters = [ 'phone_numbers', 'sales_accounts', 'active_sales_sequences', 'last_contacted', 'last_contacted_mode', 'last_contacted_sales_activity_mode', 'last_contacted_via_sales_activity', 'completed_sales_sequences', 'last_seen', 'lead_score', 'recent_note', 'creater_id', 'created_at', 'updater_id', 'updated_at', 'web_form_ids', 'last_assigned_at', ]; if (!excludeParameters.includes(ele.name)) { const typeMap = { text: 'text', textarea: 'textarea', dropdown: 'select', auto_complete: 'multitext', multi_select_dropdown: 'multiselect', radio: 'select', number: 'number', }; const placeholderPrefix = ['select', 'multiselect', 'radio'].includes( typeMap[ele.type] ) ? 'Select' : 'Enter'; const requiredParameters = ['emails', 'first_name']; const newObj = { name: ele.name, meta: { displayName: ele.label, displayType: typeMap[ele.type] || 'text', placeholder: `${placeholderPrefix} ${ele.label}`, validation: { required: requiredParameters.includes(ele.name) || ele.required, }, }, }; if (['dropdown', 'radio', 'multi_select_dropdown'].includes(ele.type)) { newObj.meta.htmlProps = { allowDynamic: true }; if (ele.choices && ele.choices.length) { newObj.meta.options = ele.choices.map((choice) => ({ label: choice.value, value: choice.id, })); } else { newObj.meta.displayType = 'text'; } if (ele.type === 'multi_select_dropdown') { newObj.meta.value = []; } } if (ele.default === false) { newObj.prop = 'custom_field'; } return newObj; } return null; }).filter((ele) => ele !== null); let custom_field = { name: 'custom_field', meta: { children: [], displayType: 'object', }, }; const outputWithCustomField = result.reduce((acc, ele) => { if (ele.prop === 'custom_field') { custom_field.meta.children.push(ele); } else { acc.push(ele); } return acc; }, []); if (custom_field.meta.children.length > 0) { outputWithCustomField.push(custom_field); } return outputWithCustomField"
            }
        }
    }
}

Explanation of the operation structure:​

  • Each operation within a resource schema is structured to define how the operation functions. The structure consists of four main components: definition, parameters, config, and output.

Definition:

  • The definition schema is used to make an API call when an activity is run from the workflow UI. This includes:
    • 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 (e.g., {{secrets.api_url}}/api/notes).
    • Headers: Any required headers for the request, such as authorization tokens or content type.
    • Query Strings (qs): Any query parameters that need to be sent with the request.
    • Body: The structure of the data sent in the request body, using placeholders for dynamic values derived from user input.
    • Response: The expected structure of the response, including how to extract output and handle errors.

Parameters:

  • This section defines the inputs required for the operation. For possible input types, refer here.

Output:

  • This section defines the expected results from the operation, including:
    • 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.

Config:

  • This 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:

    • urlType: Possible values can be:
      • 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.

getMoreParameters:

  • This field contains a definition object that defines the API configurations of the third-party API. It consists of:
    • url: The endpoint to which the request is sent, often including placeholders for dynamic data (e.g., {{secrets.api_url}}/api/settings/sales_accounts/fields).
    • method: The HTTP method to be used (e.g., GET, POST).
    • headers: Any required headers for the request, such as authorization tokens or content type.
    • Query Strings (qs): Any query parameters that need to be sent with the request.
    • response: Defines the response body.
      • transformOutput: The function used to parse and transform the response data. Keeping the output as a parameter, you can write JavaScript to transform the data. By default, the output is return output;.