SDKS-3917 Journey Module Design and Prototype

Author: witrisna

external-idp/src/main/kotlin/com/pingidentity/idp/journey/IdpCallback.kt

@@ -40,7 +40,7 @@ class IdpCallback : AbstractCallback(), JourneyAware, RequestInterceptor {
 
     override lateinit var journey: Journey
 
-    override fun onAttribute(name: String, value: JsonElement) {
+    override fun init(name: String, value: JsonElement) {
         when (name) {
             "provider" -> this.provider = value.jsonPrimitive.content
             "clientId" -> this.clientId = value.jsonPrimitive.content
@@ -53,7 +53,7 @@ class IdpCallback : AbstractCallback(), JourneyAware, RequestInterceptor {
         }
     }
 
-    override fun asJson() = input(result.token, tokenType)
+    override fun payload() = input(result.token, tokenType)
 
     /**
      * Overrides the request with the resume request if initialized, else return the input request.

external-idp/src/main/kotlin/com/pingidentity/idp/journey/SelectIdpCallback.kt

@@ -25,7 +25,7 @@ class SelectIdpCallback : AbstractCallback() {
 
     var value: String= ""
 
-    override fun onAttribute(name: String, value: JsonElement) {
+    override fun init(name: String, value: JsonElement) {
         when (name) {
             "providers" -> {
                 providers = value.jsonArray.map {
@@ -35,7 +35,7 @@ class SelectIdpCallback : AbstractCallback() {
         }
     }
 
-    override fun asJson(): JsonObject {
+    override fun payload(): JsonObject {
         return input(value)
     }
 

foundation/journey-plugin/src/main/kotlin/com/pingidentity/journey/plugin/AbstractCallback.kt

@@ -22,18 +22,19 @@ abstract class AbstractCallback : Callback {
     lateinit var json: JsonObject
         protected set
 
-    protected abstract fun onAttribute(name: String, value: JsonElement)
+    protected abstract fun init(name: String, value: JsonElement)
 
-    override fun init(jsonObject: JsonObject) {
+    override fun init(jsonObject: JsonObject) : Callback {
         this.json = jsonObject
         jsonObject["output"]?.jsonArray?.forEach { outputItem ->
             val outputObject = outputItem.jsonObject
             outputObject["name"]?.jsonPrimitive?.content?.let { name ->
                 outputObject["value"]?.let { value ->
-                    onAttribute(name, value)
+                    init(name, value)
                 }
             }
         }
+        return this
     }
 
     fun input(vararg value: Any): JsonObject {
@@ -112,5 +113,5 @@ abstract class AbstractCallback : Callback {
         return json
     }
 
-    override fun asJson(): JsonObject = json
+    override fun payload(): JsonObject = json
 }

foundation/journey-plugin/src/main/kotlin/com/pingidentity/journey/plugin/Callback.kt

@@ -11,11 +11,21 @@ import com.pingidentity.orchestrate.Action
 import com.pingidentity.orchestrate.ContinueNode
 import kotlinx.serialization.json.JsonObject
 
+/**
+ * Callback interface for handling actions in the journey plugin.
+ */
 interface Callback : Action {
-    fun init(jsonObject: JsonObject)
+    /**
+     * Initializes the callback with the provided JSON object.
+     * @param jsonObject The JSON object containing the callback configuration.
+     *   * @return The initialized Callback instance.
+     */
+    fun init(jsonObject: JsonObject): Callback
 
-    //Callback is more self-contained, it created its own json without depending on other Callback
-    fun asJson(): JsonObject
+    /**
+     * Returns the payload of the callback.
+     */
+    fun payload(): JsonObject
 }
 
 /**

foundation/journey-plugin/src/main/kotlin/com/pingidentity/journey/plugin/CallbackRegistry.kt

@@ -9,42 +9,52 @@ package com.pingidentity.journey.plugin
 
 import com.pingidentity.orchestrate.ContinueNode
 import kotlinx.serialization.json.JsonArray
-import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.jsonObject
 import kotlinx.serialization.json.jsonPrimitive
 
+/**
+ * CallbackRegistry is responsible for managing the registration and retrieval of callbacks.
+ * It allows for the registration of callbacks by type and provides a method to retrieve
+ * callbacks based on a JSON array.
+ */
 object CallbackRegistry {
     private val callbacks: MutableMap<String, () -> Callback> = HashMap()
-    val derivedCallbacks: MutableList<(JsonObject) -> String?> = mutableListOf()
 
+    /**
+     * Registers a callback with the specified type.
+     * @param type The type of the callback.
+     * @param block A lambda function that returns an instance of the callback.
+     */
     fun register(type: String, block: () -> Callback) {
         callbacks[type] = block
     }
 
-    fun registerDerived(block: (JsonObject) -> String?) {
-        derivedCallbacks.add(block)
-    }
-
     /**
-     * Injects the DaVinci and ContinueNode instances into the collectors.
-     * @param davinci The DaVinci instance to be injected.
-     * @param continueNode The ContinueNode instance to be injected.
+     * Injects the Journey instances into the callbacks.
+     * @param journey The Journey instance to be injected.
+     * @param continueNode The ContinueNode instance.
      */
-    fun inject(journey: Journey,  continueNode: ContinueNode) {
+    fun inject(journey: Journey, continueNode: ContinueNode) {
         continueNode.callbacks.forEach { callback ->
             if (callback is JourneyAware) {
                 callback.journey = journey
             }
         }
     }
 
-
+    /**
+     * Retrieves a list of callbacks based on the provided JSON array.
+     * @param array The JSON array containing the callback types.
+     *   * @return A list of initialized Callback instances.
+     */
     fun callback(array: JsonArray): List<Callback> {
         val list = mutableListOf<Callback>()
         array.forEach { item ->
             val jsonObject = item.jsonObject
             val type = jsonObject["type"]?.jsonPrimitive?.content
-            callbacks[type]?.let { list.add(it().apply { init(jsonObject) }) }
+            callbacks[type]?.let {
+                list.add(it().init(jsonObject))
+            }
         }
         return list
     }

foundation/journey-plugin/src/test/kotlin/com/pingidentity/journey/plugin/CallbackRegistryTest.kt

@@ -58,20 +58,20 @@ class CallbackRegistryTest {
 }
 
 class DummyCallback : Callback {
-    override fun init(jsonObject: JsonObject) {
-        // Do nothing
+    override fun init(jsonObject: JsonObject): Callback {
+        return this
     }
 
-    override fun asJson(): JsonObject {
+    override fun payload(): JsonObject {
         return buildJsonObject { }
     }
 }
 class Dummy2Callback : Callback {
-    override fun init(jsonObject: JsonObject) {
-        // Do nothing
+    override fun init(jsonObject: JsonObject): Callback {
+        return this
     }
 
-    override fun asJson(): JsonObject {
+    override fun payload(): JsonObject {
         return buildJsonObject { }
     }
 }

foundation/orchestrate/src/main/kotlin/com/pingidentity/orchestrate/SharedContext.kt

@@ -12,6 +12,10 @@ package com.pingidentity.orchestrate
  * @property map The map that holds the shared context.
  */
 class SharedContext(val map: MutableMap<String, Any>) : MutableMap<String, Any> by map {
+
+    infix fun String.to(value: Any) {
+        this@SharedContext[this] = value
+    }
     /**
      * Returns the value of a specific key from the shared context.
      * @param key The key for which the value is to be returned.

foundation/orchestrate/src/main/kotlin/com/pingidentity/orchestrate/Workflow.kt

@@ -72,21 +72,25 @@ class Workflow(val config: WorkflowConfig) {
     /**
      * Starts the workflow with the provided request.
      * @param request The request to start the workflow with.
+     * @param context The flow context of the flow.
      * @return The resulting Node after processing the workflow.
      */
-    suspend fun start(request: Request): Node = lock.withLock {
+    suspend fun start(
+        request: Request,
+        context: SharedContext = SharedContext(mutableMapOf())
+    ): Node = lock.withLock {
         // Before we start, make sure all the module init has been completed
         return catch {
             init()
             config.logger.i("Starting...")
-            val sharedContext = FlowContext(SharedContext(mutableMapOf()))
+            val flowContext = FlowContext(context)
             val req =
                 start.asFlow()
-                    .scan(request) { result, value -> sharedContext.value(result) }.last()
-            val response = send(sharedContext, req)
-            val initialNode = sharedContext.transform(response)
-            return next(sharedContext, node.asFlow().scan(initialNode) { result, value ->
-                value(sharedContext, result)
+                    .scan(request) { result, value -> flowContext.value(result) }.last()
+            val response = send(flowContext, req)
+            val initialNode = flowContext.transform(response)
+            return next(flowContext, node.asFlow().scan(initialNode) { result, value ->
+                value(flowContext, result)
             }.last())
         }
     }
@@ -99,6 +103,15 @@ class Workflow(val config: WorkflowConfig) {
         return start(Request())
     }
 
+    /**
+     * Starts the workflow with a flow context.
+     */
+    suspend fun start(block: SharedContext.() -> Unit): Node {
+        val map = SharedContext(mutableMapOf())
+        block(map)
+        return start(Request(), map)
+    }
+
     /**
      * Signs off the workflow.
      * @return A Result indicating the success or failure of the sign off.

foundation/orchestrate/src/main/kotlin/com/pingidentity/orchestrate/module/CustomParameter.kt

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2025 Ping Identity Corporation. All rights reserved.
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+package com.pingidentity.orchestrate.module
+
+import com.pingidentity.orchestrate.Module
+import com.pingidentity.utils.PingDsl
+
+/**
+ * Configuration class for CustomParameter.
+ * Allows adding custom parameter to be injected into requests.
+ */
+@PingDsl
+class CustomParameterConfig {
+    internal val parameters = mutableListOf<Pair<String, String>>()
+
+    /**
+     * Adds a custom parameter to the configuration.
+     * @param name The name of the parameter.
+     * @param value The value of the parameter.
+     */
+    fun parameter(name: String, value: String) {
+        parameters.add(Pair(name, value))
+    }
+}
+
+/**
+ * Module for injecting custom parameters into requests.
+ */
+val CustomParameter =
+    Module.of(::CustomParameterConfig) {
+
+        /**
+         * Intercepts all send requests and injects custom parameters.
+         * @return The modified request with custom parameters.
+         */
+        next { _, request ->
+            config.parameters.forEach { (name, value) ->
+                request.parameter(name, value)
+            }
+            request
+        }
+
+        /**
+         * Adds custom parameters at the start of the request.
+         * @return The modified request with custom parameters.
+         */
+        start {
+            config.parameters.forEach { (name, value) ->
+                it.parameter(name, value)
+            }
+            it
+        }
+    }