Connect your instance to the Hub Central

What it does

This page covers the configuration tasks that the administrator of your Futuh instance performs to connect it to the federation Hub Central and keep canonical data up to date.

Before you start

• Role: admin of the Futuh instance.
• The futuh_federation_client module installed (included by default in every Futuh instance).
• The federation token the Futuh team delivers when your annual subscription is activated.
• Estimated time: 10–15 min for the initial setup.

Configure the Hub Central endpoint

The client comes pre-configured with a record pointing to the Hub Central operated by Asamblea de Cooperación Por la Paz. In most cases you do not need to touch it: verify and continue.

1. Open Federación Futuh → Configuración Federación → Hubs configurados (interface labels are in Spanish).
2. Verify that a record named Hub Central Futuh with URL https://hub.futuh.coop exists.
3. Check that the Active field is ticked.
4. If you are federating against an alternative Hub (rare case: pilots, testing), edit the URL. It must respond to the endpoint /api/v1/canon/healthcheck with status code 200.

One Hub by default

Version 0.1 supports multi-hub but the normal case is a single one. Contact the Futuh team before adding additional Hubs.

Enter the authentication token

The Hub verifies that your instance has an active Futuh subscription through a Bearer token in every request. The token arrives by email when you renew your subscription.

1. In the Hub Central Futuh record, open the Authentication tab.
2. Paste the token into the Federation token field. The field is of password type and is encrypted in the database.
3. Click Test connection. The message Connection successful · Hub responds with canon_version X.Y.Z should appear.
4. Save.

The token expires

The token has the same validity as your annual subscription. When you renew, replace the previous one here. If it expires, the cron jobs fail with 403 Forbidden in the synchronization logs.

Review active canonical subscriptions

Your instance subscribes automatically to the canonical types required by the installed modules. If you have Radar, BDNS regulatory bases and awards arrive; if you have Incidencia Política, parliamentarians and committees arrive.

1. Open Federación Futuh → Configuración Federación → Subscriptions activas.
2. Review the list. Each subscription declares the destination model, the source URL, and the synchronization frequency.
3. Verify that the models consumed by your modules appear as Active (four or more in a typical installation).
4. If a subscription shows as Paused, check the latest entry in the synchronization log (usually an expired token or a major canonical version change).

Configure the pull cron frequency

Canonical synchronization runs via a daily scheduled action. In most instances this is enough, but the interval is adjustable.

1. Open Settings → Technical → Scheduled actions.
2. Locate Futuh Federation: Daily canonical hub pull (internal name _cron_federation_pull_all).
3. Verify the interval Every day and status Active.
4. If you need more frequent updates (campaign with daily deadlines), change the interval to Every hour. The load on the Hub is modest.
5. The second action, Futuh Federation: Healthcheck every 4h, notifies the administrator after three consecutive failures. Leave it as delivered.

Real latency

The hourly cron has one to two minutes of latency depending on load. For real-time cases, use the pull_canon_record API from your code.

Flag manual edits on canonical data

When your organization manually edits a record that came from the Hub (for example, you correct the email of a parliamentarian the Hub does not yet have), Futuh marks the record as manually edited and stops overwriting it in subsequent synchronizations.

1. Open any federated record (for example, a parliamentarian under Contacts → Parliamentarians).
2. Edit the field and save.
3. Verify that the Canonical synchronization tab shows the Manually edited badge.
4. If you later want to accept what the Hub says, click Restore canonical: the next cron run will overwrite your changes.

Manual edits apply to the whole record, not to individual fields

The cron stops touching the entire record, not only the field you changed. If you want to keep most records synchronized and only edit one, open an issue with the Hub so the correction propagates to all instances.

Troubleshooting common issues

• 403 Forbidden in the synchronization log → expired or revoked token. Replace the token and click Test connection.
• 404 Not Found on a specific model → the subscription points to a canonical type the Hub no longer publishes (a major version change occurred). Check the notice on the Messages tab of the record: it carries a link to the upgrade note for the source module.
• Cron in failed state after a recent installation → after installing a module that adds crons, you must restart the Odoo container for the registry to reload. If you cannot restart, run the cron manually once from Scheduled actions.

Next steps

• Federación Futuh: overview to understand what is federated and why.
• Configure Radar as administrator if the first module you will feed with federated data is Radar.
• Glossary of canonical terms to clarify canonical signature, canonical documentation, or bundle.