Rich text fields

Rich text in DevRev enables formatted text fields with mentions, used for issue descriptions or conversation bodies.

A simple rich text looks like one markdown string wrapped in an array:

1
["Hello **world**!"]

Markdown must conform to CommonMark Spec v0.30.

Rich text mentions

Rich text can include mentions by combining strings and mention objects:

1
[
2
  "Hello ", 
3
  {"ref_type":"external_user_type", "id":"1...", "fallback_record_name": "John Doe"}, 
4
  "how are you?"
5
]

Mention objects represents any mention (user, issue, etc.) in rich text and have the following structure:

In reverse, the loader should expect the following structure:

1
{
2
  "type": "rich_text",
3
  "content": [
4
    "Hello ",
5
    {
6
      "ref_type": "external_user_type",
7
      "id": "don:identity:dvrv-us-1:devo/xyz:devu/1",
8
      "fallback_record_name": "John Smith"
9
    },
10
    "how are you?"
11
  ]
12
}

Importing articles

Articles are documents containing key information about products, services, and processes. They support both Markdown and HTML formats.

Articles can include mentions to artifacts and other articles. Inline attachments must map to artifacts, and article links must map to articles.

Managing permissions

Article permissions are managed through the shared_with field, which can reference users, groups, and platform groups. Refer to the permissions for more details.

Inline attachments

If an inline attachment is hosted in the source system, it must be created as an artifact in DevRev. The same link cannot be used as the attachment is deleted in the source system when our customers deactivate the account. However, creating an artifact is not enough. The artifact must be linked in the appropriate place in the article content.

The following HTML example shows an inline attachment:

1
<img src="don:core:dvrv-us-1:devo/0:artifact/1" alt="Alt Text"/>

The following Markdown example shows an inline attachment:

1
![Alt Text](don:core:dvrv-us-1:devo/0:artifact/1)

Let’s say the content of your external system looks like this:

1
<p>
2
  This is an article with one image.  
3
</p>
4
<p>
5
  <img src="https://devrev.zendesk.com/hc/article_attachments/29908544740244" alt="download.jpeg">
6
</p>

The content in DevRev should look like this:

1
<p>
2
  This is an article with one image.
3
</p>
4
<p>
5
  <img src="don:core:dvrv-us-1:devo/0:artifact/1" alt="download.jpeg">
6
</p>

Where don:core:dvrv-us-1:devo/0:artifact/1 is the DevRev artifact ID corresponding to external attachment 29908544740244. To accomplish this, transform the article content to this JSON:

1
[ 
2
    "<p>This is an article with one image.</p><p><img src=\"",
3
    {
4
        "ref_type": "artifact",
5
        "id": "29908544740244",
6
        "fallback_record_name": "<fallback link>"
7
    },
8
    "\" alt=\"download.jpeg\"></p>" 
9
]

Set ref_type to artifact and use the source system’s attachment ID. The platform replaces the mention with the corresponding artifact ID. Note that the resolved value isn’t wrapped in double quotes.

Links to other articles

When an article references another article, create a mention to that article. The referenced article must exist from previous syncs or be created in the current sync. The platform handles ID resolution since article IDs in DevRev can’t be predicted at extraction time. This feature works with HTML format, and since Markdown can contain HTML, the same approach applies there.

The following HTML example shows a link to another article:

1
<a data-article-id="don:core:dvrv-us-1:devo/0:article/10" href="/ART-10" target="_self">
2
  Contact our Support Team
3
</a>

Let’s say the content of your external system looks like this:

1
<p>
2
  You can create an account and log-in
3
  <a href="https://devrev.zendesk.com/hc/en-us/articles/360059607772" target="_self">
4
    only
5
  </a>
6
  with the company email.
7
</p>

The content in DevRev should look like this:

1
<p>
2
  You can create an account and log-in
3
  <a data-article-id="don:core:dvrv-us-1:devo/0:article/10" href="/ART-10" target="_self">
4
    only
5
  </a>
6
  with the company email.
7
</p>

Where don:core:dvrv-us-1:devo/0:article/10 is the DevRev article ID corresponding to external article 360059607772. Transform the content to this JSON:

1
[
2
    "You can create an account and log-in <a data-article-id=\"",
3
    {
4
        "ref_type": "article",
5
        "id": "360059607772",
6
        "fallback_record_name": "<fallback article ID>"
7
    },
8
    "\" target=\"_self\"> only</a> with the company email."
9
]

Set ref_type to the external system’s item type that maps to articles (e.g., “documents”). The platform replaces the mention with the corresponding DevRev article ID and adds the appropriate href attribute.