App panels

What are app panels?

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

Terminology

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

Object - App 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 a basic or embedded app action(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 basic or embedded action 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 app 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

App panels can be found inside the detail view of Deals, People, and Organizations - as a panel in the left sidebar. The app 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 app panel per detail view. Taking into consideration the 3 detail views (Deal, People, and Organization), each app can have 3 different app panels altogether.

Structure of an app panel

Top of the app panel

The app 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.

Body of the app panel

An app panel body can consist of objects (multiple object panels) or simply fields (single object panels). Each app 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 app panel’s objects and fields are defined by the JSON Schema that is added in the app listing's edit page in Marketplace Manager.

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

Footer of the app panel

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

Global actions
Found at the bottom left of the app 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.

How does an app 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 app panel and its data but did not install the app. `isShared=false` - User has installed the app and sees the app panel.	`isShared=true`

Actions in panels

Actions in panels allow you to add interactivity to your app 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 app panel.

Expand/collapse
By default, an app 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 app 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 an app panel

Plan out your use case.
Map your use case with the most suitable fields and panel actions for your app panel - see adding an app panel and actions in panels for more details and sample JSON schema templates.
Create the JSON schema for your app panel. Validation of the schema will be done in Marketplace Manager.
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.
Add relevant panel actions to your app panel. Depending on the type of action (basic or embedded), 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.

App 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 app 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 app panels?

In the header of the app panel are your app's icon and the name of the app panel. Both the icon and the app 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 app panel and it'll be minimized, please consider how recognizable your icon is when it's displayed in the app panel.