Artisan IMG > Notion (notion) (510d1baf-e5d7-4e21-885d-28f6a37a36e3)
Artisan IMG > Notion (notion) (510d1baf-e5d7-4e21-885d-28f6a37a36e3)

Notion
3.0

Notion is an all-in-one workspace where you can write, plan, collaborate and get organized.

Overview
Copy

Notion is an application that provides components such as notes, databases, kanban boards, wikis, calendars, and reminders. Users can connect these components to create their own systems for knowledge management, note-taking, data management, project management, among others.

API Information
Copy

The Notion connector has the following Base URL: https://api.notion.com/v1. More information can be found on their main API documentation (v1) site. Details regarding their API limitations can be found here.

Authentication
Copy

Within the workflow builder, highlight the Notion connector.

In the Notion connector properties panel to the right of the builder, click on the Authenticate tab and the 'New authentication' button.

This will result in a Tray.io authentication pop-up modal. The first page will ask you to name your authentication and select the type of authentication you wish to create ('Personal' or 'Organisational').

The next page will ask you to choose your 'Service Type'. You can choose to create either a token-based authentication ('API Key') or an OAuth 2.0 authentication ('OAuth2.0').

Token-based authentication is used in internal integrations, and an OAuth 2.0 authentication is required for public integrations. To create a token-based authentication select 'API Key' from the drop-down menu and follow the instructions from the API Key section below. To create an OAuth 2.0 authentication select 'OAuth2.0' and follow the instructions from the OAuth 2.0 section below.

API Key
Copy

If you select 'API Key' from the drop-down menu you will be asked to enter your API Key. Note that this refers to your Integration API key, otherwise known as the "Internal Integration Token".

Before proceeding, note that you will need to be an administrator in order to get the API key.

There are two ways you can access your API key, one is through your Notion integrations page:

- images combined!

The other is through the Notion application. Head to 'Settings & Members' > 'Integrations'. Click on the horizontal hamburger icon available on the right-hand corner to display the copy token option.

- images combined!

Once you have added these fields to your Tray.io authentication pop-up window, click the 'Create authentication' button.

Go back to your settings authentication field (within the workflow builder properties panel), and select the recently added authentication from the drop-down options now available.

Your connector authentication setup should now be complete.

OAuth 2.0
Copy

If you select 'OAuth2.0' from the drop-down menu you will be asked to enter your 'Client ID' and 'Client Secret'.

To find your 'Client ID' and 'Client Secret' visit your Notion integrations page and click the public integration for which you are creating an authentication.

Once you have added these fields to your Tray.io authentication pop-up window, click the 'Create authentication' button.

Next, you will be redirected to a Notion pop-up window. Click 'Select pages' to choose which pages to grant access to.

Now you can select the Notion pages you want to allow access to, then click 'Allow access'.

Go back to your settings authentication field (within the workflow builder properties panel), and select the recently added authentication from the drop-down options now available.

Your connector authentication setup should now be complete.

Available Operations
Copy

The examples below show one or two of the available connector operations in use.

Please see the Full Operations Reference at the end of this page for details on all available operations for this connector.

Notes on using Notion
Copy

Integrations vs Users
Copy

End users should take into account that the concepts of a Notion User and a Notion Integration are extremely similar.

"In Notion, Integrations function like a special type of User. Once an admin has added an Integration to a workspace, members can grant it's access to a page from the page’s Share menu."

Integrations:

  • Can be added to workspaces like Users.

  • They have fewer access privileges by design than a normal User. Because of this they must to be given explicit permission to work with any page.

  • When you create an Integration it doesn't actually belong to anyone. Think of it as an account that multiple people can use.

Integrations are in effect the same Users, but with a smaller scope.

Get User
Copy

This is why in operations such as 'Get user', your dropdown options will list User accounts as well as any Integrations associated with your authentication.

If you are ever confused as to which is which, call the API and check the Output panel. Both User's and Integration's object values will state that they are the same and in effect seen as an"object": "user".

It is their type property which will indicate if the call was made to an Integration: "type": "bot" or a User: "type": "person".

FALLBACK VALUES: Tray.io now offer fallback values. This can be used for occasions when you know that data being returned will be inconsistent in some way. Check out the fallback values documentation page for more details.

