Custom Module

The Custom Module pauses a Workflow and hands control to your application, which runs custom logic and returns a result that determines how the Workflow continues. The SDK hands your app a callbackName, then resumes the Workflow at the next node once you report a result. It exists only inside Dashboard-defined Workflows, not in locally built flows.

For an overview of this module and how it works, see Custom Module.

Availability: Workflows API only (Dashboard-defined Workflows); not available via a local IncdOnboardingFlowConfiguration.

Add Custom Module

Because the Custom Module lives on a Workflow node, there is no flowConfig.addXxx(...) builder for it. You configure it in Dashboard and start the session against the Workflow.

1. In Dashboard, add a Custom Module node to your Workflow and set its callbackName. This is just a string the SDK delivers to your app. On iOS, there is no automatic function invocation. Your app decides how to interpret the value: for example, by mapping it to a method or branching on it.
2. Activate the Workflow and note its ID.
3. In your app, start the session against that Workflow. Set the Workflow ID via configurationId, which is one of the optional named parameters of the single IncdOnboardingSessionConfiguration initializer. Then call IncdOnboardingManager.shared.startFlow(sessionConfig:delegate:moduleId:). moduleId is optional and defaults to nil.
4. Handle the module by overriding onCustomModuleStarted(callbackName:onCustomModuleCompleted:) on your IncdOnboardingDelegate. If you don't override it, the default implementation reports .unknown, and your custom logic never runs. Always provide an implementation that calls the onCustomModuleCompleted completion handler.

Example

The example below starts a session with a configurationId, overrides onCustomModuleStarted to run custom logic based on callbackName, and reports the result through the onCustomModuleCompleted completion handler.

let session = IncdOnboardingSessionConfiguration(
    configurationId: "<WORKFLOW_ID>",
    token: "<SESSION_TOKEN>"
)
IncdOnboardingManager.shared.startFlow(sessionConfig: session, delegate: self)

extension MyViewController: IncdOnboardingDelegate {
    func onCustomModuleStarted(
        callbackName: String,
        onCustomModuleCompleted: @escaping (CustomModuleStatus) -> Void
    ) {
        // Run your custom logic based on callbackName, then report a result.
        let status = runCustomLogic(for: callbackName)
        onCustomModuleCompleted(status)
    }
}

Configuration Options

Custom Module has no client-side builder options. Its only setting, the callbackName, is configured on the Custom Module node in the Workflow in Dashboard. The SDK delivers that name to your app at runtime through the delegate callback.

For startFlow(sessionConfig:delegate:moduleId:), see API Reference.

Result

There is no result payload object. The module signals through the onCustomModuleStarted(callbackName:onCustomModuleCompleted:) callback on your IncdOnboardingDelegate. You then call the onCustomModuleCompleted completion handler with a CustomModuleStatus to report the outcome of your custom logic. Once you report a status, the SDK submits it and advances the Workflow to the next node.

CustomModuleStatus is an enum with the following values:

• ok ("OK")
• fail ("FAIL")
• warn ("WARN")
• unknown ("UNKNOWN")

When the module finishes, the SDK also invokes onCustomModuleCompleted(_ result: IncdError?) on the delegate: result is nil on success or carries an IncdError. There is no module-specific error type for Custom Module; generic failures surface through onError(_ error: IncdFlowError) on your IncdOnboardingDelegate.