Repeat Handlers

Repeat handlers allow users to define behaviour that handles utterances like "Go back", "Start over" and so on.

This is done by configuring Repeat Handler objects:

The user chooses the types of repeat events we want to handle (currently the only one that is supported is StartOver). If no events are selected, the handler triggers on all of them by default.
The user chooses the miniApps where the handled event can originate from. If no event sources are selected, the handler triggers on all of them by default.
The users select one or more of the fields of the current Flow that should be dropped when this event occurs. Dropping these fields will result in the corresponding miniApps or Flows repeating and the fields being asked again.

Each Application and Flow have their own repeat handlers. This means that there are two sets of identical end-points: one set under apps/<app_id>/repeat-handlers/ and one under flows/<flow_id>/repeat-handlers/.

They both function in exactly the same way. The difference is which DiaManT Application we want the handling to happen in.

Get Repeat Handlers

GET /api/apps/<app_id>/repeat-handlers/
GET /api/flows/<flow_id>/repeat-handlers/

URL params

Name	Type	Description	Example
`app_id`	uuid	the Application's id that the repeat handlers belong to	"9b399774-3a0a-40c1-8a1c-4a124170b6f3"
`flow_id`	uuid	the Flow's id that the repeat handlers belong to	"9b399774-3a0a-40c1-8a1c-4a124170b6f3"

Successful status: 200 OK

Return the list of Repeat Handlers.

Example:

JSON

[
    {
        "error_types": [
            "StartOver",
            "CallBack"
        ],
        "error_sources": [],
        "drop_fields": [
            "Entity1_0_output",
            "ConfirmPayment-0-output"
        ]
    },
    {
        "error_types": [
            "StartOver",
            "CallBack"
        ],
        "error_sources": [
            "54d1fc80-4627-4515-9dbc-2cef8dca0650.Entity1.Entity.MiniApps.flowteam",
            "54d1fc80-4627-4515-9dbc-2cef8dca0650.ConfirmPayment.YesNo.MiniApps.flowteam"
        ],
        "drop_fields": [
            "WelcomeAnnouncement-0-output",
            "Entity1_0_output",
            "ConfirmPayment-0-output"
        ]
    }
]

Failed status: 404 NOT_FOUND

Create/Update Repeat Handlers

Creating and Updating Repeat Handlers happens through the same PUT request, by updating the list of Repeat Handlers.

PUT /api/apps/<app_id>/repeat-handlers/
PUT /api/flows/<flow_id>/repeat-handlers/

URL params

Name	Type	Description	Example
`app_id`	uuid	the Application's id that the repeat handlers belong to	"9b399774-3a0a-40c1-8a1c-4a124170b6f3"
`flow_id`	uuid	the Flow's id that the repeat handlers belong to	"9b399774-3a0a-40c1-8a1c-4a124170b6f3"

Request payload

List of Repeat Handlers.

Name	Type	Default	Description	Required
`error_types`	array[string]	Any Event Type	error type(s) that trigger the repeat handler. If multiple are specified, they are combined with OR conditions. NOTE: If no error types are selected, the default value of ANY is applied.	no
`error_sources`	array[string]	Any Event Source	error source(s) that trigger the repeat handler. If multiple are specified, they are combined with OR conditions. NOTE: If no error sources are selected, the default value of ANY is applied.	no
`drop_fields`	array[string]	-	list of fields from the Flow or App's field list that should be dropped as a result of the handling.	yes

Example:

JSON

[
    {
        "error_types": [
            "StartOver",
            "CallBack"
        ],
        "error_sources": [],
        "drop_fields": [
            "Entity1_0_output",
            "ConfirmPayment-0-output"
        ]
    },
    {
        "error_types": [
            "StartOver",
            "CallBack"
        ],
        "error_sources": [
            "54d1fc80-4627-4515-9dbc-2cef8dca0650.Entity1.Entity.MiniApps.flowteam",
            "54d1fc80-4627-4515-9dbc-2cef8dca0650.ConfirmPayment.YesNo.MiniApps.flowteam"
        ],
        "drop_fields": [
            "WelcomeAnnouncement-0-output",
            "Entity1_0_output",
            "ConfirmPayment-0-output"
        ]
    }
]

Successful status: 200 CREATED

List of Repeat Handlers.

Example:

JSON