NEED A TRIGGER?: Remember that as a user you can always create your own service trigger should you require one. Check out the Webhook Trigger documentation page for more details.

Using the Raw HTTP Request ('Universal Operation')
Copy

As of version 1.0, you can effectively create your own operations.

This is a very powerful feature that you can use when there is an endpoint in Notion that is not used by any of our operations.

To use this you will first of all need to research the endpoint in the Notion API documentation v2021-05-13, to find the exact format that Notion will be expecting the endpoint to be passed in.

Note that you will only need to add the suffix to the endpoint, as the base URL will be automatically set (the base URL is picked up from the value you entered when you created your authentication).

The base URL for Notion is: https://api.notion.com/v1

For example, say that the 'List databases' operation did not exist in our Notion connector, and you wanted to use this endpoint. You would use the Notion API docs to find the relevant endpoint - which in this case is a GET request called: databases.

More details about this endpoint can be found here.

As you can see there is also the option to include a query parameter, should you wish to do so. So if you know what your method and endpoint, you can get the list of available databases associated with "this" particular integration with the following settings:

Method: GET

Endpoint: databases

Body Type : none

Final outcome being: https://api.notion.com/v1/databases

Example Usage
Copy

TRAY POTENTIAL: Tray.io is extremely flexible. By design there is no fixed way of working with it - you can pull whatever data you need from other services and work with it using our core and helper connectors. This demo which follows shows only one possible way of working with Tray.io and the notion connector. Once you've finished working through this example please see our Introduction to working with data and jsonpaths page and Data Guide for more details.

Below is an example of a way in which you could potentially use the Notion connector, in order to to create a new page within a Notion Workspace every time a client status is updated to "Customer - Direct". I.e., when a potential client becomes a qualified customer as opposed to a lead or prospect etc.

EXTRA AUTHS: In order to complete this workflow, you will also need to be authenticated with the Salesforce connector.

The steps will be as follows:

  1. Setup using a Salesforce trigger and search for the ID of the integration you wish to use.

  2. Using a Notion step, find the ID of the Workspace you wish to utilise.

  3. Find all records whose Account ID is equal to that of a Customer, and return their associated data.

  4. Double check that the field name has indeed been updated as expected.

  5. Create a new notion page that contains the customer information.

Your completed workflow should look similar to this:

1 - Setup Salesforce Trigger
Copy

Here we are using the Salesforce Trigger but note that you can use any trigger you like. Be it Manual, Scheduled, Callable etc.

For testing purposes, you may wish to swap out the Salesforce Trigger for a Manual one for now, as it will mean you can trigger your runs more easily.

With your trigger in place, set the operation to 'On Record Field Change'. There are two mandatory properties. The first is 'Record type'. In this example, we are only interested in triggering our workflow when an Account record changes, so we set the value to 'Account'.

The second property is 'Field to watch'. This is referring to the specific field name we want our workflow to trigger on. Select 'Account type'. This field is what updates once a lead has become a fully-fledged customer.

Also, make sure to check the box 'Trigger for created records?'. This makes sure we include any new Account records that start off as customers directly.

Now our workflow will only trigger once the field 'Account type' within a (new or old) Account record is updated.

Feel free to re-name your steps as you go along to make things clearer for yourself and other users. The operation names themselves often suffice.

2 - Get Workspace ID
Copy

Add a Notion connector. Set the operation to 'Search'. As this workflow is designed to create a new page every time a customer has been secured, we need to make sure the page is created under the right workspace. For that we need to find and specify the Workspace ID.

Here we already have a 'Customers' Workspace within Notion that we want to place all the new customer pages within. Select the equivalent in your own workflow. If you have none, create one and refresh the builder to have the new option appear.

IMPORTANT!: If you have more than one workspace with the exact same name, be warned that the Notion API will return the ID of all the Workspaces associated with the same name. Therefore it is good practice to name each of your Workspaces uniquely.

Note that there are several sorting properties as well, should you wish to use them.

In order for the builder to be able to view/ query this workspace, make sure that it is already shared with the right User accounts and Integrations.

You can check/ do this through the sharing option (the button in the top right corner of your workspace):

Now when your workflow is triggered, Notion will return the ID of the Customer Workspace you wish to create your pages under.

