HubSpot v1.0.0

About the connector

HubSpot is a CRM platform with all the software, integrations, and resources you need to connect marketing, sales, content management, and customer service. This integration helps get, create, update or delete a ticket.

This document provides information about the HubSpot Connector, which facilitates automated interactions, with a HubSpot server using FortiSOAR™ playbooks. Add the HubSpot Connector as a step in FortiSOAR™ playbooks and perform automated operations with HubSpot.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 7.3.2-2150

HubSpot Version Tested on: v1

Authored By: Fortinet

Certified: Yes

Getting the Client ID and Client Secret from HubSpot

To support OAuth authentication for HubSpot, you need to get Client ID and Client Secret from HubSpot by creating an application on HubSpot developer account.

1. Open your HubSpot developer account and navigate to Apps tab.
2. Click the Create App button.
3. Enter the Public app name under the App Info tab and Redirect URLs under Auth tab.
4. Click Create App.
   NOTE: The Redirect URL is where users must be redirected to after granting access to your app. If you are unsure about what to set as a redirect URL, use http://localhost.

Getting Access Tokens

Ensure that the required scopes are granted. Scopes determine the permissions your app has to access data or perform actions in HubSpot. The 3 minimum required scopes are: oauth, tickets, crm.objects.owners.read.

1. Copy the install URL (OAuth) from the Auth tab. It is generated based on the app credentials, redirect URL, and scope configuration you specify while creating the app.
2. Enter the install URL where you are prompted to grant permissions for your HubSpot APIs. You are then automatically redirected to a link with the following structure: REDIRECT_URI?code=AUTH_CODE.
3. Enter the following details in the Connector Configuration dialog in your FortiSOAR instance:
   1. Copy the AUTH_CODE (without the code= prefix) and paste it in the Authorization Code parameter.
   2. Enter your client ID in the Client ID field.
   3. Enter your client secret in the Client Secret field.
   4. Enter your redirect URL in the Redirect URL field. By default, it is set to http://localhost.

Installing the connector

Use the Connector Store to install the connector. For a detailed procedure to install a connector, click here.

You can also use the yum command as a root user to install the connector:

yum install cyops-connector-hubspot

Prerequisites to configuring the connector

• You must have acquired authentication tokens to access the HubSpots APIs. For more information see the Getting Access Tokens section.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the HubSpot server.

Minimum Permissions Required

To run all the connector actions, you need the following permissions:

• oauth
• tickets
• crm.objects.owners.read

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the HubSpot connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter	Description
Server URL	The service-based URI to connect and perform automated operations.
Client ID	Unique APP ID of the HubSpot application that is used to create an authentication token required to access the API.
Client Secret	Unique APP Secret of the HubSpot application that is used to create an authentication token required to access the API.
Authorization Code	The authorization code that you acquired during the Granting Scopes step.
Redirect URL	The redirect_uri of your app, where authentication responses can be sent and received by your app. It must exactly match one of the redirect_uri you registered in the app registration portal.
Verify SSL	Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set to True.

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations:

Function	Description	Annotation and Category
Get All Tickets	Retrieves a list of all tickets from HubSpot up to the maximum of 100 per request. You can get a more detailed list by specifying ticket properties and other input parameters.	get_all_tickets Investigation
Get Tickets By ID	Retrieves specific tickets from HubSpot based on the Ticket IDs, properties, and other input parameters you have specified.	get_tickets_by_id Investigation
Create Tickets	Creates new tickets – single or multiple – based on the ticket properties you have specified.	create_tickets Investigation
Update Tickets	Updates tickets – single or multiple – based on the ticket properties you have specified.	update_tickets Investigation
Delete Tickets	Deletes the tickets – single or multiple – based on the ticket ID you have specified.	delete_tickets Investigation
Get Tickets Changes Log	Retrieves the list of all the changes made to the ticket. Returns a maximum of 1000 changes, starting with the oldest change within the last 24 hours. Changes prior to this period are not returned.	get_tickets_changes_log Investigation
Get Ticket Pipelines	Retrieves a list of all pipelines for the configured account.	get_ticket_pipelines Investigation
Get Owners List	Retrieves the list of owners associated with a HubSpot account.	get_owners_list Investigation

operation: Get All Tickets

Input parameters

Parameter	Description
Ticket Properties	Specify ticket properties to include in the response (e.g., subject, content, hs_pipeline, hs_pipeline_stage). You can specify multiple comma-separated values for ticket properties.
Ticket Properties With History	Specify ticket properties to include in the response (e.g., subject, content, hs_pipeline, hs_pipeline_stage). You can specify multiple comma-separated values for ticket properties and get the full version history for the specified property.
Offset	Specify an offset value to get the next set of results. If hasMore is true in the previous response, use the returned offset value to get the next set of records.

Output

The output contains the following populated JSON schema:
{
"objects": [
{
"objectType": "",
"portalId": "",
"objectId": "",
"properties": {
"subject": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"content": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"hs_pipeline": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"hs_pipeline_stage": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
}
},
"version": "",
"isDeleted": ""
}
],
"hasMore": "",
"offset": ""
}

operation: Get Tickets By ID

Input parameters

Parameter	Description
Ticket ID	Specify the ticket ID to retrieve from HubSpot. You can specify multiple comma-separated list of ticket IDs.
Ticket Properties	Specify ticket properties to include in the response (e.g., subject, content, hs_pipeline, hs_pipeline_stage). You can specify multiple comma-separated values for ticket properties.
Ticket Properties With History	Specify ticket properties to include in the response (e.g., subject, content, hs_pipeline, hs_pipeline_stage). You can specify multiple comma-separated values for ticket properties and get the full version history for the specified property.
Include Deleted	Select the checkbox to retrieve the deleted records. By default, deleted records are not returned by the API.

Output

The output contains the following populated JSON schema:
{
"objectType": "",
"portalId": "",
"objectId": "",
"properties": {
"subject": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"created_by": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"content": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"hs_pipeline": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"hs_pipeline_stage": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
}
},
"isDeleted": ""
}

operation: Create Tickets

Input parameters

Parameter	Description
Create	Select one of the following options to create tickets: Single Ticket Multiple Tickets You can create up to 100 tickets in a single request.
Ticket Name	(Conditional - Appears on selecting Single Ticket in Create field) Specify the name of the ticket you want to create on HubSpot.
Pipeline	(Conditional - Appears on selecting Single Ticket in Create field) Specify the pipeline ID containing the ticket. You can retrieve this parameter value from Get Ticket Pipelines action.
Ticket Status	(Conditional - Appears on selecting Single Ticket in Create field) Specify the ticket's stage in its pipeline. You can retrieve this parameter value from Get Ticket Pipelines action.
Ticket Description	(Conditional - Appears on selecting Single Ticket in Create field) Specify a description of the ticket you want to create on HubSpot.
Source	(Conditional - Appears on selecting Single Ticket in Create field) Select the channel where the ticket was originally submitted, from the following options: CHAT EMAIL FORM PHONE
Ticket Owner	(Conditional - Appears on selecting Single Ticket in Create field) Specify the ID of the ticket's owner. You can retrieve this parameter value from Get Owners List action.
Priority	(Conditional - Appears on selecting Single Ticket in Create field) Select the level of attention needed on the ticket from the following options: LOW MEDIUM HIGH
Create Date	(Conditional - Appears on selecting Single Ticket in Create field) Select the creation date of the ticket. By default, its created with current date and time.
Other Properties	(Conditional - Appears on selecting Single Ticket in Create field) Specify a list of additional ticket properties that you want to set for this new ticket.
Ticket Properties	(Conditional - Appears on selecting Multiple Tickets in Create field) Specify an array of list of ticket properties you want to set for each new ticket. You must set the ticket pipeline and stage when creating a new ticket.

Output

The output contains the following populated JSON schema:
{
"objectType": "",
"portalId": "",
"objectId": "",
"properties": {
"hs_lastmodifieddate": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"subject": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"hs_pipeline": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"createdate": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"content": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"hs_pipeline_stage": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"time_to_close": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": [],
"sourceMetadata": ""
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
}
},
"isDeleted": ""
}

operation: Update Tickets

Input parameters

