# Trying to make sense of Integrations doc and Notion sample Integration app 😢

**URL:** <https://community.fibery.io/t/trying-to-make-sense-of-integrations-doc-and-notion-sample-integration-app/4258>\
**Category:** Get Help\
**Tags:** integration\
**Created:** [April 5, 2023, 8:09pm UTC](https://community.fibery.io/t/trying-to-make-sense-of-integrations-doc-and-notion-sample-integration-app/4258 "2023-04-05T20:09:20Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![Matt\_Blais](https://sea2.discourse-cdn.com/flex020/user_avatar/community.fibery.io/matt_blais/32/1464_2.png) [@Matt\_Blais](https://community.fibery.io/u/Matt_Blais)\
**Post date:** [April 5, 2023, 8:09pm UTC](https://community.fibery.io/t/trying-to-make-sense-of-integrations-doc-and-notion-sample-integration-app/4258/1 "2023-04-05T20:09:20Z")

</div>

So many questions! After many weeks I still have not gotten relations to work in my custom integration. 🙁 This explains why:

* * *

## **❓ When to use “array[text]” field type?**

The `array[text]` field type is mentioned in the Integration docs, but never explained.

## 👉When should “array[text]” be used as the field type in a schema? What does it correspond to in the Fibery front end and back end?

* * *

[Schema Docs](https://api.fibery.io/apps.html#post-api-v1-synchronizer-config:~:text=Each%20type%20must%20contain%20name%20and%20id%20field.) say: `"Each type must contain 'name' and 'id' field"`, giving this example:

```auto
{
  "repository": {
    "id": {
      "type": "id",
      "name": "Id"
    },
    "name": {
      "type": "text",
      "name": "Name"
    },

```

**According to this example, the `name` field should be a simple text field.**

But the [Notion Integration app](https://gitlab.com/fibery-community/notion-app) passes the following data to Fibery for an entity’s `name` field content:

```auto
    "name": [
      "ABC Inc. Website"
    ]

```

even though the app itself defines the `name` field type as `text` in its schema, not `array[text]`:

```auto
    "name": {
      "name": "Name",
      "type": "text",
      "path": "properties.Name.title",
      "arrayPath": "plain_text"
    }

```

## 👉 Why does the Notion Integration app pass the `name` field to Fibery as `array[text]` when the schema defines it as `text`? Why does this even work?

## 👉 What are the requirements for the special `id` and `name` fields in the schema? What is flexible, and what must be exactly as described in the doc? Must `the id` field be unique, and what happens if multiple records are defined with the same value for `id`?

* * *

## **❓ Schema structure confusion**

The [Integration doc describes the schema object](https://api.fibery.io/apps.html#post-api-v1-synchronizer-config:~:text=Schema%20is%20JSON%20object%20where%20key%20is%20field%20and%20value%20if%20field%20description.) as:

> _Schema is JSON object where **key is field** and value if field description._

👉I think this means **_“a key is a Type ID and its value is the Type’s definition”_.**  
**Yes?**

Also, the doc says nothing about adding miscellaneous undocumented properties to our schema, such as the `path` and `arrayPath` properties added by the Notion Integration app.

## 👉What are the rules and uses for adding additional custom properties to our schema?

* * *

## **❓ Notion Multi-Select fields become Fibery Text field**

In my Notion DB I have a Multiselect “Tags” field, but the sample Notion Integration app translates this into an `array[text]` field in the generated schema:

```auto
    "tags": {
      "name": "Tags",
      "path": "properties.Tags.multi_select",
      "type": "array[text]",
      "arrayPath": "name"
    },

```

## So a Notion Multiselect field becomes just a Fibery Text field. 👉Why?

* * *

## **❓ Confusing [relations documentation](https://api.fibery.io/apps.html#post-api-v1-synchronizer-schema:~:text=relation%20field%20provides%20a%20possibility%20to%20create%20a%20relation%20between%20entities%20in%20Fibery.%20It%20contains%20following%20fields%3A)**

- 👉Cardinality: Why is there no **“one-to-many” option**? How to define one-to-many relations?

- 👉How about **one-to-one** relations? These are very important, but there is no mention.

- 👉No discussion of the **“hidden fields” created by relations** , or how they are related to our explicitly defined fields – or (most importantly) which of these explicit and implicit and visible and hidden fields should actually be present in the entity data we send to Fibery - on each side of a relation?

- 👉Missing discussion of Relation fields: E.g., **What are the requirements for `targetFieldId`**? Does it have to be “id”, or can it be ANY field, of any type?

- 👉No discussion of the “ **duplication of relations fields** ” – e.g., how should we decide which side of a relation to define/keep/remove? If the field for one side of a relation is removed from the schema, should we still send that field’s data to Fibery?

- 👉What are the rules for the **field types to use for relations**? E.g., should a relation field be `array[text]` even if it only refers to single entity (many-to-one)? Can it be a number, a Date, etc?

- 👉 Sometimes **Fibery renames a field by prefixing it with the name of the integration**. Why?

- 👉 How to use **Single- and Multi-Select fields**?

* * *

## **❓ Undocumented fields in data requests from Fibery**

When Fibery sends data requests to an integration app’s /api/v1/synchronizer/data endpoint some fields can be included in the request that are not described in [the documentation](https://api.fibery.io/apps.html#post-api-v1-synchronizer-data:~:text=08%3A47.074Z%22%0A%7D-,Request,Inbound%20payload%20includes%20following%20information%3A,-types%20%2D%20array%20of).

E.g. a subset of the **schema** is sometimes included in a data request.

## 👉Could we get updated documentation for this endpoint that describes all the data passed?

* * *

## **❓ Webhooks**

The [Integrations API description of Webhooks](https://api.fibery.io/apps.html#post-api-v1-synchronizer-filter-validate:~:text=an%20error%20message%3A-,POST%20/api/v1/synchronizer/webhooks,-OPTIONAL) does not explain how to use webhooks.

## 👉Could we get updated documentation for Integration API Webhooks that includes some use cases and examples?

---

<div class="post-metadata">

**Author:** ![seaotternerd](https://avatars.discourse-cdn.com/v4/letter/s/b5a626/32.png) [@seaotternerd](https://community.fibery.io/u/seaotternerd)\
**Post date:** [April 6, 2023, 4:32am UTC](https://community.fibery.io/t/trying-to-make-sense-of-integrations-doc-and-notion-sample-integration-app/4258/2 "2023-04-06T04:32:15Z")

</div>

Agree that more documentation would be helpful! In case it’s helpful while you’re waiting for a comprehensive response, I’ve discovered the answers to a couple of these question through trial and error:

- For relation field type, `array[text]` seems to only be for `many-to-many` relations. For `many-to-one` relations, you can definitely use `text`. I suspect that it needs to be `text` (and not a number, date, etc.), but have not tried those.
- Every `one-to-many` relation is just the opposite side of a `many-to-one` relation. So you can define them by adding a `many-to-one` relation to the type on the other side of the relation.

---

<div class="post-metadata">

**Author:** ![Oleg](https://sea2.discourse-cdn.com/flex020/user_avatar/community.fibery.io/oleg/32/1887_2.png) [@Oleg](https://community.fibery.io/u/Oleg)\
**Post date:** [April 6, 2023, 2:57pm UTC](https://community.fibery.io/t/trying-to-make-sense-of-integrations-doc-and-notion-sample-integration-app/4258/3 "2023-04-06T14:57:55Z")

</div>

Hello, @Matt_Blais

Thanks for feedback. Indeed relations mapping and our api is not a simple thing to understand and we need to provide more examples and make our documentation more friendly.

Regarding `arrayPath`. It is used by Notion connector itself only: [app/notion.api.js · main · fibery-community / Notion App · GitLab](https://gitlab.com/fibery-community/notion-app/-/blob/main/app/notion.api.js#L222)

Thanks again for rising this important topic. We need to fix docs for sure.

---

<div class="post-metadata">

**Author:** ![Matt\_Blais](https://sea2.discourse-cdn.com/flex020/user_avatar/community.fibery.io/matt_blais/32/1464_2.png) [@Matt\_Blais](https://community.fibery.io/u/Matt_Blais)\
**Post date:** [April 6, 2023, 5:10pm UTC](https://community.fibery.io/t/trying-to-make-sense-of-integrations-doc-and-notion-sample-integration-app/4258/4 "2023-04-06T17:10:49Z")

</div>

Thank you for bearing with me in my frustration.

I have figured it out now - at least, enough of it that it is now working as expected in my Integration (finally!).

I believe I could write the “missing” conceptual overview on implementing relations in the Integration app, which would have saved me much time and frustration.

Many of my questions are still unanswered and pertinent, though - e.g.: **“How do we implement one-to-one relations?”**

---

<div class="post-metadata">

**Author:** ![Oleg](https://sea2.discourse-cdn.com/flex020/user_avatar/community.fibery.io/oleg/32/1887_2.png) [@Oleg](https://community.fibery.io/u/Oleg)\
**Post date:** [April 7, 2023, 6:19am UTC](https://community.fibery.io/t/trying-to-make-sense-of-integrations-doc-and-notion-sample-integration-app/4258/5 "2023-04-07T06:19:22Z")

</div>

Hello, @Matt_Blais

Unfortunately it is not supported. Probably the reason is that one-to-one never came up for our connectors.

Sorry for inconvenience, will need to support it as well.

Thanks,  
Oleg