diff --git a/.claude/docs-guidelines/repo-conventions.md b/.claude/docs-guidelines/repo-conventions.md index 5688bce9d..60f435cba 100644 --- a/.claude/docs-guidelines/repo-conventions.md +++ b/.claude/docs-guidelines/repo-conventions.md @@ -39,7 +39,14 @@ They are never fixed in the Markdown. - One directory per page with an `index.md` inside: `my-topic/index.md`. - Add the page to the `.pages` file of its directory with the title used in the menu, then run `task update:navigation` — see "Navigation" below. -- The page title (`# Heading`) and the `.pages` nav title must correspond. +- A page carries its name in three places, which serve different purposes and are not required to match: + the `.pages` entry is the label in the navigation menu, `title:` in the front matter is the site page title + and the entry on the tags page, and the `# Heading` is the visible title on the page itself. + A menu label is written for scanning inside its section and is often shorter than the heading, which is read + without that context. Do not "fix" such a divergence as if it were drift. +- The front matter `title` is often written *longer* than the heading, because the tags page lists pages flat, + without the navigation hierarchy that would say what a page belongs to. The cmemc pages are the model: + `title: "cmemc: Installation"` against a heading of `Installation`, and the same for every page in that group. - Images live next to the `index.md` that uses them. - Renaming or moving a page requires a redirect stub — see "Redirects" below. diff --git a/CLAUDE.md b/CLAUDE.md index 9d61c9786..c6177928f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -46,6 +46,11 @@ comes from the generated `nav.yml`, pulled in by `INHERIT` at the top of `mkdocs `task update:navigation` to update `nav.yml` with the `.pages` change. `zensical build --strict` compiles an unlisted page without complaining — only `task check` catches the drift. +**A page has three titles, and they need not be the same.** The `.pages` entry is the menu label, `title:` in +the front matter is the site page title and the tags page entry, and the `# Heading` is the visible title on +the page. They serve different purposes — a menu label is written for scanning inside its section. Divergence +between them is not drift and is not something to correct. + **`task check` is the gate, not `task build`.** It runs the link check, rumdl, yamllint, the navigation check and the build-output check. Do not leave it failing. diff --git a/data/integrations.yml b/data/integrations.yml index b6abfd5eb..26c889646 100644 --- a/data/integrations.yml +++ b/data/integrations.yml @@ -121,12 +121,12 @@ integrations: - name: Kubernetes icon: ":simple-kubernetes:" content: | - You can {{p.cmem_plugin_kubernetes_Execute}} and captures its output to process it. + {{p.cmem_plugin_kubernetes_Execute}} and capture its output for further processing. - name: GraphQL icon: ":simple-graphql:" content: | - You can execute a {{p.cmem_plugin_graphql_workflow_graphql_GraphQLPlugin}} and process the result in a workflow. + Execute a {{p.cmem_plugin_graphql_workflow_graphql_GraphQLPlugin}} and process the result in a workflow. - name: eMail / SMTP / IMAP icon: ":material-email-outline:" @@ -142,7 +142,7 @@ integrations: - name: Kafka icon: ":simple-apachekafka:" content: | - You can [send]({{p.cmem_plugin_kafka_SendMessages_ref}}) and + [Send]({{p.cmem_plugin_kafka_SendMessages_ref}}) and [receive messages]({{p.cmem_plugin_kafka_ReceiveMessages_ref}}) to and from a Kafka topic, on a plain broker as well as on a [Confluent Cloud](https://confluent.cloud) cluster. @@ -151,18 +151,18 @@ integrations: content: | Use a Nextcloud instance to [list]({{p.cmem_plugin_nextcloud_List_ref}}) and [download files]({{p.cmem_plugin_nextcloud_Download_ref}}) to process - them or [upload files]({{p.cmem_plugin_nextcloud_Upload_ref}}) you created with Corporate Memory. + them, or [upload files]({{p.cmem_plugin_nextcloud_Upload_ref}}) created with Corporate Memory. - name: Salesforce icon: ":fontawesome-brands-salesforce:" content: | - Interact with your Salesforce data, such as {{p.cmem_plugin_salesforce_workflow_operations_SobjectCreate}} or + Interact with Salesforce data, such as {{p.cmem_plugin_salesforce_workflow_operations_SobjectCreate}} or execute a {{p.cmem_plugin_salesforce_SoqlQuery}}. - name: Mattermost icon: ":simple-mattermost:" content: | - Send workflow reports or any other message to user and groups in you Mattermost with + Send workflow reports or any other message to users and groups in Mattermost with the {{p.cmem_plugin_mattermost}} task. - name: Spark @@ -178,20 +178,20 @@ integrations: - name: PowerBI icon: ":other-powerbi:" content: | - Leverage your Knowledge Graphs in PowerBI by using our + Leverage Knowledge Graphs in PowerBI with the [Corporate Memory Power-BI-Connector](../../consume/consuming-graphs-in-power-bi/index.md). - name: Redash icon: ":other-redash:" content: | - Leverage your Knowledge Graphs in Redash using the integrated + Leverage Knowledge Graphs in Redash with the integrated [Corporate Memory Redash-Connector](../../consume/consuming-graphs-with-redash/index.md). - name: Apify icon: ":other-apify:" content: | Use the {{p.cmem_plugin_apify_RunActor}} task to run web scrapers and other - [Apify](https://apify.com) actors, and process the resulting dataset in your workflow. + [Apify](https://apify.com) actors, and process the resulting dataset in a workflow. - name: CKAN icon: ":other-ckan:" @@ -236,8 +236,9 @@ integrations: - name: n8n icon: ":simple-n8n:" content: | - Get data and trigger eccenca Corporate Memory build workflows by using our - [n8n Community Node](https://github.com/eccenca/n8n-nodes-corporate-memory). + Get data and trigger eccenca Corporate Memory build workflows with the + [n8n Community Node](../../automate/n8n-node/index.md), which is published in the + [n8n-nodes-corporate-memory repository](https://github.com/eccenca/n8n-nodes-corporate-memory). ##### # Files diff --git a/docs/automate/.pages b/docs/automate/.pages index 90bd2dc9a..f070d7152 100644 --- a/docs/automate/.pages +++ b/docs/automate/.pages @@ -5,4 +5,5 @@ nav: - Processing Data with variable input Workflows: processing-data-with-variable-input-workflows - Scheduling Workflows: scheduling-workflows - Continuous Integration: continuous-integration + - n8n Integration: n8n-node diff --git a/docs/automate/index.md b/docs/automate/index.md index f7ff7c045..2f452a4e7 100644 --- a/docs/automate/index.md +++ b/docs/automate/index.md @@ -35,4 +35,10 @@ Setup processes and automate activities based on and towards your Knowledge Grap Setup processes which continuously integrate data artifacts such as vocabularies and shapes with your Corporate Memory instances. +- :simple-n8n: [n8n Community Node](n8n-node/index.md) + + --- + + Trigger Corporate Memory workflows and read from the Knowledge Graph inside event-driven n8n automations. + diff --git a/docs/automate/n8n-node/index.md b/docs/automate/n8n-node/index.md new file mode 100644 index 000000000..917f74916 --- /dev/null +++ b/docs/automate/n8n-node/index.md @@ -0,0 +1,76 @@ +--- +title: "n8n: Corporate Memory Community Node" +icon: simple/n8n +status: new +tags: + - Automate + - Integration +--- +# n8n Community Node + +## Introduction + +[n8n](https://n8n.io/) is a workflow automation tool that connects applications and services to each other, driven by events such as an incoming webhook, a new file or a schedule. +The eccenca Corporate Memory community node adds Corporate Memory to the set of systems an n8n automation can reach. +It is published as `@eccenca/n8n-nodes-corporate-memory` and installs through the n8n community node installer. + +With the node in place, the connectors that n8n already provides become available to Corporate Memory processes without writing a Python plugin or a custom script. +An automation can start a Corporate Memory workflow, read from the Knowledge Graph and hand the result to any other system in the same n8n canvas. + +!!! note "Relation to cmemc" + + cmemc automates Corporate Memory from a terminal, a script or a continuous integration pipeline. + The n8n community node covers the case where the automation is event driven and already connects other systems. + Both work against the same Corporate Memory APIs, so the choice is one of environment rather than capability. + +## Use cases + +- **Event-driven workflow execution:** + An event in n8n starts a Corporate Memory workflow. + Typical triggers are an incoming webhook, a new file in an object store or a document management system, an incoming mail, or a schedule. + +- **Publishing graph content to downstream systems:** + A query from the query catalog runs on a schedule and its result rows are forwarded to a messaging service, an issue tracker, a spreadsheet or a REST API. + +- **Knowledge Graph lookup inside a larger automation:** + A SPARQL query enriches items that already flow through an n8n automation with context from the Knowledge Graph. + +## Prerequisites + +- **An n8n instance:** + The node is a verified community node and installs on a self-hosted n8n instance as well as on n8n Cloud. + See [Installing community nodes](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n documentation. + +- **An OAuth client in Keycloak:** + The node authenticates with the client credentials grant and needs a confidential client, scoped to the permissions the automation requires. + Creating a service account client is described under [Keycloak](../../deploy-and-configure/configuration/keycloak/index.md). + +- **A reachable Corporate Memory deployment:** + The n8n instance needs network access to the base URL of the Corporate Memory deployment and to its Keycloak token endpoint. + +## How the node works + +The connection to Corporate Memory is configured once as a credential. +It holds the client ID, the client secret and the base URL of the deployment, and derives the token endpoint and the component URLs from that base URL. +The credential is then reused by every node instance in every automation. + +A single node covers three resources, which correspond to the three parts of Corporate Memory an automation reaches: +workflows in Build, the SPARQL endpoint of the Knowledge Graph, and the query catalog. +Selecting a resource offers the actions available for it: + +| Resource | Action | Result | +| --- | --- | --- | +| Workflow | Execute a workflow and return its result | The automation waits for the workflow to finish and continues with its output. | +| Workflow | Start a workflow execution | The workflow is started in the background and the identifiers of the running execution are returned. | +| SPARQL | Run a SPARQL SELECT query | One item per result row. | +| Query Catalog | List catalog queries | The queries saved in the selected catalogs. | +| Query Catalog | Run a saved query | The result of a saved query, with placeholders substituted. | + +![The eccenca Corporate Memory node and its actions in the n8n node details panel](n8n-node-details.png "eccenca Corporate Memory node details"){ class="bordered" } + +Because each action emits n8n items, the output of one Corporate Memory action can be routed into any other node, including a second Corporate Memory action. + +## Further reading + +- [n8n-nodes-corporate-memory repository](https://github.com/eccenca/n8n-nodes-corporate-memory) — installation, credential fields and per-action parameters +- [@eccenca/n8n-nodes-corporate-memory on npm](https://www.npmjs.com/package/@eccenca/n8n-nodes-corporate-memory) — the published package and its current version diff --git a/docs/automate/n8n-node/n8n-node-details.png b/docs/automate/n8n-node/n8n-node-details.png new file mode 100644 index 000000000..96164ee61 Binary files /dev/null and b/docs/automate/n8n-node/n8n-node-details.png differ diff --git a/docs/build/integrations/index.md b/docs/build/integrations/index.md index 9822c150a..891a36427 100644 --- a/docs/build/integrations/index.md +++ b/docs/build/integrations/index.md @@ -31,7 +31,7 @@ to interact with any --- Use the [Run Apify actor](../../build/reference/customtask/cmem_plugin_apify-RunActor.md) task to run web scrapers and other -[Apify](https://apify.com) actors, and process the resulting dataset in your workflow. +[Apify](https://apify.com) actors, and process the resulting dataset in a workflow. - :other-apacheavro:{ .lg .middle } Avro @@ -155,7 +155,7 @@ geocoding service, such as [Nominatim](https://nominatim.org/), --- - You can execute a [GraphQL query](../../build/reference/customtask/cmem_plugin_graphql-workflow-graphql-GraphQLPlugin.md) and process the result in a workflow. + Execute a [GraphQL query](../../build/reference/customtask/cmem_plugin_graphql-workflow-graphql-GraphQLPlugin.md) and process the result in a workflow. - :simple-apachehive:{ .lg .middle } Hive @@ -190,7 +190,7 @@ geocoding service, such as [Nominatim](https://nominatim.org/), --- - You can [send](../../build/reference/customtask/cmem_plugin_kafka-SendMessages.md) and + [Send](../../build/reference/customtask/cmem_plugin_kafka-SendMessages.md) and [receive messages](../../build/reference/customtask/cmem_plugin_kafka-ReceiveMessages.md) to and from a Kafka topic, on a plain broker as well as on a [Confluent Cloud](https://confluent.cloud) cluster. @@ -199,7 +199,7 @@ on a plain broker as well as on a [Confluent Cloud](https://confluent.cloud) clu --- - You can [Execute a command in a kubernetes pod](../../build/reference/customtask/cmem_plugin_kubernetes-Execute.md) and captures its output to process it. + [Execute a command in a kubernetes pod](../../build/reference/customtask/cmem_plugin_kubernetes-Execute.md) and capture its output for further processing. - :simple-mariadb:{ .lg .middle } MariaDB @@ -213,7 +213,7 @@ on a plain broker as well as on a [Confluent Cloud](https://confluent.cloud) clu --- - Send workflow reports or any other message to user and groups in you Mattermost with + Send workflow reports or any other message to users and groups in Mattermost with the [Send Mattermost messages](../../build/reference/customtask/cmem_plugin_mattermost.md) task. @@ -243,8 +243,9 @@ from and to a single ZIP archive. --- - Get data and trigger eccenca Corporate Memory build workflows by using our -[n8n Community Node](https://github.com/eccenca/n8n-nodes-corporate-memory). + Get data and trigger eccenca Corporate Memory build workflows with the +[n8n Community Node](../../automate/n8n-node/index.md), which is published in the +[n8n-nodes-corporate-memory repository](https://github.com/eccenca/n8n-nodes-corporate-memory). - :simple-neo4j:{ .lg .middle } Neo4J @@ -260,7 +261,7 @@ from and to a single ZIP archive. Use a Nextcloud instance to [list](../../build/reference/customtask/cmem_plugin_nextcloud-List.md) and [download files](../../build/reference/customtask/cmem_plugin_nextcloud-Download.md) to process -them or [upload files](../../build/reference/customtask/cmem_plugin_nextcloud-Upload.md) you created with Corporate Memory. +them, or [upload files](../../build/reference/customtask/cmem_plugin_nextcloud-Upload.md) created with Corporate Memory. - :material-microsoft-office:{ .lg .middle } Office 365 @@ -338,7 +339,7 @@ using the [Search Vector Embeddings](../../build/reference/customtask/cmem_plugi --- - Leverage your Knowledge Graphs in PowerBI by using our + Leverage Knowledge Graphs in PowerBI with the [Corporate Memory Power-BI-Connector](../../consume/consuming-graphs-in-power-bi/index.md). @@ -363,7 +364,7 @@ using the [Search Vector Embeddings](../../build/reference/customtask/cmem_plugi --- - Leverage your Knowledge Graphs in Redash using the integrated + Leverage Knowledge Graphs in Redash with the integrated [Corporate Memory Redash-Connector](../../consume/consuming-graphs-with-redash/index.md). @@ -378,7 +379,7 @@ using the [Search Vector Embeddings](../../build/reference/customtask/cmem_plugi --- - Interact with your Salesforce data, such as [Create/Update Salesforce Objects](../../build/reference/customtask/cmem_plugin_salesforce-workflow-operations-SobjectCreate.md) or + Interact with Salesforce data, such as [Create/Update Salesforce Objects](../../build/reference/customtask/cmem_plugin_salesforce-workflow-operations-SobjectCreate.md) or execute a [SOQL query (Salesforce)](../../build/reference/customtask/cmem_plugin_salesforce-SoqlQuery.md). diff --git a/docs/release-notes/2026/corporate-memory-26-2/index.md b/docs/release-notes/2026/corporate-memory-26-2/index.md index c0174663e..27b8dcd7d 100644 --- a/docs/release-notes/2026/corporate-memory-26-2/index.md +++ b/docs/release-notes/2026/corporate-memory-26-2/index.md @@ -33,7 +33,7 @@ The highlights of this release are: - Graph Insights shows [resources with images and icons throughout the exploration](../../../deploy-and-configure/configuration/graphinsights/index.md#graph-insights-configuration), and adds a content language selection that switches the language of captions and descriptions of the explored data at any time. - Automate: **n8n Corporate Memory Community Node** - - Initial release of [`@eccenca/n8n-nodes-corporate-memory` v0.4.2](https://www.npmjs.com/package/@eccenca/n8n-nodes-corporate-memory), a n8n community node available through the n8n community node installer. + - Initial release of the [n8n Corporate Memory community node](../../../automate/n8n-node/index.md) v0.4.2, available through the n8n community node installer. This release delivers the following component versions: @@ -622,7 +622,7 @@ We are excited to announce the release of Graph Insights v20.0, which adds a con ## eccenca n8n Community Node v0.4.2 -We are excited to announce the release of the n8n Corporate Memory community node v0.4.2, see [@eccenca/n8n-nodes-corporate-memory](https://www.npmjs.com/package/@eccenca/n8n-nodes-corporate-memory) for details. +We are excited to announce the release of the n8n Corporate Memory community node v0.4.2, see [n8n Community Node](../../../automate/n8n-node/index.md) for details. ## Migration Notes diff --git a/mkdocs.yml b/mkdocs.yml index 4f5f5a484..4eea44a9b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -66,6 +66,7 @@ extra: Package: package Marketplace: marketplace "Application View": application-view + Integration: integration # https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/ version: provider: mike diff --git a/nav.yml b/nav.yml index 66a91a569..f99b2a363 100644 --- a/nav.yml +++ b/nav.yml @@ -707,6 +707,8 @@ nav: - automate/scheduling-workflows/index.md - Continuous Integration: - automate/continuous-integration/index.md + - n8n Integration: + - automate/n8n-node/index.md - Develop: - Develop: develop/index.md - Accessing Graphs with Java Applications: