Skip to content

Directly import JSON formatted data to your Notion databases.

License

Notifications You must be signed in to change notification settings

NikkelM/JSON-to-Notion

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

19 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Import JSON files to Notion

JSON to Notion banner

Utility that is able to "import" JSON files to Notion - for cases where a CSV file is simply not available, and the conversion from JSON to CSV would be too complicated.

Setup

Run npm install to install the required dependencies first.

Following this, create a config.json file in the root directory of the project and fill it with your desired configuration.

If you haven't already done so, you can obtain a Notion integration key by creating an (internal) Notion integration for your workspace. You can follow this guide to learn how to do so. You will need this key to run the integration locally.

IMPORTANT: Don't forget to connect the integration to your database, as described in the guide! Otherwise, the import won't work.

Usage

After providing the config.json configuration file, you can run the script using

node index.js

The script will now automatically import the specified JSON properties to your Notion database.

Configuration

Schema validation

The project provides an extensive JSON validation schema for the required configuration file. This makes sure that the script is able to run without any issues.

The schema can be found in the config.schema.json file and used within your config.json by adding the following property:

"$schema": "config.schema.json"

NOTE: The script will test your provided config.json against this schema, so make sure your configuration is valid.

Properties

The following is a list of all configuration items, their defaults and the values they can take.

Top-level properties

notionIntegrationKey

The secret integration key for your Notion integration. Find it on your integration dashboard after creating a new integration on https://www.notion.so/my-integrations

Type Default value Possible values Required
string "" A valid Notion integration key Yes
notionDatabaseId

The ID of the database you want to run the integration on. You can find the ID in the URL of your database, e.g. https://www.notion.so/myworkspace/your-database-id

Type Default value Possible values Required
string "" A valid Notion database ID Yes
inputFile

The JSON file to import to Notion.

Type Default value Possible values Required
string "input.json" A valid JSON file(path) Yes
skipExisting

Whether to skip existing entries in the database. If set to true, the script will only import entries that do not exist in the database yet.

Type Default value Possible values Required
object See item below See sections below No
{
	"enabled": false,
	"jsonKey": "keyInJSON",
	"notionProperty": "ItemId",
	"propertyType": "number"
}

Possible values

enabled

Whether to skip existing entries in the database.

Type Default value Possible values Required
boolean false true or false Yes

jsonKey

The key in the JSON input that should be compared to the value of the notionProperty.

Type Default value Possible values Required
string "keyInJSON" A key that exists in the items of the input file Yes

notionProperty

The name of the field in the Notion database that should be compared to the value of the jsonKey.

Type Default value Possible values Required
string "ItemId" An existing Notion property name Yes

propertyType

The type of the property in the Notion database that should be compared to the value of the jsonKey. Not all property types are supported.

Type Default value Possible values Required
string "rich_text" "rich_text", "title", "number", "select" or "url" Yes
missingInInputPolicy

Decide what to do with entries in the database that have the given notionProperty set, but do not exist in the input file (i.e., an updated dataset no longer contains this entry). If this key is omitted, no action is taken and such entries are ignored.

Type Default value Possible values Required
object See item below See sections below No
{
	"policy": "noAction",
	"jsonKey": "keyInJSON",
	"notionProperty": "ItemId",
	"propertyType": "number",
	"alertedNotionProperty": "ItemName",
	"alertedPropertyType": "title"
}

Possible values

policy

The action to take when an entry exists in the database whose notionProperty value does not exist in the input file.

Type Default value Possible values Required
string noAction noAction, alert or remove Yes

jsonKey

The key in the JSON input that should be compared to the value of the notionProperty.

Type Default value Possible values Required
string "keyInJSON" A key that exists in the items of the input file Yes

notionProperty

The name of the field in the Notion database that should be compared to the value of the jsonKey.

Type Default value Possible values Required
string "ItemId" An existing Notion property name Yes

propertyType

The type of the property in the Notion database that should be compared to the value of the jsonKey. Not all property types are supported.

Type Default value Possible values Required
string "rich_text" "rich_text", "title", "number", "select" or "url" Yes

