JSON modals

What are JSON modals?


📘

JSON modals were previously called embedded app actions.

JSON modals are app actions in the form of a modal with predefined components that enable users to complete full actions inside Pipedrive.

It allows apps to provide a way for users to do as much as possible without leaving Pipedrive, e.g. the app can use JSON modals to add contacts to email campaigns, change the status of a document, push the latest deal changes to linked documents, and create tasks in project management tools - all from a modal view that can be customized based on your app’s needs.

JSON modals can be initiated from the action menu and the app panel settings menus. After a JSON modal has been clicked, a new modal containing Blocks and Action buttons will appear, where users can complete the action.

The visibility and availability of JSON modals will stay the same as for Link app actions. Each app can have a total of 21 app actions (link or JSON modal) from menus in different views (see detailed visibility in the UI). JSON modals don’t work for shared apps - users need to install apps themselves to use JSON modals.

JSON modal is triggered from the JSON panel JSON modal is triggered from the JSON panel

JSON modal is triggered from the JSON panel

JSON modal can be triggered from the three-dot actions menu. Link app action shown with an arrow. JSON modal can be triggered from the three-dot actions menu. Link app action shown with an arrow.

JSON modal can be triggered from the three-dot actions menu. Link app action shown with an arrow.

The JSON modal is displayed after the action is clickedThe JSON modal is displayed after the action is clicked

The JSON modal is displayed after the action is clicked



The structure of the JSON modal


The JSON modal will display a modal container after it has been triggered. Each modal can contain up to 8 different types of UI elements called Blocks.

Key terminology:

Container - is a base UI element that will include different smaller customizable elements to show information from apps.

Modal - is currently the only container offered. Modal’s base layout is non-configurable. Each JSON modal action can display one modal, and each modal can contain up to 10 Blocks.

Components - are all UI elements that can be added to the JSON modal, e.g. Blocks and Action buttons.

Blocks - smaller UI elements that can be included inside a modal, e.g., texts, multi-select, etc. The full list of available Blocks is available here.

Modal form - a combination of information and Blocks displayed inside the modal.

Action buttons - buttons in the footer of a modal that trigger the modal's action, this can be submitting, resetting, and cancelation.

The structure of the JSON modalThe structure of the JSON modal

The structure of the JSON modal


How to create a JSON modal?


Key steps

  1. Plan out your use case.

  2. Map your use case with the most suitable Blocks for your modal - see Component library for a full list of available Blocks and how to add them to the schema.

  3. Create the schema. Validation of the schema can be done in Marketplace Manager.

    1. 1 Configure an API endpoint on your side to respond to Pipedrive’s request. The endpoint should be able to respond/return different sets of data based on the user's input choices.
  4. Configure the JWT token. The JWT token is used to secure the requests done from the JSON modal. We send the security token on each request. The JWT token can be decrypted with one value on the app's side. You can also specify a JWT secret value to the requests by adding it under JWT secret in Marketplace Manager when combining your JSON modal. If no JWT secret is added in the Marketplace Manager, we send the client secret as this value by default.

  5. Add your JSON modal’s schema to Marketplace Manager. If you already have a live app, please create another test app for testing out the JSON modals.

Adding the action in Marketplace Manager

Go to your app’s edit page in Marketplace Manager and scroll to the App extensions' section.

Click on “+ Action” under App actions and select “JSON modal” as the Action type. The form will slightly change depending on which type of App action you'll choose.
Next, fill in the name of the JSON modal action and the rest of the fields.

Field

Description

Action name (required)

The name of your JSON modal. Descriptive, max 30 characters and should be sentence-cased (only capitalize the first word).

Action type (required)

JSON modal

API endpoint URL (required)

All API requests related to this action will be sent to this URL.

JWT Secret

Optional. Defaults to client_secret.

JSON data structure (required)

The JSON schema for your JSON modal.

Action location (required)

Maximum 3 app extensions per location. Each app can have a total of 21 app actions.

See more about available locations in app action’s visibility.



Schema


JSON modal schema


The following example schema is the complete schema for the sample modal shown in the modal structure section above.

The JSON schema consists of a mapping of all blocks and actions that will be displayed in the JSON modal for the user. More on which components to add and what options they offer, see Component library, for seeing how to display success and error messages inside the modal, see the User interaction handling page.

