Skip to main content

Sink configuration

sh.oso.servicenow.sink.ServiceNowSinkConnector

Property-by-property reference generated from the connector's ConfigDef, so it always matches the release you are running. Usage guide: Sink Connector.

Select input with the standard framework properties topics or topics.regex. For a dead letter queue use errors.tolerance=all with errors.deadletterqueue.topic.name. The shared snow.* connection, authentication, HTTP, TLS and retry properties are the same as the source connector's.

High importance​

snow.sink.routing.mode​

How the target table is chosen: fixed (snow.sink.table for every record), topic_map (snow.sink.topic.<topic>.table per input topic) or header (the record header named by snow.sink.table.header, validated against snow.sink.table.allowlist).

  • Type: string
  • Default: fixed
  • Valid values: [fixed, topic_map, header]
  • Importance: high

snow.sink.table​

Target table for fixed routing, for example incident.

  • Type: string
  • Default: null
  • Valid values: a table name matching ^[a-z0-9_]+$
  • Importance: high

snow.sink.operation.mode​

How the operation is chosen when no operation header is present: key_value (null value is DELETE, no sys_id is CREATE, otherwise snow.sink.update.method), header (the header is expected; see snow.sink.operation.header.required) or fixed (snow.sink.operation.fixed). A present operation header always wins.

  • Type: string
  • Default: key_value
  • Valid values: [key_value, header, fixed]
  • Importance: high

snow.url​

ServiceNow instance URL, for example https://acme.service-now.com. Only the scheme, host and port are used; the lower-cased host identifies the instance in source partitions.

  • Type: string
  • Default: none (required)
  • Valid values: non-empty string
  • Importance: high

snow.auth.type​

Authentication flow: basic (username and password on every request) or oauth2 (bearer tokens from the instance token endpoint, see snow.oauth.grant.type).

  • Type: string
  • Default: basic
  • Valid values: [basic, oauth2]
  • Importance: high

snow.auth.username​

Integration user. Required for basic and for the OAuth password grant. The user must have its time zone set to UTC.

  • Type: string
  • Default: null
  • Importance: high

snow.auth.password​

Password for snow.auth.username. Required for basic and for the OAuth password grant.

  • Type: password
  • Default: null
  • Importance: high

Medium importance​

snow.sink.table.allowlist​

Tables a record header may select under header routing. Required in that mode: table names become URL path segments, so records never choose a table that is not listed here.

  • Type: list
  • Default: "" (empty)
  • Valid values: table names matching ^[a-z0-9_]+$
  • Importance: medium

snow.sink.operation.fixed​

Operation for every record under snow.sink.operation.mode=fixed.

  • Type: string
  • Default: null
  • Valid values: [create, patch, put, delete]
  • Importance: medium

snow.sink.update.method​

HTTP method for updates: PATCH sends only the mapped fields and leaves the rest untouched; PUT asks the instance to replace the record. PATCH is the default because Kafka payloads are often partial.

  • Type: string
  • Default: PATCH
  • Valid values: [PATCH, PUT]
  • Importance: medium

snow.sink.null.behavior​

Null field values: omit them from the body (a PATCH leaves the field untouched), clear the field by sending an empty string, or reject the record.

  • Type: string
  • Default: omit
  • Valid values: [omit, clear, reject]
  • Importance: medium

snow.sink.unknown.field.behavior​

Fields missing from the target table's dictionary (sys_dictionary, cached): fail the record, drop them, report them to the error reporter while the rest of the record is written, or passthrough send them as is. Only passthrough avoids the dictionary lookup, which needs read access to sys_db_object and sys_dictionary.

  • Type: string
  • Default: fail
  • Valid values: [fail, drop, report, passthrough]
  • Importance: medium

snow.sink.nested.behavior​

Struct, Map or array field values: reject the record naming the field path, flatten nested keys with snow.sink.nested.flatten.delimiter, or stringify the value as a JSON string. Never silently stringified: ServiceNow would store an unrecognised object as a Java map string.

  • Type: string
  • Default: reject
  • Valid values: [reject, flatten, stringify]
  • Importance: medium

snow.sink.max.in.flight​

Kafka partitions written concurrently by one task; each partition is written in order, one request at a time. Keep it at or below snow.http.max.concurrent.requests.

  • Type: int
  • Default: 8
  • Valid values: [1,...]
  • Importance: medium

snow.sink.create.ambiguous.behavior​

