Add parameters to action manifest and action request (#334)

* Add parameters to action manifest and action request

* Dont require parameters in action request

Author: lily-es

adapter-docs/src/docs/asciidoc/overview.adoc

@@ -167,6 +167,9 @@ A request consists of the following fields.
 | Attachments
 | Any number of attachments. See table below for a list of possible request attachments.
 
+| Parameters
+| A list of arbitrary attachments requested by the action
+
 | Time budget
 | The app will use a time out if no response is received within x seconds after the user triggered an operation.
 Each action request will contain an estimated time budget the adapter should strive to respond within.

adapter-protobuf-java/src/main/proto/adapter.proto

@@ -79,6 +79,9 @@ message AdapterManifest {
 
     reserved 5;
 
+    // A list of arbitrary parameters this action can accept as input
+    repeated ParameterDefinition accepted_parameters = 6;
+
   }
 
 
@@ -97,6 +100,20 @@ message AdapterManifest {
 
   }
 
+  // An arbitrary parameter that this action can accept
+  // Example
+  // ---------
+  // Name: colour
+  // Description: A colour (red|blue|green|yellow|pink|cyan|white)
+  message ParameterDefinition {
+
+    // The name of the parameter
+    string name = 1;
+
+    // A helpful description of what the parameter is
+    string description = 2;
+  }
+
 }
 
 
@@ -123,6 +140,9 @@ message ActionRequest {
   // error is better then not returning anything.
   int32 time_budget_millis = 4;
 
+  // Arbitrary map of parameters and their values as requested by the action manifest
+  map<string, string> parameters = 6;
+
 }
 
 // Your adapter should return this as a response to requests submitted

adapter-sdk-kotlin/src/main/kotlin/com/github/oslokommune/oslonokkelen/adapter/action/ActionDescription.kt

@@ -6,5 +6,6 @@ data class ActionDescription(
     val id: ActionId,
     val description: String = "Action: ${id.short}",
     val requiredAttachmentTypes: Set<Adapter.AttachmentType> = emptySet(),
-    val possibleOutputAttachmentTypes: Set<Adapter.AttachmentType> = emptySet()
+    val possibleOutputAttachmentTypes: Set<Adapter.AttachmentType> = emptySet(),
+    val parameters: List<Adapter.AdapterManifest.ParameterDefinition> = emptyList()
 )

adapter-sdk-kotlin/src/main/kotlin/com/github/oslokommune/oslonokkelen/adapter/action/AdapterActionRequest.kt

@@ -8,11 +8,17 @@ data class AdapterActionRequest(
     val requestId: String = UUID.randomUUID().toString(),
     val actionId: ActionId,
     val timeBudget: Duration,
-    val attachments: List<AdapterAttachment>
+    val attachments: List<AdapterAttachment>,
+    val parameters: Map<String, String>
 ) {
 
     inline fun <reified A : AdapterAttachment> require(): A {
         return attachments.filterIsInstance<A>().firstOrNull()
             ?: throw InvalidAdapterRequestException("Missing attachment: ${A::class.simpleName}")
     }
+
+    fun requireParameter(parameterName: String): String {
+        return parameters[parameterName]
+            ?: throw InvalidAdapterRequestException("Missing parameter: $parameterName")
+    }
 }

adapter-sdk-kotlin/src/main/kotlin/com/github/oslokommune/oslonokkelen/adapter/protobuf/ProtobufParser.kt

@@ -67,6 +67,15 @@ object ProtobufParser {
                     null
                 }
             })
+            .putAllParameters(optionalMap(requestClaim, "parameters")?.mapNotNull {
+                val key = it.key as? String
+                val value = it.value as? String
+                if(key != null && value != null) {
+                    key to value
+                } else {
+                    null
+                }
+            }?.toMap() ?: emptyMap())
 
         return requestBuilder.build()
     }
@@ -90,6 +99,10 @@ object ProtobufParser {
         return value ?: throw missingKey(key, requestClaim)
     }
 
