Install and Configure Mobileforce for Hubspot

Install and Configure Mobileforce for Hubspot

This article is for a HubSpot Admin who is installing Mobileforce CPQ from the HubSpot App Marketplace. The section on Mobileforce Prop Keys is for a Mobileforce solutions engineer, who is configuring the Mobileforce CPQ app for a customer.

This article describes three distinct settings:

  1. HubSpot (OAuth) Scopes

Each HubSpot API call requires one or more OAuth scopes.

  1. HubSpot User Permissions

HubSpot User Permissions are used for User access management.

A HubSpot admin uses Settings --> Users & Teams --> Users to view, copy, or assign Permission Sets to users, and Settings --> Users & Teams --> Permission Sets to create permission sets.

  1. Mobileforce Prop Keys.

These properties are used to configure and control the Mobileforce CPQ application.

The first two are for the HubSpot Admin, and the last is for the Mobileforce Solutions Engineer.

Note
HubSpot OAuth Scopes are different from HubSpot Permission Sets.

A User Permission may grant access to multiple OAuth Scopes or an OAuth Scope may require multiple User Permissions. It is not clear which User Permissions one needs to select to grant the needed OAuth Scopes. As of October 2024, HubSpot provides no documentation that maps User Permissions to Scopes.

Warning
Each HubSpot API requires one or more OAuth scopes to call it. But user access management in the HubSpot UI does not use OAuth Scopes. It uses different objects called "User Permissions" instead. And these User Permissions are not the Same as OAuth Scopes.

HubSpot OAuth Scopes

HubSpot recommends the following default set of oauth scopes, established via the prop key hubspot-oauth-scope (see values for this prop-key below). Specifically, be sure to set permissions for following HubSpot objects:

The scopes specified below are Required Scopes for Mobileforce App, except for Conditional Scopes, which are introduced in HubSpot starting October 2024. A required scope is included in the scope query parameter for all installations of Mobileforce, whereas a conditional scope may be included in the scope query parameter only for some installations of Mobileforce that use the conditional scope.

REQUIRED SCOPES
READ and WRITE scopes:

READ scopes:

CONDITIONAL SCOPES
As of October 2024, HubSpot also supports conditional scopes. These conditional scopes can be optionally requested for certain app installs of Mobileforce CPQ. If a conditional scope is included in your Mobileforce install, this scope must be approved by your HubSpot Admin for the Mobileforce installation to be completed. The following conditional scopes are specified for the Mobileforce App listing on the HubSpot App Marketplace.

HubSpot Permissions

In HubSpot, permissions are accessed from Settings --> Users & Teams
First, the "Permission Sets" tab is used to create Permission Sets, and then the "Users" tabs is used to assign specific permission sets for specific users.

The following permissions (found in the UI for creating Permission Sets) are necessary for any user who wishes to use Mobileforce CPQ.

  1. CRM--> CRM Objects

  2. CRM --> CRM Tools

  3. Marketing --> Files (Read, Write, Delete)

Verifying HubSpot Permissions

Please ensure the following crm permissions for users who wish to use Mobileforce CPQ

Specific HubSpot User Permissions needed to access Mobileforce CPQ

View Only
CRM Objects --> Contacts

View and Edit
CRM Objects --> Companies
CRM Objects --> Deals

The following view and edit permissions are optionally needed if your application uses Ticket information in Quoting.
CRM Objects --> Tickets

The following permissions shouldn't be needed but appear to be needed by HubSpot, for Mobileforce CPQ to function.

View, Edit, and Delete
Marketing -> Files

Note
Hubspot restricts only Professional and Enterprise accounts to use e-commerce scope for the Products API

There are two user permissions that our app may require which may be problematic to customers:

The problem is that the customer may not want to provide these permissions to all their employees. The 'Files > Delete' permission allows a user to delete any file in the system. The 'Edit Property Settings' permission allows a user to add or remove custom properties to any object. Unfortunately, there isn't anything we can do about this. MobileForce itself does not need to delete files or update properties. But HubSpot's Permissions implementation does not provide the granularity needed for us to specify this.

