Confirmation responses

A confirmation response indicates that the action requested can be completed, but it requires some feedback from the user. The response provides information about the confirmation page that has to be presented to the user, as well as the actions that the client must do according to the choices made by the user.

Format

Its general format is an object containing a single attribute tasks, which is an array of objects with the following structure:

Form elements

Some tasks present form elements. A form element contains:

Buttons

The confirmation page requires one or more buttons, which mark the end of the confirmation procedure. The client must always show a “Cancel” button.

Other buttons are specified as follows:

(*) Frontend Codes with Parameters

To let the frontend translate the message (see User Errors), instead of a translated string a map with a frontend code and a list of parameters is sent for a key.

Example:

{
    "tasks": [
        {
            "message": {
                "code": "server.confirm.delete_object_with_children.message",
                "parameters": {
                    "objecttype": "hierarchic_objecttype",
                    "children_count": 4
                }
            }
        },
        ...
    ]
}

The frontend will select the translation of the text with the key code in the current user frontend language, and replace parameter placeholders like %(objecttype)s with the corresponding parameter values.

Actions

For each task, a confirmation page is showed:

When a button is pressed, the client proceeds. If it is the “Cancel” button, the confirmation page is closed and nothing more is done.

If it is an “Ok” button, the frontend will make sure that for every form only one option is selected and will gather all actions:

1. If the button has a name and value, this is an action
2. For evey form element, pick the name and the selected option’s value

If all tasks are confirmed:

The frontend then repeats the request providing all actions in the query string.

Example:

Request and confirmation response:

Request:  DELETE /api/product?token=1234&id=6
Response: HTTP 202
{
    "tasks": [
        {
            "title": "Confirm deletion",
            "message": "You are about to delete a product\nPlease confirm that you want to delete the product 6",
            "buttons": [
                {
                    "text": "Sure!",
                    "name": "confirmation_code",
                    "value": "g723hd67"
                }
            ]
        },
        {
            "title": "Control side-effects",
            "message": "This operation affects a project. Please select what to do:",
            "form": [
                {
                    "label": "The project should be...",
                    "name": "project_action",
                    "type": "options",
                    "options": [
                        {
                            "text": "cancelled",
                            "value": "cancel"
                        },
                        {
                            "text": "delayed",
                            "value": "delay"
                        }
                    ],
                    "buttons": [
                        {
                            "text": "Ok",
                        },
                        {
                            "text": "Ok and notify",
                            "name": "project_notify",
                            "value": "yes"
                        }
                    ]
                }
            ]
        }
    ]
}

A page is shown where the user has the options to confirm or abort the procedure. If the user proceeds, by pressing the “Sure!” button, the form remembers the button action (“confirmation_code=g723hd67”).

Then, a new page is shown where the user has to select between two options. If the user presses the “Ok” button, the form remembers the action (for example, “project_action=delay”). If the user presses the “Ok and notify” button, an addtional action is remembered (“project_notify=yes”).

After this procedure, the frontend sends the request with the new parameters:

Request:  DELETE /api/product?token=1234&id=6&confirmation_code=g723hd67&project_action=delay&project_notify=yes
Response: HTTP 200

The next sections describe the confirmation responses the server currently uses.

List of confirmation responses

Confirm transitions

This response is provided by /api/db when an operation triggers one or more transitions that require a confirmation code.

For each transition, a task is provided. The title of the task contains the transition number. The message comes from the transition definition. There is one button (“Ok”) for each task. However, only the last button has an action associated. The name for that action is “confirm” and the value is the confirmation code.

Confirm action for collection owner rights revoked

This response is provided by /api/db, /api/objecttype, /api/pool and /api/tag when the operation revokes a right for a collection object for the collection owner, which is granted by him via the collection ACL.

Two actions are possible (besides from cancelling the operation):

• remove the objects that are no longer in a valid state for the collection
• remove the ACL entries of the collection that grant the right which has been revoked