USER TIP: It is worth noting that this step is not necessary for every run once you retrieve the Workspace ID and can be removed after. Provided you keep the ID of the Workspace somewhere safe, you can simply copy the ID into any other steps/ operations you may need going forward. Generally it is good to remove unnecessary steps where possible in order to make your workflow run efficiently and more effectively.

3 - Find records
Copy

Next, add another Salesforce connector and set the operation to 'Find records'.

Once more specify the 'Record type' as 'Account'. Next choose the fields you wish to populate your new Notion customer page with. As this is a simple example, we are only going to request the 'Account name' and 'Account type'.

The next section deals with the conditions that need to be met for returning this type of record and data. Here, we demonstrate that we only wish to find records that where the 'Account ID' is 'Equal to' 'Customer - Direct'.

This latter property is being auto-generated via the use of the connector-snake, with information coming in from the trigger.

When your workflow gets to this step all Account records with the 'Account ID' field 'Customer - Direct' (and their associated data) will be returned.

4 - Check field name
Copy

Search for the Boolean connector within your connector panel, and drag it into your workflow as your next step. Set your operation to 'Boolean condition'.

The Boolean connector allows you to iterate through a list of results. In this example, we will use it to iterate through the list of Account records found within the previous Salesforce connector step ('Find records').

In order to specify the list you want to loop through, start by using the list mapping icon (found next to the list input field, within the properties panel) to generate the connector-snake.

While hovering over the 'Find records' step (with the tail end of the connector-snake), select Type from the list of output properties displayed. This will auto-populate a jsonpath within your list input field, and update the type selector to jsonpath.

Set the comparison type as 'Equal to' and the '2nd value' as 'Customer - Direct'. Make sure the 'Strictness' property is set to 'Satisfy ALL conditions'

For more clarification on the pathways you have available, open the Debug panel to view your step's Input and Output.

JSONPATHS: For more information on what jsonpaths are and how to use jsonpaths with Tray.io, please see our pages on Basic data concepts and Mapping data between steps

CONNECTOR-SNAKE: The simplest and easiest way to generate your jsonpaths is to use our feature called the Connector-snake. Please see the main page for more details.

The point of this step is to double check that the 'Account ID' field really is set to 'Customer - Direct'. This kind of check is always useful because no system is flawless (the API call might fail or another field type might slip by etc).

5 - Create page
Copy

The last step is to drag a Notion connector inside the Boolean connector step itself. Set the operation to 'Raw HTTP Request'.

Set the 'Method' to 'POST' and the 'URL' to 'Endpoint'. This means only the endpoint of the URL will be needed as the base should be set automatically. As we wish to create a page, the endpoint in question is 'pages' (as in accordance with the (Notion API)[https://developers.notion.com/reference/post-page]).

You will need to set your 'Headers' as well. Make sure the 'Key' is 'Content-Type' and the 'Value' is 'application/json'. Both input types are stings.

Set the 'Body Type' to 'raw'. Click on the 'Edit' button to specify the information you wish to populate your new customer page with.

As you can see from the sample code below, we have used interpolation to automatically pull in the Workspace and customer data from the Salesforce records we collected earlier.

INTERPOLATION: When you wish to include JSON generated data within another input/output result, use our Interpolation method as described here.

1
{
2
"parent": {
3
"type": "page_id",
4
"page_id": "{$.steps.notion-1.results[0].id}"
5
},
6
"properties": {
7
"title": {
8
"title": [
9
{
10
"text": {
11
"content": "{$.steps.salesforce-1.records[0].Name}"
12
}
13
}
14
]
15
}
16
},
17
"children": [
18
{
19
"object": "block",
20
"type": "paragraph",
21
"paragraph": {
22
"text": [
23
{
24
"type": "text",
25
"text": {
26
"content": "{$.steps.salesforce-1.records[0].Type}"
27
}
28
}
29
]
30
}
31
}
32
]
33
}

Once run, you should be able to see your new customer page within your customer Workspace.

When you open said page, the data from your Salesforce records will also be included.

Congratulations! your workflow is now complete! Every time an Account record (old or new) has its Account ID field updated to Customer - Direct, your workflow will automatically create a new page within your Notion Customer Workspace with all the associated field data specified earlier.

BEST PRACTICES: Whenever you do decide to create your own workflow, be sure to check out some of our key articles such as: