A Block Library in Neo enables users to create reusable, standardized blocks that can be utilized across different dataflows without the need to reconfigure them each time. This addresses the challenge of replicating blocks with similar configurations across multiple dataflows or rules.

Features

• Reusability: Allow users to build blocks with specific configurations or logic once and then reuse them in various dataflows. This avoids duplication of effort and promotes efficiency.
• Standardization: Ensures that certain functionalities or integrations are implemented consistently across different dataflows.
• Central Management: The Block Library acts as a central repository for these reusable components, making them easier to find, manage, and update.
• Versioning and Approval: Block Libraries are version-controlled and follow an approval process.
• Integration with Rules/Dataflows: Once approved, blocks from the library can be easily imported and used within rule versions or dataflows.
• Global Library: There is also a Global Library with predefined, read-only blocks managed at a higher organizational level.

Global Block Libraries & Org-Specific Block Library

Global Block Library: Global Library includes a set of pre-defined uneditable blocks managed by the Capillary Technology organization and is available for use across organisations, in that particular cluster. Blocks in the Global Library are read-only within your current organization. You can use these blocks in your dataflows, but you cannot modify their configurations directly.

Org-specific Block Library - These libraries are created and managed within individual organizations. Users with the appropriate Neo Edit Access can create and update blocks in these libraries. Updates to these blocks are allowed only when the library version is in the draft state.

Access Control & User Roles

For information on Neo access and more, refer to the documentation here.

Block Library Versioning

Block libraries are version-controlled. By default, the version v1 is available in the Draft state, allowing users with edit access to add blocks.

When a Neo Admin approves a version under review, the system automatically creates a new version with the next consecutive number. This new version starts in the Draft state and is a copy of the recently approved version, allowing further modifications.

Switching Library Versions in Dataflows

Once a dataflow is approved, you cannot change its block library version. To use a different block library version, you must create a new dataflow and link it to the updated library version.

Linking Library to Dataflows

A block library is linked to a specific dataflow version, not the dataflow itself. As a result, a dataflow can use multiple block library versions across different versions of the dataflow.

Managing Blocks in the Block Library

Adding a Block to a Version

To add a block to a specific library version,

1. On the Dataflows page in the Neo UI, click Access Libraries.

   

2. On the Libraries page, choose the version in Draft state where you want to add the block.

   📘

   Note

   • If no versions are available, any new block you create is automatically added to version v1 in the Draft state.
   • You can't add blocks into a version in the Published state.

   

3. (Optional) Hover over Add a description, to enter a description for the block library version.

   

4. Hover over +Add new block and select the block to add to the block library version.

5. Enter the Block name, Description, and Script.

   📘

   Note:

   • A version cannot have two blocks with the same name.
   • You can use an existing block name in a different version, but the block type must be the same.

6. Click Done.

The block is created in the chosen library version and is in the Draft state.

Reusing logic in a Script block

You can reuse common logic by writing it in a Script block and adding the block to the library. The Script block containing the reusable logic is called a Helper Function block. You can execute the helper function block using the DAO function, executeBlock.

The helper function blocks are useful for handling repetitive tasks such as validations, calculations, and data transformations. You can pass input values to these blocks during execution. The block uses those inputs and returns a response based on its logic. The input values (arguments) are passed using the DAO function getFunctionArguments.

Common Use Cases

Validations

• Mobile number format check
• Email validation
• Required field checks

Calculations

• Tax or price calculations
• Currency conversion
• Statistical functions

Data Transformations

• Field normalization
• Format conversion

Utilities

• Logging and auditing
• Common business logic
• Conditional routing

Example: Helper function block to validate a mobile number

To reuse common logic like validating a mobile number, you can create a Helper function block (Script block that contains this reusable logic) and add it to the block library.

The following example defines a helper function block named validateMobileNumber. This block checks whether the provided mobile number follows a valid format.

What the script does

• Uses dao.getFunctionArguments() to get the input arguments.

• Extracts the first argument and stores it in mobileNumber.

• Validates the number using a regular expression: it must start with a + and be followed by exactly 10 digits.

• Returns an object with:

  • isValid: a boolean indicating if the number is valid.
  • message: a confirmation message.

// Block Library Block Implementation
const validateMobileNumber = {
  execute: () => {
    // Access the mobile number argument
    const args = dao.getFunctionArguments();
    const mobileNumber = args[0]; // First argument passed to executeBlock
    
    // Perform validation
    return {
      isValid: /^\+[0-9]{10}$/.test(mobileNumber),
      message: "Valid mobile number"
    };
  }
};

Executing the helper function block

You can run a helper function block using the dao.executeBlock() function. This function calls a Script block from the block library and passes input arguments to it. The called block processes the input and returns a response.

Steps to execute a helper function block

1. Create and publish the helper function block in the block library.

2. In your main Script or Schema block, import dao from "neo/dao".

3. Use dao.executeBlock() to run the helper block:

   • Pass the helper block name as the first argument.
   • Pass input arguments as additional parameters.
   • Use the await keyword to wait for the block's response.

   Example:

   JavaScript

   const validationResult = await dao.executeBlock("validateMobileNumber", mobile);

   • validateMobileNumber is the name of the helper block.
   • mobile is the input value.
   • validationResult stores the response returned by the helper block.

Example scenario

Requirement
During a dataflow execution, you need to:

• Validate a mobile number.
• Calculate the total amount, including tax.

Script block using executeBlock

import dao from "neo/dao";
import logger from "neo/logger";

const script = {
  execute: async () => {
    const mobile = "+1234567890";
    const amount = 100;
    const tax = 18;

    // Call the mobile number validation helper block
    const validationResult = await dao.executeBlock("validateMobileNumber", mobile);

    if (!validationResult.isValid) {
      return { error: "Invalid mobile number" };
    }

    // Call the tax calculation helper block
    const totalAmountResult = await dao.executeBlock("calculateTotalAmount", amount, tax);

    return {
      validatedMobile: validationResult.cleanedNumber,
      totalAmount: totalAmountResult.amountWithTax
    };
  }
};

export {
  script as default
};

What this script does

1. Create and publish helper blocks
   The blocks validateMobileNumber and calculateTotalAmount are saved to the block library.

2. Importdao
   The main Script block imports dao to access DAO functions like executeBlock().

3. CallexecuteBlock() with block name and arguments

   • Pass "validateMobileNumber" and mobile to validate the number.
   • Pass "calculateTotalAmount" along with amount and tax to compute the total.

4. Useawait to get the result
   The await keyword pauses execution until the helper block returns a response. This ensures that you work with the actual result.

Best Practices

• Include only the required blocks in your dataflow to improve performance.
• Use clear, descriptive block names that reflect the block’s purpose.
• Document the expected arguments and their order for each block.
• Validate all input arguments inside the block using getFunctionArguments().
• Always use the JavaScript keyword await with executeBlock to ensure proper execution flow.

Limitations

• Only blocks included in the current dataflow's block library can be executed.
• Execution is asynchronous and must be awaited.
• Each block defines its response format; there is no standard structure.
• Arguments must be accessed by index, not by name.
• Blocks must be explicitly added to the dataflow to be executable.

Modifying a Version

You can edit blocks from a version in the Draft state.

To edit a block,

1. On the Libraries page, select the version in the Draft state that you want to modify.

2. Hover over the ellipsis next to the block you want to edit and click Edit block.

   

3. Edit the required fields in the block and click Done.
   Note: You cannot edit the Block name field.

   The block is successfully updated.

Deleting a Block from a Version

You can delete blocks from a version in the Draft state.

To delete a block,

1. On the Libraries page, select the version in the Draft state that you want to modify.

2. Hover over the ellipsis next to the block you want to edit and click Delete block.
   A confirmation message is received.

   

3. Click Yes, delete.

The specified block is deleted from the version.

Note: If you delete a block from a block library version that a dataflow uses and then try to update the dataflow to a new library version where the block no longer exists, Neo triggers a validation error. To fix this, you must remove the outdated block from the dataflow before switching to the new block library version.

Block Library Approval Workflow

The approval workflow for block library versions ensures that changes are reviewed and validated before deploying. The block library versions progress through different statuses, allowing you to create, submit, and refine block configurations.

Below are the key statuses in the workflow:

• Draft: The initial state where you can edit and update block configurations.
• Awaiting Approval: You can submit the version for approval once the changes are complete.
• Published: After a Neo Admin approves the version, it becomes available for use in dataflows.
• Rejected: If the version is rejected, you can edit the Block Library version and revert its status to Draft for further modifications.

Below is a flow chart illustrating the state change of a block library version.

Sending a Block Library Version for Approval

After making the necessary changes to the Block Library version, it is sent to the Neo Admin for approval.

To send the block library version for approval,

1. On the Libraries page, click Send for approval.
   A confirmation message appears.

   

2. On the confirmation message, click Yes.

   

The block library version is sent for approval by the Neo Admin and transitions to the Awaiting Approval state.

Approving a Block Library Version

The Neo Admin can approve the block library version.

To approve,

1. On the Libraries page, click Review and approve.
   The Review changes modal appears.

   

2. On the Review changes modal, review the changes by comparing the versions.

   📘

   Note

   If multiple versions of the Block Library exist, you can select the versions to compare from the drop-down.

   

3. Click Approve.
   A confirmation message appears.

4. In the confirmation message, enter a reason for approval and click Yes.

The block library version is approved and moves to the Published state.

Using Block Libraries in a Dataflow

1. Attach a Library Version: To use blocks from a block library in a dataflow, attach an approved library version to the specific dataflow version you are working on. You can attach either a global or an organisation-specific library. This attachment happens at the dataflow version level, ensuring that all blocks within that dataflow version consistently use the same library version.
2. Import Blocks: Once a library version is attached, you can import any block from that library onto your dataflow canvas using Import from Library from the block option.
3. Modify Block: You can make modifications and override the Input Execution Logic, Cacheable feature, and Execution Path in the block imported from the library.

📘

Notes

• You can add, modify, or delete blocks within a Block Library version while it is in the Draft state
• Each Block Library is tied to a specific dataflow version, not the dataflow itself. If you delete blocks from a library version that are still being referenced by an approved dataflow version, a validation error will occur when trying to update the dataflow version's library reference. In such cases, the outdated library blocks must be removed from the dataflow before the library version can be updated.
• In the Neo UI, when you use a block from a library, the block's name (from BlockLibraryMeta) is displayed on the canvas. This name might change across different library versions, even if the underlying blockMetaId remains the same.