Integration

Polymorphic external service integration. Uses @JsonTypeInfo for JSON serialization discriminator. Subtypes cover authentication, CRM, KB, livechat, LLM, ticketing, and translation providers. Collection: integrations | DB: MongoDB Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/Integration.kt TypeScript: hbf-core-api/src/datamodel/integration.ts, hbf-core-api/src/datamodel/plugin.ts

Base Fields (all subtypes inherit these)

Field	Type	Required	Indexed	Notes
id	String	yes	PK	@Null on create (auto-generated)
name	String	yes		@NotNull on create
enabled	Boolean	no
description	String	no
type	IntegrationType	yes		@JsonTypeInfo discriminator
tags	List<String>	no
organization	Organization	yes		@DBRef lazy, @JsonIgnore
organizationRef	String	no		@Transient, @WriteOnly
category	IntegrationCategory	yes		@NotNull on create
createdAt	Date	yes		@CreatedDate
updatedAt	Date	yes		@LastModifiedDate

Subtypes

OIDCIntegration (type: OIDC_AUTHENTICATION, category: AUTHENTICATION)

Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/OIDCIntegration.kt

Field	Type	Notes
configurationUrl	String	OIDC discovery URL
issuer	String	@NotNull on create
authorizationEndpoint	String	@NotNull on create
tokenEndpoint	String	@NotNull on create
jwksUri	String	@NotNull on create
grantType	GrantType	@NotNull on create. AUTHORIZATION_CODE or AUTHORIZATION_CODE_PKCE
clientId	String	@NotNull on create
clientSecret	String	@WriteOnly
challengeMethod	ChallengeMethod	Default: SHA_256. SHA_256 or PLAIN
additionalScopes	String
emailKey	String	@PrivateProperty, claim key for email extraction
fullNameKey	String	@PrivateProperty, claim key for full name extraction

MicrosoftDynamicsCrmIntegration (type: MICROSOFT_DYNAMICS_CRM, category: CRM)

Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/MicrosoftDynamicsIntegration.kt

Extends abstract MicrosoftDynamicsIntegration.

Field	Type	Notes
baseUrl	String	Dynamics 365 base URL
clientId	String
clientSecret	String
azureTenantId	String
scope	String
version	String
entityProperties	Set<MicrosoftDynamicsEntityProperty>	Field mappings
filterExpression	String	OData filter expression
filterProperty	FilterProperty	Links CRM property to subscriber property
contactLinkTemplate	String	URL template for CRM contact

MicrosoftDynamicsKbIntegration (type: MICROSOFT_DYNAMICS_KB, category: KB)

Source: same as CRM above.

Same fields as the CRM variant minus filterProperty and contactLinkTemplate.

AzureBlobStorageKbIntegration (type: AZURE_BLOB_STORAGE_KB, category: KB)

Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/AzureBlobStorageKbIntegration.kt TypeScript: hbf-core-api/src/datamodel/integration.ts (not yet present — gap, needed by hbf-knowledge-manager)

Extends abstract WebhookIntegration (adds webhookKey).

Field	Type	Notes
webhookKey	String	Inherited from WebhookIntegration. Format: <accountName_lower>/<containerName_lower>. Used to index integrations for webhook routing
accountName	String	Azure Storage account name
containerName	String	Azure Blob container name
sasToken	String	SAS token for container access
pathPrefix	String	Optional blob path prefix filter. Only blobs under this prefix are synced
allowedContentTypes	List<String>	Optional MIME type allowlist. If empty, all types are accepted
organizationId	String	@Transient. Populated at query time from the owning Organization

CiscoLivechatIntegration (type: CISCO_LIVECHAT, category: LIVECHAT)

Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/CiscoLivechatIntegration.kt

Field	Type	Notes
endpoint	String	@NotNull on create
chatId	Long	@NotNull on create
ccxQueueTag	String	@NotNull on create
clientId	String
clientSecret	String

HelviaLivechatIntegration (type: HELVIA_LIVECHAT, category: LIVECHAT)

Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/Integration.kt

No additional fields beyond the base Integration.

ZendeskLivechatIntegration (type: ZENDESK_LIVECHAT, category: LIVECHAT)

Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/ZendeskLivechatIntegration.kt

Field	Type	Notes
baseUrl	String	@NotNull on create. Without /sc suffix
appId	String	@NotNull on create
keyId	String	@NotNull on create
secret	String	@NotNull on create
webhookId	String	@NotNull on create
webhookKey	String	@NotNull on create

GenesysLivechatIntegration (type: GENESYS_LIVECHAT, category: LIVECHAT)

Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/GenesysLivechatIntegration.kt

Extends abstract WebhookIntegration (adds webhookKey).

Field	Type	Notes
webhookKey	String	Inherited from WebhookIntegration. @NotNull on create
clientId	String	@NotNull on create
clientSecret	String	@NotNull on create
region	String	@NotNull on create. Genesys domain, e.g. "mypurecloud.ie"
openIntegrationId	String	@NotNull on create
queueIds	Set<String>	Subscribed queue IDs

OpenAIIntegration (type: OPEN_AI_LLM, category: LLM)

Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/OpenAIIntegration.kt

Field	Type	Notes
apiKey	String	@NotNull on create
project	String
openAIOrganization	String
customUrl	String

AzureAIIntegration (type: AZURE_AI_LLM, category: LLM)

Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/AzureAIIntegration.kt