alertedNotionProperty

The name of the field in the Notion database that should be used for logging objects missing in the input file.

Type Default value Possible values Required
string "ItemName" An existing Notion property name No

alertedPropertyType

The type of the property used for the logging. Not all property types are supported.

Type Default value Possible values Required
string "title" "rich_text", "title", "number", "select" or "url" Yes, if alertedNotionProperty is set
writeErroredObjectsToFile

Whether to write the input objects that failed to be imported to Notion to a file. This speeds up the process of cleaning up those errors and trying again.

Type Default value Possible values Required
boolean true true or false No
extraProperties

Extra properties to add to the Notion database. These properties will be added to every row in the database.

Type Default value Possible values Required
array See item below See sections below No
[
	{
		"notionPropertyName": "Imported by",
		"propertyValue": "Imported using JSON to Notion",
		"notionPropertyType": "rich_text"
	}
]

Possible values

notionPropertyName

The Notion property name to map to the JSON key.

Type Default value Possible values Required
string "Imported by" A valid Notion property name Yes

notionPropertyType

The type of the Notion property. Note: Not all property types are supported as of now. Unsupported types that may get supported later on: status, files, checkbox, email, phone number. If you would like one of these supported, please open an issue.

Type Default value Possible values Required
string "rich_text" "rich_text", "title", "number", "select", "multi_select", "date" or "url" Yes

propertyValue

The value to add to the Notion property.

Type Default value Possible values Required
string "Imported using JSON to Notion" The type of object depends on the notionPropertyType and will be passed directly to the Notion API. Yes
propertyMappings

The mapping of JSON keys to Notion property names. If an existing JSON key is not mapped, it will be ignored.

Type Default value Possible values Required
array See item below See sections below Yes, at least one item
[
	{
		"jsonKey": "keyInJson",
		"notionPropertyName": "keyInNotion",
		"notionPropertyType": "rich_text",
		"nestedObjectPolicy": {
			"policy": "useNamedProperty",
			"namedProperty": "nameOfNestedProperty"
		}
	}
]

propertyMappings

jsonKey

The JSON key to map to the Notion property.

Type Default value Possible values Required
string "keyInJson" A key that exists in the items of the input file Yes
notionPropertyName

The name of the Notion property to map to the JSON key.

Type Default value Possible values Required
string "keyInNotion" An existing Notion property name Yes
notionPropertyType

The type of the Notion property. Note: Not all property types are supported as of now. For multi_select, the input string will be split along , to create multiple entries. Combine this with the nestedObjectPolicy "concatenateProperties".

Type Default value Possible values Required
string "rich_text" "rich_text", "title", "number", "select", "multi_select", "url", "date", "cover" or "icon" Yes
nestedObjectPolicy

The policy to use when the value of the specified JSON key contains another JSON object. This is useful when the JSON value is an object that contains multiple properties that should be mapped to a single Notion property.

Type Default value Possible values Required
object See item below See sections below No
{
	"policy": "useNamedProperty",
	"namedProperty": "nameOfNestedProperty"
}

Possible values

policy

The policy to use when the value of the specified JSON key contains another JSON object.

Type Default value Possible values Required
string "useNamedProperty" "useNamedProperty", "concatenateProperties" or "usePriorityList" Yes

namedProperty

The name of the property to use when the policy is set to useNamedProperty.

Type Default value Possible values Required
string "namedProperty" A key that exists in the items of the input file Yes, if the policy is useNamedProperty

priorityList

The prioritized list of properties to use when the policy is set to usePriorityList. The script will use the value of the property with the highest priority.

Type Default value Possible values Required
array See item below A list of strings Yes, if the policy is usePriorityList
[
	"highestPriorityProperty",
	"secondHighestPriorityProperty"
]

Related projects

If you are using Notion to organize your Steam game library, you might be interested in the Notion Steam API integration project, an integration that automatically retrieves information for Notion entries that contain a Steam App ID.

Similarly, you can use the Game Pass API to retrieve information about all games currently available on Game Pass, and then import that information using this tool.

Feedback

If you have any question, feedback or feature requests, feel free to open an issue.