Parameter	Description
Update	Select one of the following options to update tickets: Single Ticket Multiple Tickets You can update up to 100 tickets in a single request.
Ticket ID	Specify the Ticket ID you want to update on HubSpot. You can retrieve this parameter value from Get All Tickets action.
Ticket Name	(Conditional - Appears on selecting Single Ticket in Update field) Specify the name of the ticket you want to update on HubSpot.
Pipeline	(Conditional - Appears on selecting Single Ticket in Update field) Specify the pipeline ID containing the ticket. You can retrieve this parameter value from Get Ticket Pipelines action.
Ticket Status	(Conditional - Appears on selecting Single Ticket in Update field) Specify the ticket's stage in its pipeline. You can retrieve this parameter value from Get Ticket Pipelines action.
Ticket Description	(Conditional - Appears on selecting Single Ticket in Update field) Specify a description of the ticket you want to update on HubSpot.
Source	(Conditional - Appears on selecting Single Ticket in Update field) Select the channel where the ticket was originally submitted, from the following options: CHAT EMAIL FORM PHONE
Ticket Owner	(Conditional - Appears on selecting Single Ticket in Update field) Specify the ID of the ticket's owner. You can retrieve this parameter value from Get Owners List action.
Priority	(Conditional - Appears on selecting Single Ticket in Update field) Select the level of attention needed on the ticket from the following options: LOW MEDIUM HIGH
Create Date	(Conditional - Appears on selecting Single Ticket in Update field) Select the creation date of the ticket to update on HubSpot.
Other Properties	(Conditional - Appears on selecting Single Ticket in Update field) Specify a list of additional ticket properties that you want to update for this ticket.
Ticket Properties	(Conditional - Appears on selecting Multiple Tickets in Update field) Specify an array with each element containing the ID of the ticket to update and a list of properties to update for that ticket.

Output

The output contains the following populated JSON schema:
{
"objectType": "",
"portalId": "",
"objectId": "",
"properties": {
"hs_lastmodifieddate": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"hs_ticket_priority": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"content": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
},
"status": {
"versions": [
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
},
{
"name": "",
"value": "",
"timestamp": "",
"source": "",
"sourceVid": []
}
],
"value": "",
"timestamp": "",
"source": "",
"sourceId": ""
}
},
"isDeleted": ""
}

operation: Delete Tickets

Input parameters

Parameter	Description
Ticket ID	Specify the ticket ID to delete from HubSpot. You can specify multiple comma-separated list of ticket IDs.

Output

The output contains the following populated JSON schema:
{
"status": "",
"message": ""
}

operation: Get Tickets Changes Log

Input parameters

Parameter	Description
Timestamp	Specify the timestamp of the last change you pulled.
Change Type	Specify the last change type you pulled. NOTE: Specify the Timestamp and Object ID fields when specifying value in this field.
Object ID	Specify the ID of the last object for which you received changes. NOTE: Specify the Timestamp and Change Type fields when specifying value in this field.

Output

The output contains the following populated JSON schema:
{
"timestamp": "",
"changeType": "",
"objectId": "",
"changes": {
"changedProperties": [],
"newAssociations": [],
"removedAssociations": [],
"newListMemberships": [],
"removedListMemberships": []
}
}

operation: Get Ticket Pipelines

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
"results": [
{
"pipelineId": "",
"createdAt": "",
"updatedAt": "",
"objectType": "",
"label": "",
"displayOrder": "",
"active": "",
"stages": [
{
"stageId": "",
"createdAt": "",
"updatedAt": "",
"label": "",
"displayOrder": "",
"metadata": {
"ticketState": ""
},
"active": ""
}
],
"default": ""
}
]
}

operation: Get Owners List

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
"portalId": "",
"ownerId": "",
"type": "",
"firstName": "",
"lastName": "",
"email": "",
"createdAt": "",
"updatedAt": "",
"remoteList": [
{
"portalId": "",
"ownerId": "",
"remoteId": "",
"remoteType": "",
"active": ""
}
]
}

Included playbooks

The Sample - HubSpot - 1.0.0 playbook collection comes bundled with the HubSpot connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the HubSpot connector.

• Create Tickets
• Delete Tickets
• Get All Tickets
• Get Owners List
• Get Ticket Pipelines
• Get Tickets By ID
• Get Tickets Changes Log
• Update Tickets

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.