Wolken
The Wolken source ingests knowledge-base articles from a Wolken ServiceDesk
instance. Each article becomes a record in the pipeline — its contents are
uploaded to a new agent session for processing. With data_api, articles are
filtered by the lifecycle, validation, and audience-level filters you
configure. With kb_module, articles are filtered by category. Each article's
audience attributes are carried as document metadata for attribute-based
filtering.
Authentication
Before you create the pipeline, obtain the Wolken API endpoint, tenant domain, OAuth client ID, service account, auth code, and refresh token from your Wolken administrator or Wolken support. There is no Vectara-hosted flow for issuing these credentials.
Despite its name, auth_code is not a browser OAuth authorization code. It is
sent verbatim as the Authorization header on the token request, so include any
scheme prefix Wolken issues it with (typically Basic <base64>).
Configuration
Wolken deployments expose the knowledge base through one of two API families,
selected with the kb_api field. The data_api family reads the provisioned
data API endpoint and supports server-side update-time filters. The kb_module
family reads the Knowledge Base module REST API, which lists articles by
category and offers no server-side filters. Ask your Wolken administrator which
family your deployment provisions. A data_api call against a deployment that
only provisions the Knowledge Base module fails with Wolken's
Invalid data API name passed error.
The connector requires credentials with read access to the knowledge-base
listing and article-detail endpoints. For data_api, incremental sync
additionally requires the listing to support update-time filters. Which filters
the listing accepts, and the specific status, validation, and level IDs, vary by
Wolken deployment.
SOURCE FIELD (WOLKEN)
Code example with json syntax.1
Fields
| Field | Required | Description |
|---|---|---|
type | Yes | wolken_kb. |
api_endpoint | Yes | Base URL of the Wolken API (e.g. https://example-api.wolkenservicedesk.com). |
domain | Yes | The value of the domain header issued with your Wolken API credentials. Wolken deployments vary in whether this is a tenant name or a full hostname, so use the exact value from your credential handoff. |
kb_api | No | The Wolken API family used to read the knowledge base, either data_api or kb_module. Defaults to data_api. |
client_id | Yes | Wolken OAuth client ID. |
service_account | Yes | Wolken service account the API calls run as. |
auth_code | Yes | The auth code Wolken issues for the instance, used with refresh_token to obtain access tokens. Sent verbatim as the Authorization header on the token request, typically in Basic <base64> form. Encrypted at rest and never returned in responses. |
refresh_token | Yes | Long-lived refresh token exchanged for access tokens. Encrypted at rest and never returned in responses. |
category_ids | No | Wolken knowledge-base category IDs to restrict ingestion to. If unset, articles of every category are ingested. Category IDs are specific to your deployment. Applies to kb_module only. |
article_ids | No | Wolken knowledge-base article IDs to restrict ingestion to. If unset, all articles matching the other configured filters are ingested. |
article_statuses | No | Article lifecycle statuses to ingest, any of published, retired, draft, or delete. If unset, articles of every status are ingested. Applies to both API families. |
status_id | No | Lifecycle status to filter articles by. If unset, articles of every lifecycle status are ingested. Status IDs are specific to your deployment. Applies to data_api only. |
validation_status_id | No | Validation status to filter articles by. If unset, articles of every validation status are ingested. Validation status IDs are specific to your deployment. Applies to data_api only. |
level_id | No | Audience level to filter articles by. If unset, articles of every audience level are ingested. Level IDs are specific to your deployment. Applies to data_api only. |
update_upper_bound_operator | No | Operator for the incremental-sync upper bound when filtering by last-updated time. lt is strict less-than; lte is less-than-or-equal. Defaults to lte. Applies to data_api only. |
article_url_template | No | Template for each article's public URL. The {article_number} placeholder is replaced with the article number. When omitted, the URL returned by the Wolken listing is used. |
How records are fetched
With data_api, each run enumerates the knowledge-base listing, applying the
status_id, validation_status_id, and level_id filters you configured. Each
article that passes the filters becomes one record.
With kb_module, each run first lists every knowledge-base category and then
enumerates the articles filed under each category. When category_ids is set,
only the matching categories are enumerated, and a configured ID that matches
no listed category is ignored. An article filed under several
categories is listed once per category. Per-record deduplication collapses
copies that arrive after the first copy is processed, and copies processed
concurrently are reprocessed redundantly and converge on identical content. The
module offers no server-side filters, so update-time bounds are applied after
listing.
In both families, when article_ids is set, articles outside the configured
IDs are discarded after listing. When article_statuses is set, articles whose
listed status is not among the configured statuses are discarded the same way.
An article the listing reports no status for is always ingested. Both filters
run on the listing entry, so a discarded article costs neither an
article-detail request nor an agent session.
The kb_module listing reports every article a category holds regardless of
lifecycle state, including retired and draft articles, and the Knowledge Base
module offers no server-side status filter, so article_statuses is the only
way to restrict ingestion to published content under that family.
In both families, article contents are read from the article-detail endpoint and composed into a single HTML document from the labeled sections the response carries.
Articles are enumerated with offset pagination. An article edited or archived while a run is in flight can shift position between pages and be skipped until its next edit or a full refresh. Wolken offers no change-token alternative.
Source metadata
Each record carries source metadata that the connector resolves at fetch time.
system_metadata:
| Key | Description |
|---|---|
title | The article title. |
status_name | The article's lifecycle status name. |
category | The knowledge-base category the article was listed under. An article filed under several categories carries one of them. Present for kb_module only. |
url | The article's public URL, from article_url_template or the listing. Absent when neither provides one. |
created_time | The article's created time, as reported by Wolken. |
updated_time | The article's last-updated time, as reported by Wolken. |
user_metadata carries the article's audience attributes for attribute-based
filtering, populated only when present in the response: article_number,
status_name, level_name, article_type, review_date, category_names,
software_release, validation_status, published_date, support_product,
and support_product_id. status_name is emitted in both buckets: in
system_metadata as the article's lifecycle status, and here as a filterable
audience attribute.
acl_metadata reports org_wide_access as READER. Wolken articles carry no
per-principal grants — access is audience-level and already enforced by the
listing filters, so the principal buckets of the source-independent
ACL metadata shape are left
null.
Incremental sync
When sync_mode is incremental (the default), the pipeline tracks a watermark
based on each article's last-updated time. See
Sync mode.
On the next run, only articles updated since the stored watermark are reprocessed. The next run's inclusive lower bound re-covers the boundary, and per-record deduplication absorbs the overlap.
With data_api, the watermark bounds are pushed into the listing's server-side
update-time filters. With kb_module, every article is listed each run and the
bounds are applied client side against the millisecond timestamps the listing
reports. An article whose listing carries no millisecond timestamp is included
in every run, and per-record deduplication decides whether it is reprocessed.
Deletes are not propagated. An article the connector can no longer retrieve (or that falls out of the configured filters) stops appearing in new runs. The pipeline emits no delete signal, so anything a previous run already produced downstream — for example, a document indexed into a corpus — is left in place.