Ctrl+K

Introduction to Linking Endpoints

Introduction to Linking Endpoints#

Workiva’s Linking endpoints allow you to interact with links in documents and spreadsheets. Source links are attached to anchors. Destination links are either a DestinationLinkTextElement in rich text or CellDestinationLinkValue in tables.

In this guide, you’ll learn:

  • How do I link a table cell to rich text?

  • How do I link rich text to a table cell?

  • How do I publish value changes to my destination links?

  • How do I find the source link for a destination?

  • How do I find the destinations for a source link?

  • What are some common concepts to consider when working with links?

Example Use Cases#

How do I link a table cell into rich text?#

In this exercise, you will link text from a table cell to a rich text document. To follow these steps, you’ll need:

  • The tableId, revision, and CellRange values for where the source link is to be created. Refer to Introduction to tables to learn how to retrieve a tableId and identify cell coordinates.

  • The richTextId, revision, and Caret values for where the destination link is to be placed. Refer to Introduction to rich text to learn about obtaining a richTextId and identifying locations in rich text.

A source link must always be attached to an anchor. If you don’t already have a source link, you will need to create an anchor first.

Creating a table cell anchor#

Use a POST create table anchor call to create the anchor. You will need the tableId, revision, and CellRange values from the section above.

Important

The CellRange must be the specific individual cell that you want to configure as the source link. Table anchor source links can only be for a single cell.

Request#
curl -X POST -H "Authorization: Bearer ${token}" --data @body.json https://api.app.wdesk.com/prototype/platform/content/tables/WA2NiYGJgm7cWr4W6Ka9BHScz56m2AT2FqTmBgekyk399M99I9Bb69BoEt3WHCag/anchors/creation
Request Body#
{
  "range": {
    "startRow": 0,
    "stopRow": 0,
    "startColumn": 0,
    "stopColumn": 0
  },
  "revision": "2c6438ab45553de5"
}

A 202 response indicates that your edit request was accepted.

After the request is made, the status of the request can be found through polling the Operations endpoint set in the location header of the creation’s response. When the operation is complete a GET request can be made to the completed operation’s resourceUrl to retrieve the table anchor creation results. The results of this creation request includes the table anchor and the new revision:

Request#
curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/operations/851b155b-fc91-4e78-9f45-f627544844bd/tableAnchorCreationResults
Response#
{
    "data": [
        {
            "type": "anchor",
            "anchor": "WA3l7enh6Dkm85iyvOn3ujymTB2reZ3tyRq4syjklMoTn4L9B55sDCFHpxd0lUSVRIVEhUQUhATklL"
        }
    ],
    "revision": "2c6438ab4540684f"
}

Linking an anchor to rich text#

Now you are ready to create a link.

You will need the values for richTextId, revision, and the position within the rich text where you want to place the anchor. You will also need the source anchorId value from the previous step.

This inserts the destination link at the beginning of the rich text.

Request#
curl -X POST -H "Authorization: Bearer ${token}" --data @body.json https://api.app.wdesk.com/prototype/platform/content/richText/WA8jJy8nLubbkEHM99i4dIuJ4CNQDsW8rB7MvLmwCHucbKj61j6tmTLBft2g/links/edit
Request Body#
{
  "revision": "2c6438ab4540684a",
  "data": [
    {
      "type": "insertDestinationLink",
      "insertDestinationLink": {
        "insertAt": {
          "paragraphIndex": 0,
          "offset": 0
        },
        "sourceAnchor": "WA3l7enh6Dkm85iyvOn3ujymTB2reZ3tyRq4syjklMoTn4L9B55sDCFHpxd0lUSVRIVEhUQUhATklL"
      }
    }
  ]
}

If the response is 202, your creation request was accepted. Read the Operations guide to learn more about operations.

You have now created the link, and can query the rich text using GET rich text paragraphs to see the new link.

How do I link rich text to a table cell?#

In this exercise, you will link text from a document to a table cell.

To follow these steps, you’ll need:

  • The richTextId, revision, and RichTextSelection values for where you will create the source link. Refer to Introduction to rich text to learn about obtaining a richTextId and identifying locations in rich text.

  • The tableId, revision, and Cell values for where you will create the destination link. Refer to Introduction to tables to learn how to retrieve a tableId and identify cell coordinates.

Creating a rich text anchor#

Use a POST create new rich text anchor call using the values identified above.

This request creates a source link starting at the beginning of paragraph index 2 and ending 17 characters later.

Request#
curl -X POST -H "Authorization: Bearer ${token}" --data @body.json https://api.app.wdesk.com/prototype/platform/content/richText/WA8jJy8nLubbkEHM99i4dIuJ4CNQDsW8rB7MvLmwCHucbKj61j6tmTLBft2g/anchors/creation
Request Body#
{
  "revision": "2c6438ab45406ba9",
  "type": "sourceLink",
  "selection": {
    "start": {
      "paragraphIndex": 2,
      "offset": 0
    },
    "stop": {
      "paragraphIndex": 2,
      "offset": 17
    }
  }
}

If you have successfully created the link, a 202 response is returned. Follow the typical Operations pattern until the operation completes.

Linking an anchor to a table cell#

This step links the anchor to the table cell. You will need the tableId, revision, and table cell ID (Row/Column) values for this table and cell.

This example uses the POST command to create the table link.

Request#
curl -X POST -H "Authorization: Bearer ${token}" --data @body.json https://api.app.wdesk.com/prototype/platform/content/tables/WA66srK9At2Z5rMft47ao5WP5E0L0JsKylkXn7He7y5VMwN2guMRcVww/links/edit
Request Body#
{
   "revision": "2c6438ab45553de5",
   "data": [
      {
        "type": "insertCellDestinationLink",
        "insertCellDestinationLink": {
          "insertAt": {
            "row": 0,
            "column": 0
          },
          "sourceAnchor": "WA3l7enh6Dkm85iyvOn3ujymTB2reZ3tyRq4syjklMoTn4L9B55sDCFHpxd0lUSVRIVEhUQUhATklL"
        }
      }
   ]
}

If the response to this POST is 202, your link creation request was accepted and the link was created. You can now query your table using GET table cells to see your new link.

Common Concepts#

Anchors#

  • Anchors are an attachment point.

  • A source link is always attached to an anchor.

  • Anchors may be created on a table cell, on a selection in rich text, or on drawing content.