[
    {
        "error_types": [
            "StartOver",
            "CallBack"
        ],
        "error_sources": [],
        "drop_fields": [
            "Entity1_0_output",
            "ConfirmPayment-0-output"
        ]
    },
    {
        "error_types": [
            "StartOver",
            "CallBack"
        ],
        "error_sources": [
            "54d1fc80-4627-4515-9dbc-2cef8dca0650.Entity1.Entity.MiniApps.flowteam",
            "54d1fc80-4627-4515-9dbc-2cef8dca0650.ConfirmPayment.YesNo.MiniApps.flowteam"
        ],
        "drop_fields": [
            "WelcomeAnnouncement-0-output",
            "Entity1_0_output",
            "ConfirmPayment-0-output"
        ]
    }
]

Failed status: 400 BAD_REQUEST

Failed status: 404 NOT_FOUND

when the group access privileges constraint is violated (the application is under a group to which the user does not have access privileges).

Delete Repeat Handler

To delete a Repeat Handler, you make a PUT request as above, with payload empty list [].

Failed status: 400 BAD_REQUEST

The following errors may be returned by the API in case of misconfigured Repeat Handlers:

Repeat Handler Warnings

All the messages below can also appear as warnings on Canvas save if a change is introduced that causes the corresponding problems.

drop Fields are empty

Example:

JSON

{
    "message": "A Repeat Handler has an empty Drop Field set. Please add at least one field to drop.",
    "errors": {
        "repeat_handler_errors": [
            {
                "type": "WARNING",
                "code": "EMPTY_REPEAT_DROP_FIELDS",
                "message": "A Repeat Handler has an empty Drop Field set. Please add at least one field to drop.",
                "location": "repeat_handlers/0"
            }
        ]
    }
}

drop Field does not exist

Example:

JSON

{
    "message": "Unknown field is referenced at a repeat handler. Field: <name of field> (drop field).",
    "errors": {
        "repeat_handler_errors": [
            {
                "type": "WARNING",
                "code": "UNKNOWN_DROP_FIELD",
                "message": "Unknown field is referenced at a repeat handler.",
                "field": {
                    "field_type": "drop field",
                    "name": "<name of field>"
                },
                "location": "repeat_handlers/0"
            }
        ]
    }
}

a used Event Type does not exist

Example:

JSON

{
    "message": "An invalid event type has been specified. Please select one of the available types. Field: <name of field> (event type).",
    "errors": {
        "repeat_handler_errors": [
            {
                "type": "WARNING",
                "code": "INVALID_EVENT_TYPE",
                "message": "An invalid event type has been specified. Please select one of the available types.",
                "field": {
                    "field_type": " event type",
                    "name": "<name of field>"
                },
                "location": "repeat_handlers/0"
            }
        ]
    }
}

a used Event Source does not exist

Example:

JSON

{
    "message": "A miniApp has been referenced as Event Source but it no longer exists. Please remove the reference. Field: <name of source> (event source).",
    "errors": {
        "repeat_handler_errors": [
            {
                "type": "WARNING",
                "code": "UNKNOWN_EVENT_SOURCE",
                "message": "A miniApp has been referenced as Event Source but it no longer exists. Please remove the reference.",
                "field": {
                    "field_type": "event source",
                    "name": "<name of source>"
                },
                "location": "repeat_handlers/0"
            }
        ]
    }
}

Models

Repeat Handlers

Name	Type	Description
`error_types`	array[string]	list of FailExitReasons (for example, "getMiniAppError", "InfoAsked_NotAvailable", "MaxNoInputs")
`error_sources`	array[string]	list of Fields to use as error sources
`drop_fields`	array[string]	list of Fields to drop

Example:

JSON

[
    {
        "error_types": [
            "StartOver",
            "CallBack"
        ],
        "error_sources": [],
        "drop_fields": [
            "Entity1_0_output",
            "ConfirmPayment-0-output"
        ]
    },
    {
        "error_types": [
            "StartOver",
            "CallBack"
        ],
        "error_sources": [
            "54d1fc80-4627-4515-9dbc-2cef8dca0650.Entity1.Entity.MiniApps.flowteam",
            "54d1fc80-4627-4515-9dbc-2cef8dca0650.ConfirmPayment.YesNo.MiniApps.flowteam"
        ],
        "drop_fields": [
            "WelcomeAnnouncement-0-output",
            "Entity1_0_output",
            "ConfirmPayment-0-output"
        ]
    }
]