Documentation

# HubSpot plugin

Integrates HubSpot (opens new window) CRM with the Epona provisioning service. The plugin polls HubSpot on a schedule, reads changed records, and writes client/matter JSON files that the provisioning service picks up and processes.

DLL: Epona.HubSpot.dll

# What it does

  • Matter sync — fetches recently changed records from HubSpot (companies, deals, services, or leads) and creates or updates matter records in SharePoint.
  • Company lookup — resolves the linked company for each record and exposes its fields under a company. prefix for field mapping.
  • Owner lookup — resolves the HubSpot owner (hubspot_owner_id) and exposes their fields under a responsible. prefix.
  • Batch loading — when Load Matter Associated Company is set, companies are fetched in bulk via the HubSpot Associations API to avoid per-record API calls.
  • Post handler — optionally writes the SharePoint matter URL back to a HubSpot property after a matter is created.

# Deployment

  1. Copy Epona.HubSpot.dll to the service's bin directory.
  2. Restart the provisioning service.
  3. Open the Configurator, select the relevant SharepointCfg, and configure the HubSpot section that now appears in the property grid.

# Configuration reference

# Connection

# Url

Type: string | Default: https://api.hubapi.com/

Base URL of the HubSpot API. Change only when using a non-standard environment.

# Access Token

C#: AccessToken | Configurator: "Access Token"

Type: string (encrypted)

HubSpot private app access token. Stored encrypted. Managed via the Secrets manager.

# Schedule

# HubSpot Schedule

C#: IntervalScheduleCfg | Configurator: "HubSpot Schedule"

Type: IntervalScheduleCfg

Controls when and how often the sync job runs. Expand in the Configurator to set Enabled, IntervalInMinutes, StartTime, and EndTime.

# Connection — matters endpoint

# Matters Endpoint

C#: MattersEndpoint | Configurator: "Matters Endpoint"

Type: enum | Default: Companies

Determines which HubSpot object type to use as matters. Valid values:

Value HubSpot object CRM API path
Companies Standard companies crm/v3/objects/companies
Deals Standard deals crm/v3/objects/deals
Services Custom object crm/v3/objects/{CustomObjectTypeId}
Leads Standard leads crm/v3/objects/leads

# Custom Object Type Id

C#: CustomObjectTypeId | Configurator: "Custom Object Type Id"

Type: string | Default: 0-162

HubSpot type ID for the custom object used when Matters Endpoint is Services. The ID may differ between HubSpot environments — verify it in your HubSpot portal under Settings > Objects > Custom Objects.

# Load Matter Associated Company

C#: LoadMatterAssociatedCompany | Configurator: "Load Matter Associated Company"

Type: string | Default: (empty)

Set to 0-2 to batch-fetch the company linked to each matter via the HubSpot Associations API. Leave empty to skip.

Use this when Matters Endpoint is Services or Leads, because those object types do not carry the company ID as a direct property. When enabled, the plugin makes one batch API call per sync run (up to 1 000 matter IDs per request) to resolve all associations, then fetches the referenced companies in bulk. The company's properties are exposed via the company. prefix in all field mapping configuration.

When Matters Endpoint is Companies or Deals, the company ID is read from the Client Id property instead, and this setting is typically not needed.

# Client Id

C#: ClientId | Configurator: "Client Id"

Type: string | Default: hs_primary_associated_company

HubSpot property that holds the linked company ID. Used when Load Matter Associated Company is empty and the company ID is available as a direct field on the matter record (typical for Deals).

# Client

# Client Code

C#: ClientCode | Configurator: "Client Code"

Type: string

Field expression that resolves to the SharePoint client code. Supports field names, company. prefix, responsible. prefix, literal strings ("value"), and dynamic templates ({field}). See Field mapping expressions.

# Default Client Code

C#: DefaultClientCode | Configurator: "Default Client Code"

Type: string

Fallback client code used when the expression in Client Code resolves to an empty value.

# Client Name

C#: ClientName | Configurator: "Client Name"

Type: string

Field expression that resolves to the SharePoint client name. Supports the same syntax as Client Code.

# Default Client Name

C#: DefaultClientName | Configurator: "Default Client Name"

Type: string

Fallback client name used when the expression in Client Name resolves to an empty value.

# Client Field Mapping

C#: ClientFieldMapping | Configurator: "Client Field Mapping"

Type: string