Mobileforce Prop Keys

The following prop keys need to be set in your Mobileforce instance, in order to use Mobileforce CPQ with HubSpot. Specifically, you can find the clientid and clientsecret for Mobileforce CPQ from the Mobileforce Admin team. You will also need your HubSpot instanceid in the prop key hubspot-oauth-authurl.

To learn about HubSpot's support for Oauth2.0 follow this link:

<prop key="comment">*** HubSpot ***</prop>
<prop key="hubspot-oauth-version">2.0</prop>
<prop key="hubspot-oauth-clientid">your-mobileforcecpq-hubspot-instance-clientid</prop>
<prop key="hubspot-oauth-clientsecret">your-mobileforcecpq-hubspot-instance-clientsecret</prop>
<prop key="hubspot-oauth-authurl">https://app.hubspot.com/oauth/<instanceid>/authorize</prop>
<prop key="hubspot-oauth-accesstokenurl">https://api.hubapi.com/oauth/v1/token</prop>
<prop key="hubspot-oauth-redirecturi">https://apps.mobileforcesoftware.com/mobileforce/oauth_redirect</prop>
<prop key="hubspot-oauth-scope">
oauth files crm.objects.companies.read crm.objects.companies.write crm.schemas.companies.read crm.objects.deals.read crm.objects.deals.write crm.schemas.deals.read crm.objects.contacts.read crm.schemas.contacts.read crm.objects.owners.read crm.objects.line_items.read crm.objects.line_items.write
</prop>
<prop key="hubspot-oauth-accessmethod">header</prop>
<prop key="hubspot-oauth-clientauthmethod">requestparams</prop>
<prop key="hubspot-oauth-granttype">authorization_code</prop>
<prop key="hubspot-oauth-responsetype">code</prop>
<prop key="hubspot-datatable-url">https://apps.mobileforcesoftware.com/adapters/hubspot-crm-v3/schema.php</prop>
<prop key="hubspot-hubspotTables">Contacts,Companies,Deals,Owners,Pipelines,Stages</prop>

Note
If additional HubSpot tables (standard or custom) are being used in CPQ, then those table names will also need to be specified in the property hubspot-hubspotTables. For example, if you use a HubSpot table called sites, you'd need to add:

<prop key="hubspot-hubspotTables">Contacts,Companies,Deals,Owners,Pipelines,Stages,sites</prop>

Similarly, any additional custom objects being read or written by CPQ would necessitate additional values crm.objects.custom.read and crm.objects.custom.write in the property hubspot-oauth-scope

<prop key="hubspot-oauth-scope">oauth files crm.objects.companies.read crm.objects.companies.write crm.schemas.companies.read crm.objects.deals.read crm.objects.deals.write crm.schemas.deals.read crm.objects.contacts.read crm.schemas.contacts.read crm.objects.owners.read crm.objects.line_items.read crm.objects.line_items.write e-commerce crm.objects.custom.read crm.objects.custom.write crm.schemas.custom.read</prop>

The Mobileforce CPQ card for HubSpot is found on the right panel of the HubSpot Screen (if the Mobileforce App is installed on the HubSpot instance). If this card is not visible to you, it means that Mobileforce CPQ has not been installed on your HubSpot instance. This card is the starting point for all Mobileforce CPQ actions. Here's an example CPQ card:

This card includes a list of most recent Mobileforce CPQ quotes created for this HubSpot instance, together with the quote status and effective/expiration dates for each quote. In addition, the card includes the action buttons to "create a new CPQ proposal" and other actions that are accessed from the "Actions" button. In addition, the Mobileforce CPQ card also provides a mechanism to Setup Mobileforce CPQ, which is meant only for Admins.

The HubSpot CPQ card filters quotes by their opportunity ID if the quote's summary has an 'opportunity_id' field in its watched inputs.

The following ADL properties can be used by the Mobileforce Solutions Engineer to customize the HubSpot CPQ card:

  1. hubspot-card-company-name-field: Name of the quote field that contains the company's name. Must be a watched input. Default is 'account'.
  2. hubspot-card-company-id-field: Name of the quote field that contains the HubSpot ID of the company. Must be a watched input. Default is 'account_id'.
  3. hubspot-card-deal-name-field: Name of the quote field that contains the deal's name. Must be a watched input. Default is 'opportunity'.
  4. hubspot-card-deal-id-field: Name of the quote field that contains the HubSpot ID of the deal. Must be a watched input. Default is 'opportunity_id'.
  5. hubspot-card-screen-id-quote-list: ADL screen path of the List Quotes screen.
  6. hubspot-card-screen-id-new-quote: ADL screen path of the New Quote screen.
  7. hubspot-card-screen-id-setup: ADL screen path of the CPQ Setup screen.
  8. hubspot-card-user-guide-url: URL of the page that the card should go to when a user clicks on the 'CPQ User Guide' action.
  9. hubspot-card-label-cpq-setup: Label for the 'CPQ Setup' action.
  10. hubspot-card-label-cpq-user-guide: Label for the 'CPQ User Guide' action.
  11. hubspot-card-label-cpq-proposals: Label for the 'CPQ Proposals' action.
  12. hubspot-card-label-new-cpq-proposal: Label for the 'New CPQ Proposal' action.
  13. hubspot-card-label-quote-title: Label for a single quote, (e.g., 'Quote $%s').

Note
Some Mobileforce apps on HubSpot are customized with additional functionality: e.g., to allow access to additional HubSpot APIs, such as Products or Custom objects. These apps will need additional OAuth scopes, (e.g., 'e-commerce' or 'crm.objects.custom.read crm.objects.custom.write crm.schemas.custom.read’. If these OAuth scopes were added, HubSpot users will also need the corresponding permissions, (e.g. ’Manage Product Libraries’ or ‘Custom Views’)

To access HubSpot products within MobileForce as a non-super-admin, you need the ‘e-commerce’ scope. Additionally, all non-super-admin HubSpot users need the ‘Manage Products Libraries’ permission.

To set up permissions for specific users in HubSpot, go to  
HubSpot Settings --> Account Setup --> Users and Teams --> <select a specific user> --> Edit permissions.

The following screenshot shows permissions for a user that can be controlled:

In addition, make sure that the following prop keys are set to given values below

<prop key=“auth-param-prefix”>hubspot-</prop>
<prop key=“auth-datatable-param-prefix”>hubspot-</prop>
<prop key=“auth-datatable-schema-url”>https://apps.mobileforcesoftware.com/adapters/hubspot-crm-v3/schema.php#contacts</prop>
<prop key=“auth-datatable-filter”></prop>
<prop key="cpq-param-prefix">hubspot-</prop>

Note about HubSpot OAuth Admin
Upon a successful login into MobileForce via HubSpot, an OAuth access token is created for the logged in user if no such token exists. If it does exist, that token is used. This token has the OAuth scopes incorporated into it. Consequently if you are logged in as a user, and then change the OAuth scopes for that app, that user will still be using the old scopes.

To change the user's OAuth token, a Mobileforce admin must delete the OAuth token for the user so that HubSpot would generate a new one with the new scopes. This deletion can only be performed by a Mobileforce Admin using Mobileforce Manager to list, view, and delete OAuth tokens associated with an account. Please contact Mobileforce Support (opens in new tab) if you need the OAuth token for your App deleted (presumably because you changed the OAuth scopes).

Debugging HubSpot Install Issues

HubSpot users install Mobileforce CPQ from the HubSpot Marketplace. If this installation has issues or doesn't complete, here are some steps to follow:

(Only for Mobileforce Solution Engineer)

  1. First go into MF DBMS to see if customer account was even created when it was previously attempted. Specifically, look for an account with the prefix: hubspot266… – if you don't find it, you know that the MF account was never created (i.e., no database entry in the dbms)

  2. Then go into HubSpot > Settings > Integrations > Connected Apps and in to Mobileforce CPQ and hit Uninstall – This would uninstall the previous Mobileforce CPQ.

  3. Then go into HubSpot Marketplace and re-install Mobileforce CPQ. This time it should work.