Reference data sources of the organization

The ERP does not carry tax rates, exchange rates, return forms or bank holidays itself. It asks the reference-data service data-vNext for them, and what it asks for follows from how the organization is set up: its countries, currencies, VAT settings, bank accounts and fixed assets. This page reads the overview that answers three questions for an administrator: is the ERP connected to the reference data, which data points does this organization need, and is each of them current.

Before you start

• The call needs the admin scope. The page uses the admin key of the demo organization ($ERP_KEY, its first key), and later $BOB_KEY, the key of a person who has approve but not admin, to show the refusal. See getting started and conventions.
• The demo organization has two entities: CH01 (Demo AG, Switzerland, with a bank account, VAT returns and a fixed asset in an ESTV tax book) and DE01 (Demo GmbH, Germany, with monthly VAT returns, recapitulative statements and XRechnung e-invoices).
• In the demo the reference data runs inside the ERP process (in_process). An installation that calls a data-vNext server shows http. The values below are those of the test data: the freshness of the exchange rates and the dataset version differ in a real installation, and the page does not assert them.

1. Read the overview

curl "$ERP_URL/v1/settings/data-sources" \
  -H "Authorization: Bearer $ERP_KEY"

{
  "connection": {
    "mode": "in_process",
    "base_url": null,
    "pinned_version": null,
    "reachable": true,
    "dataset_version": "test",
    "last_error": null
  },
  "summary": {"gap": 0, "unknown": 0},
  "needs": [
    {
      "domain": "indirect_tax",
      "domain_title": "Indirect tax",
      "jurisdictions": ["CH"],
      "reasons": [
        {
          "entity": "CH01",
          "entity_name": "Demo AG",
          "feature": "vat_documents",
          "text": "CH01 Demo AG: VAT on invoices and bills"
        }
      ],
      "state": "ok",
      "source": {
        "authority": "ch-estv",
        "authority_name": "Eidgenössische Steuerverwaltung (ESTV)",
        "method": "curated",
        "state": "ok"
      }
    },
    "..."
  ],
  "customer_defined": [
    {"kind": "chart_of_accounts", "entity": "CH01", "template": "ch_kmu"},
    {"kind": "chart_of_accounts", "entity": "DE01", "template": "ifrs_generic"},
    {"kind": "chart_of_accounts", "entity": "US01", "template": "us_gaap"}
  ],
  "watcher": {"available": false}
}

The answer is long; the parts that matter are explained here.

connection

How the ERP reaches data-vNext and whether it did when the overview was made.

When reachable is false, every need has the state unknown, other is empty and last_error says why. Nothing can be said about freshness then.

needs

One entry per data point the organization needs. A need is a domain of reference data (indirect tax, tax returns, FX reference rates, calendars, e-invoicing, fixed assets, recapitulative statements, official VAT exchange rates) for a jurisdiction, matched to the authority that publishes it in the source register. It follows the jurisdiction's parents and groups: a German entity needs the EU's place-of-supply rules too.

• reasons says why: each reason names the entity and the feature that uses the data (vat_documents, eu_vat_rules, fx, tax_fx, due_dates, vat_returns, net_tax_rates, recapitulative, swiss_payments, payment_dates, xrechnung, depreciation) and a sentence. One data point can serve several entities and features: the ECB reference rates serve both entities.
• jurisdictions lists the jurisdictions the entities need the data for.
• source is the data point of the register: the authority, how the data arrives (method: curated records maintained by hand and cited to the authority, or feed data ingested regularly), the feeds with their freshness rule and last run, the number of records, and when its citations were last verified. It is null for a gap.
• state is the status of the need:

A gap means that the ERP would run without the data it needs: for example a country whose VAT rules nobody has registered.

summary

The number of needs in each state (needed, ok, stale, no_data, error, gap, unknown) and available, the number of data points in the register. The demo has no gap and nothing unknown; ok and stale depend on how recent the stored exchange rates are on the day.

The rest

• other lists the registered data points the organization does not need, for example the French indirect-tax rules, because the organization has no French entity.
• customer_defined lists what the organization defines for itself and what is therefore not reference data: the chart of accounts of each entity with its number of active accounts and the template it started from. They are never a need or a gap.
• as_of is the date the freshness was judged. watcher tells whether a report of the source watcher (which checks the cited legislation URLs) could be read; with in_process reference data it cannot, as the demo shows. status_error says why freshness is unknown when the register loaded but its status did not.

What can go wrong

The overview is for administrators. A key with the approve scope but not admin is refused:

curl "$ERP_URL/v1/settings/data-sources" \
  -H "Authorization: Bearer $BOB_KEY"

{"error": {"code": "missing_right"}}

A request without a key is refused before anything is read:

curl "$ERP_URL/v1/settings/data-sources"

{"error": {"code": "unauthorized"}}

Reference

• GET /v1/settings/data-sources