Block

Block es un componente de Nappai que te permite gestionar bloques individuales dentro de páginas de Notion. Con él puedes crear nuevos bloques, borrar bloques existentes, listar los bloques de una página y añadir contenido escrito en Markdown que se convierte automáticamente en bloques nativos de Notion.

¿Cómo funciona?

El componente se conecta a la API oficial de Notion mediante un token de integración que el usuario debe haber configurado previamente en la sección de credenciales de Nappai. Cuando se ejecuta, el componente envía peticiones HTTP a los endpoints de Notion para crear, borrar, listar o actualizar bloques según la operación seleccionada. Si se elige la operación Add Markdown, el texto Markdown se procesa y se convierte en una serie de bloques que se insertan en la página o bloque padre indicado.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

• Create: Crea un nuevo bloque dentro de la página o bloque padre especificado. Necesitas indicar el tipo de bloque y opcionalmente los hijos en formato JSON.
• Delete: Elimina un bloque existente usando su ID.
• List: Recupera la lista de bloques que contiene una página o bloque padre.
• Add Markdown: Convierte un texto escrito en Markdown en bloques de Notion y los añade a la página o bloque padre.

Para usar el componente, primero selecciona la operación que necesitas en el campo “Operation” (Operación).

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

• Fixed (Fijo): Escribes el valor directamente en el campo.
• Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
• Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

• Operation: Selecciona la operación que quieres ejecutar.
  • Visible en: Create, Delete, List, Add Markdown
• Block ID: Target block ID for single-block operations.
  • Visible en: Delete
• Select block type: Select the type of block to create.
  • Visible en: Create
• Children: The children of the new block as a JSON string.
  • Visible en: Create
• Mapping Mode: Enable mapping mode to process multiple data records in batch.
  • Visible en: Create, Delete, List, Add Markdown
• Markdown Text: The markdown text to convert to Notion blocks or the content to add to the page.
  • Visible en: Add Markdown
• Parent Page ID: Notion Page ID or Block ID where the new block will be created.
  • Visible en: Create, List, Add Markdown
• Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.
  • Visible en: Create, Delete, List, Add Markdown
• Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.
  • Visible en: Create, Delete, List, Add Markdown
• Tools arguments metadata: Defines the arguments metadata for the tools.
  • Visible en: Create, Delete, List, Add Markdown

Credencial
Este componente requiere una credencial de tipo Notion API.

1. Configura primero la credencial en la sección de credenciales de Nappai.
2. Luego selecciona esa credencial en el campo “Credential” del componente.
   La credencial necesita un Notion Integration Token que puedes crear siguiendo la guía oficial de Notion.

Salidas

• Data: Resultado de la operación (por ejemplo, la lista de bloques o la confirmación de eliminación).
• Tool: Objeto que permite que un agente de IA utilice esta operación como una herramienta dentro de un flujo de trabajo.

Ejemplo de Uso

Caso 1 – Crear un bloque de párrafo

1. Selecciona la operación Create.
2. En Parent Page ID escribe el ID de la página donde quieres añadir el bloque.
3. En Select block type elige paragraph.
4. En Children escribe {"text":[{"content":"Hola, mundo!"}]}.
5. Activa la credencial de Notion y ejecuta el flujo.
   El bloque aparecerá en la página indicada.

Caso 2 – Añadir contenido Markdown

1. Selecciona la operación Add Markdown.
2. En Parent Page ID escribe el ID de la página destino.
3. En Markdown Text escribe:

   # Título
   Este es un **ejemplo** de Markdown.

4. Ejecuta el flujo.
   El texto se convertirá en bloques de Notion (encabezado y párrafo) y se añadirá a la página.

Componentes Relacionados

• NotionBlockComponent: Base que maneja la lógica de bloques de Notion.
• NotionDirectoryLoader: Carga directorios y páginas de Notion para su uso posterior.

Consejos y Mejores Prácticas

• Usa Mapping Mode cuando necesites procesar listas de bloques en lote; evita enviar demasiadas peticiones individuales.
• Cuando crees bloques, valida el JSON de Children con una herramienta de validación para evitar errores de formato.
• Para operaciones de borrado, verifica siempre el Block ID antes de ejecutar para evitar eliminar el bloque incorrecto.
• Aprovecha los campos Tool Name y Tool Description cuando conectes el componente a un agente; esto facilita la selección automática de la herramienta correcta.

Consideraciones de Seguridad

• La credencial de Notion contiene un token de acceso que permite leer y escribir en tus páginas. Guárdala con cuidado y no la compartas públicamente.
• Si compartes flujos que usan este componente, asegúrate de que solo los usuarios autorizados tengan acceso a la credencial.