A create whose response never arrived may or may not exist: retry re-sends the POST (a duplicate row is possible), fail_ambiguous fails the record with classification AMBIGUOUS, correlation_lookup queries snow.sink.correlation.field before every create and after an ambiguous one, then creates, patches the single match, or fails on two or more matches.

  • Type: string
  • Default: fail_ambiguous
  • Valid values: [retry, fail_ambiguous, correlation_lookup]
  • Importance: medium

snow.sink.correlation.field​

Field unique per business object, present in every create payload; required by snow.sink.create.ambiguous.behavior=correlation_lookup.

  • Type: string
  • Default: null
  • Importance: medium

snow.sink.not.found.behavior​

A 404 on PATCH, PUT or DELETE: fail the record (classification NOT_FOUND), ignore it, or create the row with the same sys_id (updates only; a missing row on DELETE is ignored).

  • Type: string
  • Default: fail
  • Valid values: [fail, ignore, create]
  • Importance: medium

behavior.on.api.errors​

After a permanent record failure has been offered to the dead letter queue and the error reporter: fail the task, log the failure and continue, or ignore it and continue. Retryable failures never take this path; they re-deliver the batch.

  • Type: string
  • Default: fail
  • Valid values: [fail, log, ignore]
  • Importance: medium

snow.sink.reporter.bootstrap.servers​

Kafka bootstrap servers for the reporter producer. Required when a reporter topic is set; a task cannot see the worker's own bootstrap servers.

  • Type: string
  • Default: null
  • Importance: medium

snow.oauth.grant.type​

OAuth 2.0 grant when snow.auth.type=oauth2: client_credentials (needs the instance property glide.oauth.inbound.client.credential.grant_type.enabled and an application user) or password (resource owner password, reusing snow.auth.username and snow.auth.password).

  • Type: string
  • Default: client_credentials
  • Valid values: [client_credentials, password]
  • Importance: medium

snow.oauth.client.id​

OAuth application registry client id. Required when snow.auth.type=oauth2.

  • Type: string
  • Default: null
  • Importance: medium

snow.oauth.client.secret​

OAuth application registry client secret. Required when snow.auth.type=oauth2.

  • Type: password
  • Default: null
  • Importance: medium

snow.http.max.concurrent.requests​

Maximum requests in flight to this instance from this worker JVM, shared by every connector that targets the same instance.

  • Type: int
  • Default: 8
  • Valid values: [1,...]
  • Importance: medium

snow.retry.max.attempts​

Total attempts per request for retryable failures (429, 408, 425, 5xx, transient I/O) before the failure surfaces to the task as retriable.

  • Type: int
  • Default: 5
  • Valid values: [1,...]
  • Importance: medium

snow.retry.max.elapsed.ms​

Retrying stops once the next wait would take the request past this many milliseconds in total.

  • Type: long
  • Default: 300000
  • Valid values: [0,...]
  • Importance: medium

Low importance​

snow.sink.table.header​

Record header carrying the target table name under header routing.

  • Type: string
  • Default: snow.table
  • Valid values: non-empty string
  • Importance: low

snow.sink.operation.header​

Record header carrying the operation: CREATE or POST, PATCH, PUT, UPDATE (the configured update method), DELETE, or UPSERT (update when a sys_id is present, otherwise create). Case-insensitive. The source connector writes snow.source.operation, a different header, so replaying a source topic never issues commands by accident.

  • Type: string
  • Default: snow.operation
  • Valid values: non-empty string
  • Importance: low

snow.sink.operation.header.required​

Under snow.sink.operation.mode=header, fail the record when the header is absent instead of falling back to key/value inference.

  • Type: boolean
  • Default: false
  • Importance: low

snow.sink.sys.id.key.field​

Field of a Struct or Map record key holding the sys_id. A String key is the sys_id itself.

  • Type: string
  • Default: sys_id
  • Valid values: non-empty string
  • Importance: low

snow.sink.sys.id.value.field​

Field of the record value holding the sys_id.

  • Type: string
  • Default: sys_id
  • Valid values: non-empty string
  • Importance: low

snow.sink.sys.id.precedence​

When the key, the value and the snow.sys_id header carry different sys_ids: reject the record, or let the key or the value win.

  • Type: string
  • Default: reject
  • Valid values: [reject, key, value]
  • Importance: low

snow.sink.nested.flatten.delimiter​

Joins nested keys under snow.sink.nested.behavior=flatten, so location.city becomes location_city.

  • Type: string
  • Default: _
  • Valid values: non-empty string
  • Importance: low

