Wolken Forms
The Wolken Forms source ingests the end-user-facing service catalog of a Wolken ServiceDesk instance. Both incident forms and service request forms are ingested. Each form becomes one record in the pipeline, and its contents are uploaded to a new agent session for processing. Because each form is indexed as a document, an agent can recommend the right form from a user's stated intent through semantic search rather than by matching the form name.
Every form document carries the form title, its description, and its category. When detail ingestion is enabled, the document also carries the form's FAQs, its field definitions with their help text, and the values selectable on each of its dropdown and lookup fields.
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. These are the same credentials the Wolken knowledge-base source uses, and the same token flow applies.
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
The connector requires credentials with read access to the service catalog
listing. When include_form_details is enabled, the credentials additionally
require read access to the form metadata, special instructions, and lookup
value endpoints. Whether a deployment provisions those endpoints varies, so ask
your Wolken administrator which endpoints your deployment provisions before
enabling detail ingestion.
SOURCE FIELD (WOLKEN FORMS)
Code example with json syntax.1
Fields
| Field | Required | Description |
|---|---|---|
type | Yes | wolken_forms. |
base_url | Yes | Base URL of the Wolken API, for example 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. |
client_id | Yes | Wolken OAuth client ID. |
service_account | Yes | Wolken service account the API calls run as. Sent as a header on API requests. |
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. |
include_form_details | No | Whether to enrich each form with its detail content. When true, the pipeline fetches each form's FAQs, field definitions, field help text, and the values selectable on each of its dropdown and lookup fields. When false, documents are built from the catalog listing alone, which is faster and uses far fewer Wolken API calls. Defaults to true. |
item_url_template | No | Template for each form's portal URL. The {item_id} placeholder is replaced with the form's item ID. The end-user portal host differs from the API host, so use the portal host here. When omitted, records carry no URL. |
The portal URL takes the following form.
https://example-enduser.wolkenservicedesk.com/wolken-support/item_details?itemId={item_id}
How records are fetched
Each run enumerates the service catalog listing. Only forms that are visible to end users are ingested. Retired and inactive forms are excluded.
Each form that passes the visibility filter becomes one record. When
include_form_details is true, the connector then reads the form's field
definitions, FAQs, and per-field option values, and composes them with the
listing content into a single HTML document. When include_form_details is
false, the document is composed from the listing content alone.
Option values are ingested in full, because the option names are often what a search matches. A user who asks for a role, a site, or an application by name is naming a value inside a form's dropdown or lookup field rather than anything in the form's title. Treat the Wolken API as the source of truth when filling a form, since the values a field offers can depend on earlier selections.
In listing-only mode the catalog listing carries no form name, so the document title is derived from the form description.
Forms are enumerated with offset pagination. A form created or deleted in the catalog while a run is in flight shifts the position of later forms between pages, and a form can be skipped until its next edit or a full refresh. Retiring a form does not shift positions, because retired forms remain in the listing and are filtered out after the page is read.
A change to include_form_details or item_url_template is picked up on the
next run of the pipeline, including an incremental run. The connector includes
these settings in its change detection, so already-ingested forms are recomposed
under the new settings without a full refresh.
Source metadata
Each record carries source metadata that the connector resolves at fetch time.
system_metadata:
| Key | Description |
|---|---|
title | The form title. |
url | The form's portal URL, from item_url_template. Absent when no template is configured. |
user_metadata carries the form's catalog attributes for attribute-based
filtering:
| Key | Description |
|---|---|
item_id | The Wolken catalog item ID of the form. |
item_name | The Wolken catalog item name of the form. |
category_id | The ID of the catalog category the form is filed under. |
category_name | The name of the catalog category the form is filed under. |
sub_category_id | The ID of the catalog sub-category the form is filed under. |
sub_category_name | The name of the catalog sub-category the form is filed under. |
request_type | The kind of request the form raises, either incident or service_request. |
access_type | The catalog audience the form is published to. |
mandatory_field_count | The number of mandatory fields on the form. |
fillable | Whether the form can be completed in an agent session. false when a mandatory visible field of the form declares a dependency on another field's selection, which an agent cannot resolve without the live Wolken API. |
The item_name, request_type, mandatory_field_count, and fillable keys are
absent when include_form_details is false, because they are read from the
form detail endpoints rather than from the catalog listing.
acl_metadata reports org_wide_access as READER. Wolken catalog items carry
no per-principal grants. The audience is already restricted to end-user-facing
forms by the listing filter, so the principal buckets of the source-independent
ACL metadata shape are left
null.
Handing a form to a ticketing agent
The item_id, item_name, and request_type metadata of a form are the values
an agent passes to the Wolken ticketing tools when it files the request the form
represents. The corpus is a recommendation index rather than a record of the
form's current definition. Read the live Wolken API for the field definitions and
option values in force at the time the form is filled.
Incremental sync
When sync_mode is incremental, which is the default, the connector detects changed
forms by comparing form content between runs rather than by filtering on an
update time. The Wolken catalog API offers no update-time filter, so every form
is enumerated on every run and only forms whose content changed are reprocessed.
See Sync mode.
Item-level edits, such as a change to a form's name, description, or category,
are detected on every run. Edits confined to a form's FAQs, field help text, or
option lists may not be reflected in the catalog listing, and an incremental run
can therefore miss them. Run the pipeline in full_refresh mode to pick those
up. A full refresh re-reads every form's detail content, and forms whose
composed content is unchanged are still skipped, so a full refresh reprocesses
only what actually differs.
Deletes are not propagated. A form the connector can no longer retrieve, or that is retired or made invisible to end users, 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.