JSON panels

What are JSON panels?


📘

JSON panels were previously called app panels.

JSON panels allow Pipedrive users to see and use the data from your app directly inside Pipedrive in the form of a panel.

JSON panel in Pipedrive web appJSON panel in Pipedrive web app

JSON panel in Pipedrive web app


Terminology

JSON panels - An entrance point for an app's data and interactivity inside Pipedrive in a panel format.

Object - A JSON panel object is a data entry point with multiple descriptive fields displayed inside a panel. A panel can contain multiple objects.

Object actions menu - A white "Actions" button with an arrow pointing downwards at the top right of the object. It features a dropdown menu that gives access to link(s) or JSON modal(s). Object actions are specific to the object itself and only available for multiple object panels.

Field - Descriptive data field in a certain format within the object.

Field action - A link or JSON modal that allows the user to interact with the data inside the field. The action is specific to the field itself.

Global actions - A green action button at the bottom of the JSON panel. It features one main app action and a dropdown menu if there are multiple app actions and/or an external link.

Actions menu - A dropdown menu, accessible from the three dots symbol on the top of the panel. The menu allows the user to manage the left sidebar, adjust panel and app settings as well as access the same app action(s) as the one(s) defined in global actions.


Visibility in the UI

JSON panels can be found inside the detail view of Deals, People, and Organizations - as a panel in the left sidebar. The JSON panel will appear at the top of the left sidebar and its location can be changed, hidden, and reordered with other sections in the sidebar.

Each app is allocated 1 JSON panel per detail view. Taking into consideration the 3 detail views (Deal, People, and Organization), each app can have 3 different JSON panels altogether.



Structure of a JSON panel


Structure of the JSON panelStructure of the JSON panel

Structure of the JSON panel

Top of the JSON panel

The JSON panel header has three icons next to the panel name: the reload button, collapse/expand button, and actions menu.

Reload button - Enables the user to reload information that is pulled from your app.

Collapse/expand button - Enables the user to collapse/expand the panel manually.

Actions menu - Enables the user to access a dropdown menu that contains a link to manage the left sidebar, adjust app and panel settings and access app-specific app actions. App-specific app actions are app actions that belong only to your app.

Top of the JSON panelTop of the JSON panel

Top of the JSON panel

Body of the JSON panel

A JSON panel body can consist of objects (multiple object panels) or simply fields (single object panels). Each JSON panel can display a maximum of 10 objects, while each object can display a maximum of 20 fields along with a header and field data.

The JSON panel’s objects and fields are defined by the JSON Schema that is added in the app listing's edit page in Marketplace Manager.

JSON panels can be interactive with the addition of object actions and field actions. Learn more about it here.

Body of the JSON panelBody of the JSON panel

Body of the JSON panel


Footer of the JSON panel

The footer of the JSON panel contains two items: global actions and feedback dialog.

Global actions
Found at the bottom left of the JSON panel, global actions are represented by a green action button. This is where the user can find one main app action that is featured and a dropdown menu if there are multiple app actions and/or an external link. These app actions are app-specific.

The order of global actions can be customized based on your app users' needs. More details about it here.

Feedback dialog
The feedback dialog is a light blue box with a thumbs up and a thumbs down symbol that enables users to give you direct feedback about your app. Feedback will be sent to the main contact info email that you specified in your app listing inside Marketplace Manager.

If a user gives a “thumbs down”, it is mandatory for them to answer “what features are missing” in the message box. If the user gives a “thumbs up”, they can choose to leave a message. Users may also close the feedback dialog without giving any feedback.

Footer of the JSON panelFooter of the JSON panel

Footer of the JSON panel



How does a JSON panel work?


When the page or a panel is reloaded, we will renew the information in the panel by requesting the information from the API endpoint (which is provided to us in your app listing's edit page in Marketplace Manager). You will receive an HTTP request to your API with a Basic Authentication header (defined in Marketplace Manager as HTTP Auth username and password) and query parameters (described in the table below). If it takes more than 10 seconds to receive the response, the app panel will display a "Something went wrong…" error message.

These are the parameters that are added to the API endpoint's URL:

Parameter

Explanation or value(s)

Examples

resource

deal/person/organization

resource=deal

view

details

view=details

userId

userId=12345

companyId

companyId=12345

selectedIds

Entity ID that shows the ID of the selected entity

selectedIds=3

isShared

true or false

  • isShared=true - User sees JSON panel and its data but did not install the app.
  • isShared=false - User has installed the app and sees the JSON panel.

isShared=true

Actions in panels

Actions in panels allow you to add interactivity to your JSON panel. App actions can be added for the entire panel, the object itself and individual fields. Learn more about it here.

Panel settings

Panel settings can be found by clicking on the actions menu in the top right of the JSON panel.

Expand/collapse
By default, a JSON panel is set to expand/collapse manually. In panel settings, users can choose to auto-expand or auto-collapse the panel based on filters for each detail view - Deals, People, Organizations.

Ordering of fields
In your JSON panel, you can present your own default view of fields based on what you make available. The user can decide to change the order and presentation of the fields via panel settings.



Key steps to adding a JSON panel


  1. Plan out your use case.

  2. Map your use case with the most suitable fields and panel actions for your JSON panel - see adding a JSON panel and actions in panels for more details and sample JSON schema templates.

  3. Create the JSON schema for your JSON panel. Validation of the schema will be done in Marketplace Manager.

  4. 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.

  5. Add relevant panel actions to your JSON panel. Depending on the type of action (link or JSON modal), different aspects need to be filled out. See more details in actions in panels.

Keep in mind, if you already have a live app, please create another test app for testing out the adding a panel and/or panel actions.



JSON panels in App Approval Process


What if my app has already been approved?

If you already have an app or an integration available in the Pipedrive Marketplace, please create a new test app for the development of the JSON panels and to make sure they work properly.

Remember that any changes saved when updating a public app in the Marketplace Manager will all be immediately visible for your app users.

What to consider when submitting JSON panels?

In the header of the JSON panel are your app's icon and the name of the JSON panel. Both the icon and the JSON panel's name can be added to your app's listing in the Marketplace Manager. Since your app's icon will be displayed next to the title of the JSON panel and it'll be minimized, please consider how recognizable your icon is when it's displayed in the JSON panel.



Did this page help you?