Maps HubSpot fields to SharePoint client fields. Syntax: SharePointField=hubspotField;Field2=hubspotField2. Supports field expressions on the right-hand side.

# Matter

# Matter Code

C#: MatterCode | Configurator: "Matter Code"

Type: string

Field expression that resolves to the SharePoint matter code.

# Matter Name

C#: MatterName | Configurator: "Matter Name"

Type: string

Field expression that resolves to the SharePoint matter name.

# Matter Field Mapping

C#: MatterFieldMapping | Configurator: "Matter Field Mapping"

Type: string

Maps HubSpot fields to SharePoint matter fields. Same syntax as Client Field Mapping.

# Filter

# Matter Filter

C#: MatterFilter | Configurator: "Matter Filter"

Type: string

One or more filters in the format field=value;field2=value2. Records that do not match all filters are skipped before export. Supports multiple lines.

# Post handler — update HubSpot

After a matter is created in SharePoint, the post handler can write the matter URL back to a HubSpot property.

# Enable Post Handler

C#: EnablePostHandler | Configurator: "Enable Post Handler"

Type: boolean | Default: false

Set to true to enable writing the SharePoint matter URL back to HubSpot after matter creation.

# Matter Id

C#: MatterId | Configurator: "Matter Id"

Type: string | Default: id

HubSpot property that holds the record ID. Used to identify which HubSpot record to update.

# Matter URL Property

C#: MatterUrlProperty | Configurator: "Matter URL Property"

Type: string

HubSpot property name that receives the SharePoint matter URL. Example: eponadmsurl.

# Debugging

# Test Mapping

C#: TestMapping | Configurator: "Test Mapping"

Type: boolean | Default: false

When enabled:

  • Exports JSON to ./Monitor/{name}/Test/ instead of the live monitor directory.
  • Does not update the last-run timestamp, so the same records are fetched again on the next run.
  • Adds raw HubSpot field values to the exported JSON under __TEST_{fieldName} keys (matter fields), __TEST_hubspotowner_{fieldName} keys (owner fields), and client properties under __TEST_{fieldName} (company fields).

Use this to inspect the raw data and verify field mapping without affecting the production state.

# Field mapping expressions

All field mapping properties (ClientCode, ClientName, MatterCode, MatterName, and the FieldMapping columns) accept the following expression forms on the right-hand side:

Form Example Description
Direct field name dealname Value of the named HubSpot property on the matter object
Company prefix company.name Property from the linked company (requires company lookup)
Owner prefix responsible.hs_email Property from the HubSpot owner resolved via hubspot_owner_id
Literal string "General" Fixed literal value (include the double quotes)
Dynamic template {company.name} / General Interpolated string combining fields and literals
Pipe fallback dealname\|hs_object_id Uses the first non-empty value from left to right

Dynamic templates and DynamicFieldValueMapping (configured in the global settings) interact — a resolved value may itself be re-evaluated as a template.

# Example configurations

# Companies as matters

Matters Endpoint    = Companies
Client Code         = company_number
Client Name         = name
Matter Code         = "General"
Matter Name         = {name} / General
Matter Field Mapping = MatterStage=lifecyclestage;ResponsibleEmail=responsible.hs_email

# Deals as matters

Companies linked to deals are resolved via the hs_primary_associated_company field (set in Client Id). Company properties are then available under the company. prefix.

Matters Endpoint    = Deals
Client Id           = hs_primary_associated_company
Client Code         = company.company_number
Client Name         = company.name
Matter Code         = "General"
Matter Name         = {company.name} / General
Matter Field Mapping = MatterType=dealtype;Responsible=responsible.hs_email
Matter URL Property = dmsLink
Enable Post Handler = true

# Services (custom objects) as matters

Custom objects do not carry a direct company property — use Load Matter Associated Company to resolve linked companies via the Associations API.

Matters Endpoint              = Services
Custom Object Type Id         = 0-162
Load Matter Associated Company = 0-2
Client Id                     = hs_primary_associated_company
Client Code                   = company.company_number
Client Name                   = company.name
Matter Code                   = hs_object_id
Matter Name                   = hs_object_id

# Leads as matters

Leads use the same association-based company lookup as services.

Matters Endpoint              = Leads
Load Matter Associated Company = 0-2
Client Code                   = company.company_number
Client Name                   = company.name
Matter Code                   = hs_object_id
Matter Name                   = {company.name} / General
Last Updated: 5/11/2026, 2:44:29 PM