Custom SaaS Connector: Delta Aggregation not being triggered in ISC tenant

SailPoint Human Fabric (SHF) SHF Discussion and Questions
, , , ,
1

:bangbang: Please be sure you’ve read the docs and API specs before asking for help. Also, please be sure you’ve searched the forum for your answer before you create a new topic.

Custom SaaS Connector: Delta Aggregation not being triggered in ISC tenant

Hi everyone,

I’m developing a custom SaaS Connector and I’m trying to implement Delta Aggregation for accounts and entitlements.

I followed the SailPoint documentation for the account-list command and the Delta Aggregation State implementation:

I also used the following discussion as a reference:

My connector has supportsStatefulCommands enabled:

"supportsStatefulCommands": true

I also added the spConnEnableDeltaAggregation configuration:

{
  "key": "spConnEnableDeltaAggregation",
  "label": "Enable Delta Aggregation",
  "type": "checkbox",
  "required": true,
  "helpKey": "When enabled, the connector honors ISC's `stateful` flag and returns only records changed since the last successful aggregation. The full aggregation path is preserved as a fallback when no state is present."
}

My stdAccountList implementation is currently:

.stdAccountList(async (_context, input, res) => {
  logger.info({ input }, 'Running outsourced employee list')

  const isDelta = shouldUseDeltaAggregation(config, input)
  const since = isDelta ? resolveStateDate(input) : undefined

  logger.info(
    { since, stateful: isDelta, mode: isDelta ? 'delta' : 'full' },
    isDelta
      ? 'Delta aggregation enabled — fetching outsourced employees updated since last run'
      : 'Running full aggregation (current behavior)'
  )

  for await (const outsourcedEmployee of outsourcedEmployeeClient.stdOutsourcedEmployeelist(
    since
  )) {
    res.send(outsourcedEmployee)
  }

  res.saveState(buildSaveState())
})

The function that determines whether the aggregation should run in delta mode is:

function shouldUseDeltaAggregation(
  config: ConfigSchemaProps,
  input: {
    stateful?: boolean
    state?: {
      lastRun?: string
      previousLastRun?: string
    }
  }
): boolean {
  return (
    config.spConnEnableDeltaAggregation === true &&
    input?.stateful !== undefined &&
    input?.stateful === true &&
    input?.state != undefined
  )
}

Current behavior

When I test the connector locally using Postman, I can successfully trigger the stateful request and the connector correctly enters the delta path.

However, when the connector is deployed to an ISC tenant and I run an account aggregation, the connector does not appear to receive the request with stateful: true. As a result, the connector always executes the full aggregation path.

My main question is:

What is the correct way to configure and implement Delta Aggregation for a custom SaaS Connector so that ISC actually triggers the stateful/delta aggregation during a real account aggregation?

More specifically:

  1. Is there any additional configuration required in ISC to enable Delta Aggregation for a custom SaaS Connector?

  2. How does ISC determine when to send stateful: true to the stdAccountList command?

  3. Does the account source need to be configured in a specific way for Delta Aggregation to be triggered?

  4. Is res.saveState() sufficient to persist the state between aggregation executions, or is there anything else that needs to be implemented?

  5. Is there a specific aggregation type or option in ISC that needs to be selected to execute a Delta Aggregation?

  6. Is Delta Aggregation supported automatically for custom SaaS Connectors, or does it require additional configuration on the connector/source side?

  7. How should the state be handled when the connector needs to aggregate both accounts and entitlements?

The important point is that the delta implementation works correctly when I manually send the expected stateful request locally, but I cannot get ISC to trigger this behavior in the tenant.

Any guidance on the correct ISC configuration or expected flow for triggering Delta Aggregation would be greatly appreciated.Please consider addressing the following when creating your topic:

  • What have you tried?
  • What errors did you face (share screenshots)?
  • Share the details of your efforts (code / search query, workflow json etc.)?
  • What is the result you are getting and what were you expecting?
2

Hi @GabrielBorgesLabs, welcome to the community!

I think the main thing to check is the source configuration key. For a custom SaaS connector, the key should be “spConnEnableStatefulCommands”, not “spConnEnableDeltaAggregation”.

Your connector spec is correct:

"supportsStatefulCommands": true

And the source configuration should contain:

{
  "key": "spConnEnableStatefulCommands",
  "label": "Stateful",
  "required": true,
  "type": "checkbox"
}

This is the configuration SailPoint documents for enabling stateful commands. Once enabled, ISC can send “stateful: true” and the previously saved state to “std:account:list”. The connector should call “res.saveState()” with a JSON object after processing the aggregation so that state is available for the next run.

I would change the configuration key first, enable the option on the source, run a successful aggregation, and then check the source “connectorAttributes” to confirm that “spConnEnableStatefulCommands” is “true” and that the state has been saved.