Field	Type	Notes
endpoint	String	@NotNull on create
deploymentName	String	Deprecated
apiVersion	String	Deprecated
apiKey	String	@NotNull on create

GeminiAIIntegration (type: GEMINI_AI_LLM, category: LLM)

Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/GeminiAIIntegration.kt

Field	Type	Notes
apiKey	String	@NotNull

ZendeskTicketingIntegration (type: ZENDESK_TICKETING, category: TICKETING)

Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/ZendeskTicketingIntegration.kt

Field	Type	Notes
baseUrl	String	@NotNull on create
userName	String	@NotNull on create
token	String	@NotNull on create, @WriteOnly

GoogleTranslationIntegration (type: GOOGLE_TRANSLATION, category: TRANSLATION)

Source: hbf-core/src/main/java/gr/helvia/hbf/core/domain/GoogleTranslationIntegration.kt

Field	Type	Notes
apiKey	String	@NotNull on create

Abstract Intermediate Classes

WebhookIntegration (abstract, extends Integration)

Field	Type	Notes
webhookKey	String	@NotNull on create. Webhook validation key

Used by: GenesysLivechatIntegration, AzureBlobStorageKbIntegration

MicrosoftDynamicsIntegration (abstract, extends Integration)

Field	Type	Notes
baseUrl	String
clientId	String
clientSecret	String
azureTenantId	String
scope	String
version	String
entityProperties	Set<MicrosoftDynamicsEntityProperty>
filterExpression	String

Used by: MicrosoftDynamicsCrmIntegration, MicrosoftDynamicsKbIntegration

Supporting Types

MicrosoftDynamicsEntityProperty

Field	Type	Notes
dataPropertyPath	String	CRM OData property path
domainPropertyName	String	Subscriber property name
displayName	String	Friendly name
type	EntityPropertyType	TEXT, NUMBER, CHOICE, LOOKUP, DATETIME
value	Any	Populated from CRM response

FilterProperty

Field	Type	Notes
dataPropertyName	String	CRM property name
subscriberPropertyName	String	Subscriber property name

Enums

IntegrationType

Value	Category	Description
OIDC_AUTHENTICATION	AUTHENTICATION	OpenID Connect SSO
MICROSOFT_DYNAMICS_CRM	CRM	MS Dynamics 365 CRM
MICROSOFT_DYNAMICS_KB	KB	MS Dynamics knowledge base
AZURE_BLOB_STORAGE_KB	KB	Azure Blob Storage file-based knowledge base
CISCO_LIVECHAT	LIVECHAT	Cisco CCX live chat
HELVIA_LIVECHAT	LIVECHAT	Built-in Helvia live chat
ZENDESK_LIVECHAT	LIVECHAT	Zendesk Sunshine live chat
GENESYS_LIVECHAT	LIVECHAT	Genesys Cloud live chat
AZURE_AI_LLM	LLM	Azure AI (OpenAI on Azure)
OPEN_AI_LLM	LLM	OpenAI API
GEMINI_AI_LLM	LLM	Google Gemini
ZENDESK_TICKETING	TICKETING	Zendesk ticketing
GOOGLE_TRANSLATION	TRANSLATION	Google Cloud Translation

IntegrationCategory

Value	Description
AUTHENTICATION	SSO/auth providers
CRM	Customer relationship management
KB	External knowledge base
LIVECHAT	Live chat providers
LLM	Large language model providers
TICKETING	Ticketing systems
TRANSLATION	Translation services

GrantType (OIDC)

Value
AUTHORIZATION_CODE
AUTHORIZATION_CODE_PKCE

ChallengeMethod (OIDC)

Value
SHA_256
PLAIN

EntityPropertyType (MS Dynamics)

Value
TEXT
NUMBER
CHOICE
LOOKUP
DATETIME

Relationships

• Belongs to: Organization (via @DBRef)
• Referenced by: Tenant (via integrations list and plugin settings)
• Referenced by: LoginSettings (for auth integrations)
• Referenced by: KnowledgeBase (for integration-type KBs)

TypeScript Mapping

hbf-core (Kotlin)	hbf-core-api (TypeScript)	Notes
Integration	Integration	TS base omits organization, organizationRef, tags, enabled, createdAt, updatedAt
IntegrationType	IntegrationType	TS uses OPENID_AUTHENTICATION vs Kotlin's OIDC_AUTHENTICATION
IntegrationCategory	IntegrationCategory	TS omits TRANSLATION
OIDCIntegration	OIDCIntegration	Aligned
OpenAIIntegration	OpenAIIntegration	Aligned
AzureAIIntegration	AzureAIIntegration	Aligned
GeminiAIIntegration	GeminiAIIntegration	Aligned
CiscoLivechatIntegration	CiscoLivechatIntegration	In plugin.ts
ZendeskLivechatIntegration	ZendeskSunshineLivechatIntegration	Different naming
GenesysLivechatIntegration	GenesysLivechatIntegration	In plugin.ts
ZendeskTicketingIntegration	(not in TS)	Gap
GoogleTranslationIntegration	(not in TS)	Gap
MicrosoftDynamicsCrmIntegration	(not in TS)	Gap
MicrosoftDynamicsKbIntegration	(not in TS)	Gap
AzureBlobStorageKbIntegration	(not in TS)	Gap — needed by hbf-knowledge-manager. AZURE_BLOB_STORAGE_KB also missing from IntegrationType enum in hbf-core-api