epilot-dev · ernestoresende · Nov 18, 2024 · Nov 18, 2024 · Nov 18, 2024
diff --git a/docs/notes/_category_.json b/docs/notes/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Notes",
+  "position": 8
+}
diff --git a/docs/notes/intro.mdx b/docs/notes/intro.mdx
@@ -0,0 +1,106 @@
+---
+title: Overview
+hide_title: true
+sidebar_position: 1
+---
+
+<h1 align="left" style={{ display: 'inline-block' }}>
+  Notes{' '}
+  <span
+    style={{
+      display: 'inline-block',
+      padding: '2px 8px',
+      color: '#fff',
+      fontWeight: 'bold',
+      backgroundColor: '#df0000',
+      borderRadius: '4px',
+      fontSize: '1rem',
+      verticalAlign: 'middle',
+    }}
+  >
+    Beta
+  </span>
+</h1>
+
+Notes provide a way to exchange contextual information in a collaborative way to other Entities in Epilot. **All Notes created in Epilot are represented as Note Entities**, and are accesible through [Entity API's](/api/entity#tag/entity_schema) and [SDK](/docs/architecture/sdk).
+
+:::warning
+Notes were previously available as a platform feature accessible through the Notes Tab on the Entity View. This feature is being deprecated and removed in favor of **Notes as Entities** and the new **Notes Capability**, available from the Entity sidebar, described in this section.
+
+**Notes as Entities** are currently in closed **Beta** only available to selected customers. General Availability will be announced soon.
+:::warning
+
+## Using Notes from the Entity sidebar
+
+### Accessing Notes from the Entity View
+
+On any of the supported Entity types, you can create a new Note by expanding the sidebar and going to the **Notes Tab**. This will show you all the Notes associated with this Entity.
+
+### Creating a new Note
+
+To create a new Note, click on the **New Note** button on the top right of the Notes Tab. You can use various formatting options to structure your Note, mention other users from your organization, add file attachments, and categorize your Notes with labels.
+
+<video
+  width="100%"
+  autoPlay
+  loop
+  muted
+  style={{
+    borderRadius: '5px',
+  }}
+>
+  <source src="/videos/notes/creating_notes.mp4" type="video/mp4" />
+</video>
+
+### Creating a comment on a Note thread
+
+You can also create a comment on a Note thread by clicking on the **Comment** button at the bottom corner of the Note. You can use Note comment threads to discuss a topic in more detail, without adding clutter to the to the current Entity context.
+
+<video
+  width="100%"
+  autoPlay
+  loop
+  muted
+  style={{
+    borderRadius: '5px',
+  }}
+>
+  <source src="/videos/notes/creating_note_comments.mp4" type="video/mp4" />
+</video>
+
+### Pinning Notes
+
+You can pin a Note to the top of the Notes tab by clicking on the **Pin** button in any Note. This will make the Note easilly accessible from the top of the Notes tab.
+
+<video
+  width="100%"
+  autoPlay
+  loop
+  muted
+  style={{
+    borderRadius: '5px',
+  }}
+>
+  <source src="/videos/notes/note_pinning.mp4" type="video/mp4" />
+</video>
+
+### Searching Notes
+
+You can search for any Note that is contextually attached to the current Entity you're viewing by typing parts of it's content, mentioned users, or labels on the search input at the top of the Notes tab.
+
+:::info
+Furthemore, you can filter Notes globally through the Note Entity table. See more details about advanced usage of Note Entities [here](/docs/notes/note_entities).
+:::info
+
+### Note file attachments
+
+You can add file attachments to your Notes and Note comments. These attachements will be resolved to File Entities and can be accessed through the [File API](/api/file).
+
+## Configuring Notes notifications
+
+New Notes will automatically trigger notification events to users that are either:
+
+- Participating in the Note thread (eg.: created the Note or replied to an Note thread at least once);
+- Mentioned directly in the Note or Note comment;
+
+To change these settings, navigate to User > My Account > Notifications, and look for the **Communication** section.
diff --git a/docs/notes/note_entities.mdx b/docs/notes/note_entities.mdx
@@ -0,0 +1,10 @@
+---
+title: Note Entities 
+sidebar_position: 2
+---
+
+All Notes created in Epilot are represented as Note Entities. For almost all cases, you're expected to use the dedicated Notes tab on the sidebar of related Entities, but some cases may require you to manipulate the Note Entity directly. For such cases, you can use the Note Entity table to filter and access Note Entities just like any other Entity.
+
+## Note Entity relationships
+
+Note Entities use the [default entity relationship model](/docs/entities/relations) to link themselves to other contextual entities, file attachments, and also to other Notes. This is what controls the hierarchical structure of Note threads.
diff --git a/docs/notes/notes_api.mdx b/docs/notes/notes_api.mdx
@@ -0,0 +1,68 @@
+---
+title: Notes API
+sidebar_position: 3
+---
+
+[[API Docs](/api/notes)] [[SDK](https://www.npmjs.com/package/@epilot/notes-client)]
+
+Developers and integration partners can leverage the Notes API to easily manipulate Note Entities in the platform.
+
+## Getting notes for an Entity context
+
+You can use the [`getNotesByContext`](/api) operation to get all the Notes associated with an Entity context. This will return all the Notes from the Entity ID passed as a path parameter.
+
+> *Example of a `getNotesByContext` request*:
+
+> `https://notes.dev.sls.epilot.io/v1/notes/8429e0f4-3c06-41fd-92bb-a00ba575d1fc`
+
+### Non-Entity contexts
+
+In addition to the Entity ID of the primary context for a Note, you can use the `contexts` query parameter to filter the returned Notes by specific non-entity contexts, such as `workflow_execution` and `workflow_task`.
+
+> *Example of a `getNotesByContext` request with a `contexts` query parameter*:
+
+> `https://notes.dev.sls.epilot.io/v1/notes/8429e0f4-3c06-41fd-92bb-a00ba575d1fc?contexts[]={"type":"workflow_execution","id":"zio6qcaduot"}&contexts[]={"type":"workflow_task","id":"anm0narsy2i"}`
+
+:::note
+Remember to encode the URL with a method like [`encondeURIComponent()`](https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent).
+:::note
+
+## Creating and updating Notes
+
+You can create a new Note by using the [`createNote`](/api/notes#tag/Notes/operation/createNote) operation. And update an existing Note using the [`updateNote`](/api) or [`patchNote`](/api) This operation accepts all the attributes especified on the Note Entity schema, and a `content` attribute, which should be a stringified HTML content for the Note.
+
+### Note content formatting rules
+
+The styles of the Note content are normalized, which means that any style attributes in the `content` attribute will be removed during the Note creation. We conform to standard HTML tags to resolve the Note formatting:
+
+- The entire content should be wrapped in a `<body>` tag;
+- `<p>` tag for simple paragraphs;
+  - You can use the `<span>` tag with the `epilot360-comment-user-id` attribute to mention users in the Note;
+- `<h1>` to `<h3>` tags for headings (we allow a maximum of 3 levels of heading depth);
+- `<li>` tag for list items, wrapped in a `<ol>` tag for ordered lists, and `<ul>` for unordered lists;
+- `<a>` tag for links;
+  - The `href` attribute is required for links;
+- For styling tags, we allow the following:
+  - `<strong>` or `<b>` tag for bold text;
+  - `<em>` or `<i>` tag for italic text;
+  - `<u>` tag for underlined text;
+
+> *Example of a `createNote` request body with valid HTML content*:
+```json
+{
+  "entity_id": "4e9f4d7a-f5d8-4f0d-b8d6-d1b1d5f1f2f3",
+  "content": "<body><p>Hello from Epilot</p></body>",
+}
+```
+
+## Pinning Notes
+
+You can pin a Note to the top of the Notes tab by using the [`pinNote`](/api/notes#tag/Notes/operation/pinNote) operation. This operation accepts the Entity ID of the Note as a path parameter.
+
+## Deleting Notes
+
+You can delete a Note using the [`deleteNote`](/api/notes#tag/Notes/operation/deleteNote) operation. This operation accepts the Entity ID of the Note as a path parameter.
+
+:::danger
+Deleting a Note that has comments will also delete all the Note Entities for these comments
+:::danger
diff --git a/redoc.config.js b/redoc.config.js
@@ -134,6 +134,11 @@ module.exports.specs = [
     routePath: '/api/discussion',
     specUrl: 'https://docs.api.epilot.io/discussion.yaml',
   },
+  {
+    layout: { title: 'Notes API' },
+    routePath: '/api/notes',
+    specUrl: 'https://docs.api.epilot.io/notes.yaml',
+  },
   {
     layout: { title: 'Consent API' },
     routePath: '/api/consent',

diff --git a/static/videos/notes/creating_note_comments.mp4 b/static/videos/notes/creating_note_comments.mp4
diff --git a/static/videos/notes/creating_notes.mp4 b/static/videos/notes/creating_notes.mp4
diff --git a/static/videos/notes/note_pinning.mp4 b/static/videos/notes/note_pinning.mp4
diff --git a/static/videos/notes/note_searching.mp4 b/static/videos/notes/note_searching.mp4
diff --git a/static/videos/notes/opening_notes.mp4 b/static/videos/notes/opening_notes.mp4