+    private fun optionalMap(requestClaim: Map<String, Any>, key: String): Map<*, *>? {
+       return requestClaim[key] as? Map<*, *>
+    }
+
     private fun missingKey(key: String, requestClaim: Map<*, *>): IllegalStateException {
         return IllegalStateException("Missing key $key (found: ${requestClaim.keys.joinToString(", ")})")
     }
@@ -101,7 +114,8 @@ object ProtobufParser {
             timeBudget = Duration.ofMillis(serializedRequest.timeBudgetMillis.toLong()),
             attachments = serializedRequest.attachmentsList.mapNotNull { attachment ->
                 parseAttachment(attachment)
-            }
+            },
+            parameters = serializedRequest.parametersMap
         )
     }
 
@@ -224,7 +238,8 @@ object ProtobufParser {
                     id = thing.id.createActionId(serializedAction.id),
                     description = serializedAction.description,
                     requiredAttachmentTypes = serializedAction.requiredInputAttachmentTypesList.toSet(),
-                    possibleOutputAttachmentTypes = serializedAction.possibleOutputAttachmentTypesList.toSet()
+                    possibleOutputAttachmentTypes = serializedAction.possibleOutputAttachmentTypesList.toSet(),
+                    parameters = serializedAction.acceptedParametersList
                 )
 
                 thingActions = thingActions.put(action.id, action)

adapter-sdk-kotlin/src/main/kotlin/com/github/oslokommune/oslonokkelen/adapter/protobuf/ProtobufSerializer.kt

@@ -24,6 +24,7 @@ object ProtobufSerializer {
             .setRequestId(request.requestId)
             .setThingId(request.actionId.thingId.value)
             .setActionId(request.actionId.value)
+            .putAllParameters(request.parameters)
             .build()
     }
 
@@ -318,6 +319,7 @@ object ProtobufSerializer {
                 .setDescription(action.description)
                 .addAllRequiredInputAttachmentTypes(action.requiredAttachmentTypes.toList())
                 .addAllPossibleOutputAttachmentTypes(action.possibleOutputAttachmentTypes.toList())
+                .addAllAcceptedParameters(action.parameters)
                 .build()
         } ?: emptyList()
 

adapter-sdk-kotlin/src/main/kotlin/com/github/oslokommune/oslonokkelen/adapter/tokens/generator/BackendTokenGenerator.kt

@@ -63,7 +63,8 @@ class BackendTokenGenerator(
                     is AdapterAttachment.ErrorDescription,
                     is AdapterAttachment.ErrorCategory -> null
                 }
-            }
+            },
+            "parameters" to request.parameters
         )
 
         return buildToken {

adapter-sdk-kotlin/src/test/kotlin/com/github/oslokommune/oslonokkelen/adapter/protobuf/ProtobufParserTest.kt

@@ -21,7 +21,8 @@ internal class ProtobufParserTest {
             timeBudget = Duration.ofMillis(2400),
             attachments = listOf(
                 AdapterAttachment.NorwegianFodselsnummer("12345678912")
-            )
+            ),
+            parameters = mapOf("test" to "testValue")
         )
 
         val token = BackendTokenGeneratorTest.testGenerator.createActionRequestToken(

adapter-sdk-kotlin/src/test/kotlin/com/github/oslokommune/oslonokkelen/adapter/protobuf/ProtobufSerializerTest.kt

@@ -35,7 +35,8 @@ internal class ProtobufSerializerTest {
                 timeBudget = Duration.ofSeconds(3),
                 attachments = listOf(
                     AdapterAttachment.NorwegianFodselsnummer("30098602247")
-                )
+                ),
+                parameters = mapOf("test" to "testValue")
             )
 
             val serializedRequest = ProtobufSerializer.serialize(request)

adapter-sdk-kotlin/src/test/kotlin/com/github/oslokommune/oslonokkelen/adapter/tokens/generator/BackendTokenGeneratorTest.kt

@@ -34,7 +34,8 @@ class BackendTokenGeneratorTest {
                 timeBudget = Duration.ofSeconds(2),
                 attachments = listOf(
                     AdapterAttachment.NorwegianFodselsnummer("30098602247")
-                )
+                ),
+                parameters = mapOf("test" to "testValue")
             )
         )