{
    "type":"object",
    "properties":{
        "blocks":{
            "type":"object",
            "properties":{
                "block_key_cake_size":{
                    "$ref":"#/definitions/element-input",
                    "options":{
                        "label":"Cake size",
                        "placeholder":"Insert size",
                        "message":"Cake size will be either S, M or L"
                    }
                },
                "block_key_textarea":{
                    "$ref":"#/definitions/element-textarea",
                    "options":{
                        "label":"Additional instructions",
                        "placeholder":"Write \"Happy Birthday!\" on the cake!",
                        "message":"What would you like to have on your cake?",
                        "resize":true
                    }
                },
                "block_key_separator":{
                    "$ref":"#/definitions/element-separator"
                },
                "block_key_flavors":{
                    "$ref":"#/definitions/element-checkbox-group",
                    "options":{
                        "label":"Flavor",
                        "value":[
                            "cranberry"
                        ],
                        "items":[
                            {
                                "value":"vanilla",
                                "label":"Vanilla"
                            },
                            {
                                "value":"chocolate",
                                "label":"Chocolate",
                                "isDisabled":true
                            },
                            {
                                "value":"cranberry",
                                "label":"Cranberry"
                            }
                        ]
                    }
                },
                "block_key_delivery_date":{
                    "$ref":"#/definitions/element-datepicker",
                    "options":{
                        "label":"Delivery date",
                        "value":"2020-02-27",
                        "message":"Cakes will be ready by 12:00 on selected date",
                        "placeholder":"Date",
                        "allowClear":true,
                        "isRequired":true
                    }
                },
                "block_key_delivery_method":{
                    "$ref":"#/definitions/element-select",
                    "options":{
                        "label":"Delivery method",
                        "placeholder":"Select method",
                        "message":"Please, specify how the delivery will be done",
                        "isRequired":true,
                        "items":[
                            {
                                "label":"Standard",
                                "value":1
                            },
                            {
                                "label":"Accelerated",
                                "value":2
                            }
                        ]
                    }
                },
                "block_key_is_gift":{
                    "$ref":"#/definitions/element-radio-group",
                    "options":{
                        "label":"Wrap as gift?",
                        "items":[
                            {
                                "value":"yes",
                                "label":"Yes"
                            },
                            {
                                "value":"no",
                                "label":"No"
                            }
                        ]
                    }
                },
                "block_key_info":{
                    "$ref":"#/definitions/element-text",
                    "options":{
                        "value":"Thank you for using the cake ordering app!"
                    }
                }
            }
        },
        "actions":{
            "type":"object",
            "properties":{
                "cancel_action":{
                    "$ref":"#/definitions/action-secondary",
                    "options":{
                        "label":"Cancel",
                        "handler":"cancel"
                    }
                },
                "submit_action":{
                    "$ref":"#/definitions/action-primary",
                    "options":{
                        "label":"Save",
                        "handler":"request"
                    }
                }
            }
        }
    }
}


JSON modal's data exchange on opening the modal


The user flow interaction will go as follows for the JSON modal:

  1. The User opens the three-dot/actions menu and clicks on the “New cake order“ action.
  2. A modal appears based on the JSON schema added to the Marketplace Manager for the JSON modal.
  3. Initial request will be sent to the endpoint that was set as an API endpoint in Marketplace Manager.

📘

All requests from JSON modals contain the same query parameters as Link app actions - resource, view, userId, companyId, selectedIds plus additional form, invoker (see Component library, and token (encrypted JWT token value). token contains encrypted userID and companyID, so you can verify them from the query parameters.

The response to the initial request should be formatted accordingly to the JSON schema data structure that was uploaded in Marketplace Manager.

The response for the initial request can be used for:

  • Simply acknowledging the request,
  • Setting default values for the inputs

For example, the response for a schema could be as follows. The response can partially include options for dynamic data such as "items" and "value" for different Blocks. The options will be merged with uploaded structure by block key defined in the schema and used in API response in the path /data/blocks or /data/actions.

{
    "data": {
        "blocks": {
            "block_key_delivery_method": {
                "value": 1,
                "items": [
                    {
                        "label": "Standard",
                        "value": 1
                    },
                    {
                        "label": "Accelerated",
                        "value": 2
                    }
                ]
            },
            "block_key_is_gift": {
                "value": "yes"
            }
        },
        "actions": {}
    }
}

The schema will now show the "standard" delivery option as a preselected value for Select Block and "yes" as a preselected value for Radio Group Block.

Or the response could be returned with a "data" property, that is required, and the "blocks" array and "actions" array can be left empty, as the response will be merged with the already added schema definition in Marketplace Manager and displayed as it is.

Response from the API endpoint

{
    "data": {
        "blocks": {},
        "actions": {}
    }
}

Here you can see, how the modal remained the same as in the schema definition, no new values were added.

📘

Please note that options from the uploaded structure and API response will be first merged and then validated altogether (see Structure validation).



Schema structure validation


The response structure received from the app’s API endpoint can be incorrect. For example, this can happen when some options have an invalid value, a missing required option or, a Block that includes an unknown additional option. In this situation, the user will see an error.

For example, the following data response will cause validation errors as willNotPass is an invalid option`

{
    "data":{
        "blocks":{
            "input_item":{
                "willNotPass":true
            }
        },
        "actions":{
            "submit":{
                "handler":"invalid-handler"
            }
        }
    }
}
Modal validation error displayed in the modal UIModal validation error displayed in the modal UI

Modal validation error displayed in the modal UI

Actual errors won't be visible for users in the UI but can be checked in the Network tab in Developer Tools in your browser when you click on the error path.

If there is an error, troubleshooting can be done using the following parameters:

  • dataPath tells what Block's data is invalid.
  • message contains an explanation of why it is invalid.
  • params gives more context about the error.
Troubleshooting errors in the Network tab under Developer Tools in your browser tab.Troubleshooting errors in the Network tab under Developer Tools in your browser tab.

Troubleshooting errors in the Network tab under Developer Tools in your browser tab.



Schema data exchange on modal form submit


📘

Your own destination URL can be defined in the uploaded schema for each primary action button. By default, the JSON modal URL set in Marketplace Manager will be used for all requests.

When all required fields are filled in, the user can submit the modal form (or open a new browser tab - depends on your action handler configuration).
Before sending the form data as a request payload, it will be collected from:

  • All visible Blocks
  • Blocks with “visibleOn”: “never”. These blocks won’t be visible to the users but allow you to send additional metadata to your service, e.g., data from fields of Pipedrive entities to save additional API requests.
{
    "block_key_input": "Some text value"
}

There are a few options for the following user behavior:

  • in a positive scenario, the modal will be either closed with a snackbar notification shown to the user or a new browser tab will be opened (see Displaying success message).
  • in a negative scenario, there are 3 different ways how errors and error messages can be displayed to the user (see Displaying error message).


Did this page help you?