# Articles

Write and manage articles, Risotto's built-in knowledge base, and turn resolved Slack threads into articles with the ✍️ emoji

Articles are Risotto's built-in knowledge base. When the agent answers a question, it searches your articles together with your [indexes](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes). As the Articles tab puts it, articles take precedence over indexed data. Risotto re-indexes an article each time you save it.

You manage articles in **Knowledge > Articles**.

## The Articles tab

Click **Knowledge** in the sidebar. The page opens on the **Articles** tab and lists your articles in a table with their **Title** and the date they were **Created**. Click a column header to sort by it, and type in **Search articles** to find an article by its title or its content. Click a title to open the article.

*Product example: Knowledge, Articles in the Risotto dashboard: the articles table, with Create article.*

The **⋮** menu on each row has these actions:

- **Open in Slack**: opens the Slack thread the article was made from. It shows only for an article created from a ticket.
- **Export…**: copies the article into Guru. See [Exporting an article to Guru](#exporting-an-article-to-guru).
- **Delete**: deletes the article. See [Deleting an article](#deleting-an-article).

## Creating an article

You see **Create article** if you are an Org Admin, an Org Manager or a Department Supervisor. See [Article permissions](#article-permissions).

1. **Click Create article**

   In **Knowledge > Articles**, click **Create article** above the table. The **Create article** dialog opens.

2. **Enter a title**

   Type the article's **Title**.

3. **Choose a department**

   Pick a **Department** to restrict the article to that department, or keep **Organization-wide**. See [Organizing articles](#organizing-articles).

   *Product example: The Create article dialog, with the Department list open on IT.*

   **Organization-wide** is offered only to Org Admins and Org Managers. If you are a Department Supervisor, your first department is selected for you.

4. **Click Add content**

   Click **Add content**. Risotto creates the article and opens it, ready to edit.

5. **Write the content and save**

   Write the article in the **Content** editor, then click **Save**. See [Editing an article](#editing-an-article).

## Editing an article

1. **Open the article**

   In **Knowledge > Articles**, click the article's title. The article opens with its details in a side panel.

   *Product example: An article in the Risotto dashboard, with its details in the side panel and Edit in the header.*

2. **Click Edit**

   Click **Edit** in the page header, or press `e`. The **Title**, **Department** and **Content** fields open.

3. **Change the article**

   Edit the fields. **Content** is Markdown.

   *Product example: An article being edited: Title, Department and the Markdown content editor, with Save in the header.*

   The toolbar above the content adds bold, italic, a quote, a numbered or bulleted list, a heading (H1 to H3), a link, and code. Click **Preview** to see the rendered article, and **Write** to go back to the Markdown.

4. **Click Save**

   Click **Save**, or press **⌘S** (**Ctrl+S** on Windows). The header shows **Saved**. To discard your changes, click **Cancel** or press **Esc**.

Articles hold text only. The editor has no button to upload or paste an image. If you add a Markdown image link, the image shows in **Preview**, but Risotto reads only the text of the article. It does not read what is in the picture, so describe each step in words.

The side panel shows the article's **Title**, its **Department** (or **Organization-wide**), and when it was **Created** and **Last updated**. For an article created from a ticket, it also shows the **Original question**, a link to the **Ticket**, and an **Open in Slack** button that opens the source thread.

Each change is recorded in **Settings > Audit Log** as **Knowledge Article Updated**.

## Deleting an article

1. **Open the row menu**

   In **Knowledge > Articles**, open the **⋮** menu on the article's row and click **Delete**.

2. **Confirm**

   In the **Delete article?** dialog, confirm. Risotto shows **Article deleted**.

Deleting cannot be undone. If Risotto has already used the article to answer in Slack and you index that Slack channel, the answer can stay in the channel index. In that case, editing the article is better than deleting it.

Each deletion is recorded in **Settings > Audit Log** as **Knowledge Article Deleted**.

## Automating article creation in Slack

> **Info:** The ✍️ emoji command is available in Slack only. It is not yet supported in
> Microsoft Teams.

When a Slack thread solves a problem that your documentation doesn't cover, you can turn it into an article. Add the ✍️ (`:writing_hand:`) reaction to the thread's top message, the one that started the thread. A ✍️ on a reply does nothing. Risotto then:

1. Creates a ticket for the thread if it has none.
2. Writes an article from the thread: a title and a Markdown body. The article is organization-wide, and it keeps the ticket and the original question.
3. Resolves the ticket if it is not resolved yet, and adds an internal note to the ticket that names you and links the new article.
4. Adds a 💡 reaction to the thread once the article is indexed, and posts **Knowledge Base Article Created** to your [notifications channel](https://www.tryrisotto.com/docs/dashboard/settings/notifications) if you have one.

Once the article is indexed, Risotto stops using the Slack thread itself as a source, so the article takes its place.

- Adding ✍️ again to a thread that already has an article rewrites that article from the thread. This replaces any edits you made in the dashboard.
- Removing the last ✍️ reaction from the top message deletes the article.
- Risotto ignores the reaction from anyone whose Slack email doesn't match a Risotto dashboard user.

To use a different emoji, see [Commands](https://www.tryrisotto.com/docs/operating/slack-emojis).

## Organizing articles

Each article has a **Department** field ("Optionally restrict this article to a specific department."). The field controls which tickets the agent can use the article on:

- **Organization-wide**: the agent can use the article on any ticket. Articles that the ✍️ emoji creates are organization-wide.
- **A department**: the agent uses the article only on tickets in that department. A ticket with no department gets only organization-wide articles.

The department comes from the ticket, not from the requestor. Any requestor whose ticket goes to that department can get an answer from the article.

> **Note:** The **Department** field is not an access control. Articles have no staff-only
> setting. To keep a document for your team only, store it in a connected
> knowledge source and set the index's **Audience** to **Assistant only**. See
> [Indexes](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes).

## Exporting an article to Guru

> **Info:** Article export is **Experimental**. The dialog and its options can change.

You can copy an article into Guru as a new card. The article in Risotto stays
unchanged. Only an Org Admin or Org Manager sees the export action, because the
export sends a vault credential's value to Guru.

Before you start, you need:

- A [Guru User Token](https://developer.getguru.com/docs/user-tokens-vs-collection-tokens)
  stored in the [Credential Vault](https://www.tryrisotto.com/docs/dashboard/settings/credential-vault) as an
  **org-wide** credential of type **Secret text**. Risotto does not accept a
  Collection Token. A department credential cannot be used for an export. If
  the credential has allowed hosts, they must include `api.getguru.com`.
- The email of the Guru user the token belongs to.

1. **Open the export dialog**

   In **Knowledge > Articles**, open the **⋮** menu on the article row and
   click **Export…**. The **Export article** dialog opens.

   *Product example: The articles table with a row's menu open on Export….*

2. **Choose the destination and account**

   **Destination** is **Guru**. Enter the **User email** of the Guru user who
   owns the token. Guru creates the card as this user.

3. **Pick the token**

   For **User API token**, pick the vault credential that holds the Guru User
   Token, or create one inline. The list shows org-wide credentials only.

4. **Pick a collection**

   After you enter the email and pick the token, Risotto loads the collections
   the Guru user can see. Pick the **Collection** the card is created in. If
   you change the email, the token, or the destination, pick the collection
   again.

5. **Set access and export**

   **Access** is **Team** or **Private**. A Team card is visible to everyone
   who can read the collection. A Private card is visible to the token's user
   only. Click **Export**.

   *Product example: The Export article dialog filled in for a Guru collection, with Export.*

   Risotto shows **Article exported to Guru** with an **Open** link to the new card.

The export converts the article's markdown to HTML. Tables, fenced code blocks,
and lists keep their formatting. Strikethrough text is exported as literal
`~~` characters.

Each export is recorded in **Settings > Audit Log** as **Knowledge Article
Exported**, with the article, the destination, the collection, the access level,
and the new card's ID and URL. Exporting the same article again creates another card;
Risotto does not update a card it exported before.

> **Note:** An exported card is not indexed by Risotto until the collection it is in is
> connected as a Guru index. See [Guru](https://www.tryrisotto.com/docs/integrations/knowledge/guru).

## Article permissions

Every org member can read every article. Who can write an article depends on the article's **Department** field and on your roles. See [Permissions System](https://www.tryrisotto.com/docs/operating/permissions) for all roles.

| Action                                       | Org Admin or Org Manager | Department Supervisor                        | Department Agent or Org Member |
| -------------------------------------------- | ------------------------ | -------------------------------------------- | ------------------------------ |
| Read articles                                | ✅                        | ✅                                            | ✅                              |
| Create, edit, or delete an org-wide article  | ✅                        | ❌                                            | ❌                              |
| Create, edit, or delete a department article | ✅                        | Only in departments that they supervise      | ❌                              |
| Move an article to org-wide                  | ✅                        | ❌                                            | ❌                              |
| Move an article to another department        | ✅                        | Only between departments that they supervise | ❌                              |
| Export an article to Guru                    | ✅                        | ❌                                            | ❌                              |

A Supervisor of a [sub-department](https://www.tryrisotto.com/docs/dashboard/settings/sub-departments) can also write the articles of the parent department. A Supervisor sees **Organization-wide** in the **Department** field only if they are also an Org Admin or Org Manager.

> **Note:** The ✍️ emoji command in Slack does not check these roles. Anyone whose Slack
> email matches a Risotto dashboard user can use it to create an org-wide
> article. See [Slack Emoji Cheat Sheet](https://www.tryrisotto.com/docs/operating/slack-emojis).

Source: https://www.tryrisotto.com/docs/dashboard/knowledge/articles