snow.sink.field.rename​

Top-level field renames as from:to pairs, applied before the allow and deny lists.

  • Type: list
  • Default: "" (empty)
  • Valid values: from:to pairs
  • Importance: low

snow.sink.field.allowlist​

When set, only these top-level fields (after renames) are written. Naming a reserved field such as sys_id here keeps it in the body.

  • Type: list
  • Default: "" (empty)
  • Importance: low

snow.sink.field.denylist​

Top-level fields (after renames) never written. Cannot be combined with the allowlist.

  • Type: list
  • Default: "" (empty)
  • Importance: low

snow.sink.reporter.success.topic​

Topic receiving a JSON report for every successful write; empty disables it.

  • Type: string
  • Default: null
  • Importance: low

snow.sink.reporter.error.topic​

Topic receiving a JSON report for every failed write; empty disables it.

  • Type: string
  • Default: null
  • Importance: low

snow.sink.reporter.include.request.body​

Include the request body in reports. Off by default because bodies can carry personal data.

  • Type: boolean
  • Default: false
  • Importance: low

snow.oauth.token.url​

Token endpoint override. Defaults to {snow.url}/oauth_token.do.

  • Type: string
  • Default: null
  • Importance: low

snow.oauth.scope​

Optional OAuth scope sent with the token request.

  • Type: string
  • Default: null
  • Importance: low

snow.http.connect.timeout.ms​

TCP connect timeout in milliseconds.

  • Type: int
  • Default: 10000
  • Valid values: [1,...]
  • Importance: low

snow.http.request.timeout.ms​

Per-request timeout in milliseconds (time to response headers). Also bounds the wait for a concurrency permit.

  • Type: int
  • Default: 60000
  • Valid values: [1,...]
  • Importance: low

snow.http.proxy.url​

HTTP proxy, for example http://proxy.internal:3128.

  • Type: string
  • Default: null
  • Importance: low

snow.http.proxy.username​

Proxy username, when the proxy requires authentication.

  • Type: string
  • Default: null
  • Importance: low

snow.http.proxy.password​

Proxy password.

  • Type: password
  • Default: null
  • Importance: low

snow.http.max.response.bytes​

Responses larger than this many bytes (after decompression) fail the request.

  • Type: long
  • Default: 67108864
  • Valid values: [1024,...]
  • Importance: low

snow.http.user.agent​

User-Agent header sent with every request.

  • Type: string
  • Default: kafka-connect-servicenow/<version>
  • Importance: low

snow.http.adaptive.throttling​

Halve the in-flight limit when the instance answers 429 and recover one permit per 50 successful requests, never above snow.http.max.concurrent.requests.

  • Type: boolean
  • Default: true
  • Importance: low

snow.tls.truststore.path​

Truststore file for the instance certificate chain, when the JDK defaults are not enough.

  • Type: string
  • Default: null
  • Importance: low

snow.tls.truststore.password​

Truststore password.

  • Type: password
  • Default: null
  • Importance: low

snow.tls.truststore.type​

Truststore type (JKS or PKCS12).

  • Type: string
  • Default: JKS
  • Importance: low

snow.tls.keystore.path​

Keystore holding the client certificate for mutual TLS.

  • Type: string
  • Default: null
  • Importance: low

snow.tls.keystore.password​

Keystore password.

  • Type: password
  • Default: null
  • Importance: low

snow.tls.keystore.type​

Keystore type (JKS or PKCS12).

  • Type: string
  • Default: JKS
  • Importance: low

snow.retry.initial.backoff.ms​

Ceiling of the first full-jitter backoff in milliseconds; doubles per attempt.

  • Type: long
  • Default: 500
  • Valid values: [0,...]
  • Importance: low

snow.retry.max.backoff.ms​

Largest backoff ceiling in milliseconds. A Retry-After header overrides the backoff.

  • Type: long
  • Default: 30000
  • Valid values: [0,...]
  • Importance: low

Per-topic routing (snow.sink.topic.<topic>.table)​

Under snow.sink.routing.mode=topic_map each input topic is mapped to its target table with one key per topic, with <topic> replaced by the Kafka topic name (for example snow.sink.topic.incident-updates.table).

snow.sink.topic.<topic>.table​

Target table for records from this topic under snow.sink.routing.mode=topic_map.

  • Type: string
  • Default: null
  • Valid values: a table name matching ^[a-z0-9_]+$
  • Importance: high