Introduction to Range Linking Endpoints#
Workiva’s Range Link endpoints allow you to interact with range links in tables. Source range links can be created, removed, updated, and published. Destination range links can be created and removed.
In this guide, you’ll learn:
How do I create a source range link?
How do I create a destination range link?
How do I publish range links?
How do I move an existing source range link?
How do I remove a range link?
Example Use Cases#
How do I create a source range link?#
In this exercise, you’ll create a new source range link in a table. You’ll need the tableId and CellRange values for the source range. Refer to Introduction to tables to learn how to retrieve a tableId and identify cell coordinates.
Use a POST Initiate a range links edit call to create the range link source. You will need the tableId and cell coordinates.
curl -X POST -H "Authorization: Bearer ${token}" --data @body.json https://api.app.wdesk.com/prototype/platform/content/tables/WA2NiYGJgm7cWr4W6Ka9BHScz56m2AT2FqTmBgekyk399M99I9Bb69BoEt3WHCag/rangeLinks/edit
{
"type": "createSource",
"createSource": {
"range": {
"startColumn": 0,
"startRow": 0,
"stopColumn": 1,
"stopRow": 1
}
}
}
After the request is made, the status of the request can be found by polling the Operations endpoint set in the location header of the action’s response. When the operation is complete a GET request can be made to the completed operation’s resourceUrl to retrieve the action results. If the response is 202, your creation request was accepted. Read the Operations guide to learn more about operations.
curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/operations/851b155b-fc91-4e78-9f45-f627544844bd/rangeLinkEditCollectionResults
{
"revision": "24601abc",
"data": [
{
"type": "rangeLink",
"rangeLink": "5c05e5c9523045438201bc2021c7a71d"
}
]
}
You have now created the source range link, and can query for it using GET Retrieve a list of range links.
curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/content/tables/WA2NiYGJgm7cWr4W6Ka9BHScz56m2AT2FqTmBgekyk399M99I9Bb69BoEt3WHCag/rangeLinks
{
"@nextLink": "<opaque_url>",
"data": [
{
"id": "f649093edf354cfe8ce52fa60990a109",
"table": "WA2NiYGJgm7cWr4W6Ka9BHScz56m2AT2FqTmBgekyk399M99I9Bb69BoEt3WHCag",
"revision": "24601abc",
"type": "destination",
"destination": {
"source": {
"rangeLink": "8ce52fa60990a109f649093edf354cfe",
"table": "WA66srK9AtGU3PvTjs4dMCR9B34EoH6LqyloPIRNdxS5Bgs3p199MQzPsA",
"revision": "24601abc",
}
}
}
]
}
Note
The revision field on source range links indicates the revision at which the range link was last published.
How do I create a destination range link?#
In this exercise, you’ll create a new destination range link in a table. You’ll need the source and destination tableIds and the source rangeLinkId from which this destination range link should be created. Refer to Introduction to tables to learn how to retrieve a tableId.
Note, this request can optionally disable formatting and column width replication to retain any pre-existing formatting that already exists on the destination table. Destination range links are always inserted at the top left cell of the table and fully occupy the table, removing all cells outside of the range.
Use a POST Initiate a range links edit call to create the range link destination. You will need the source tableId, source rangeLinkId, and the target tableId. Use the target tableId in the POST path.
curl -X POST -H "Authorization: Bearer ${token}" --data @body.json https://api.app.wdesk.com/prototype/platform/content/tables/WA2NiYGJgm7cWr4W6Ka9BHScz56m2AT2FqTmBgekyk399M99I9BgTTTW12377/rangeLinks/edit
{
"type": "createDestination",
"createDestination": {
"sourceRangeLink": "8ce52fa60990a109f649093edf354cfe",
"sourceTable": "WA66srK9AtGU3PvTjs4dMCR9B34EoH6LqyloPIRNdxS5Bgs3p199MQzPsA"
}
}
After the request is made, the status of the request can be found by polling the Operations endpoint set in the location header of the action’s response. When the operation is complete a GET request can be made to the completed operation’s resourceUrl to retrieve the action results. If the response is 202, your creation request was accepted. Read the Operations guide to learn more about operations.
curl -X GET -H "Authorization: Bearer ${token}" https://api.app.wdesk.com/prototype/platform/operations/851b155b-fc91-4e78-9f45-f627544844bd/rangeLinkEditResults
{
"revision": "24601abc",
"data": [
{
"type": "rangeLink",
"rangeLink": "5c05e5c9523045438201bc2021c7a71d"
}
]
}
How do I publish range links?#
Source range link value and structural changes do not immediately propagate to destinations. Changes must be published as a separate action. Publishes are performed at the document level and each document type (Spreadsheet, Document, Presentation) has its own unique publish POST request–see below. When you publish, both value changes and range link structure changes are published.
Important
In order to publish all links in a document you must have “document owner” permissions.
Note
Range link publishes may partially succeed. Value publishes always entirely succeed or entirely fail–it will never be the case that only some values are published. However, in error conditions, it may be that only some range link destinations receive range changes. If the publish operation indicates a Success status, then all links and range links were published successfully. If the operation indicates a Failure, some destinations may not have received changes to the source range. Check the operation results for more details.
How do I move an existing source range link?#
The range of an existing source range link can be updated to grow or shrink the source range to include or exclude particular cells. Once complete, the source range link will need to be published to update any destinations. This update is achieved via an action performed on the source range link, specifying the new CellRange values for where the source range link is to be moved. You’ll need the tableId and rangeLinkId.
Important
A source range link can be moved within a table, but its table cannot be changed.
Use a POST Initiate a range links edit call to change the source range link’s range. You will need the tableId, rangeLinkId, and the new cell coordinates.
curl -X POST -H "Authorization: Bearer ${token}" --data @body.json https://api.app.wdesk.com/prototype/platform/content/tables/WA2NiYGJgm7cWr4W6Ka9BHScz56m2AT2FqTmBgekyk399M99I9Bb69BoEt3WHCag/rangeLinks/edit
{
"type": "changeSourceRange",
"changeSourceRange": {
"rangeLink": "8ce52fa60990a109f649093edf354cfe",
"range": {
"startColumn": 0,
"startRow": 0,
"stopColumn": 2,
"stopRow": 2
}
}
}
After the request is made, the status of the request can be found by polling the Operations endpoint set in the location header of the action’s response. When the operation is complete a GET request can be made to the completed operation’s resourceUrl to retrieve the action results. If the response is 202, your creation request was accepted. Read the Operations guide to learn more about operations.
How do I remove a range link?#
Existing source or destination range links can be removed. When a range link is deleted, cell-level links created by the Range Link will remain and need to be removed separately if desired. Deletions are performed as an action on either a source or destination range link by specifying a tableId and rangeLinkId.
Removing a destination range link only impacts that specific table. Removing a source range link will also remove all corresponding destination range links. Substitute the removeDestination and removeSource action types as needed.
curl -X POST -H "Authorization: Bearer ${token}" --data @body.json https://api.app.wdesk.com/prototype/platform/content/tables/WA2NiYGJgm7cWr4W6Ka9BHScz56m2AT2FqTmBgekyk399M99I9Bb69BoEt3WHCag/rangeLinks/edit
{
"type": "removeSource",
"removeSource": {
"rangeLink": "8ce52fa60990a109f649093edf354cfe"
}
}
After the request is made, the status of the request can be found by polling the Operations endpoint set in the location header of the action’s response. When the operation is complete a GET request can be made to the completed operation’s resourceUrl to retrieve the action results. If the response is 202, your creation request was accepted. Read the Operations guide to learn more about operations.
Common Concepts#
Cell Range#
Cell Ranges specify the exact range within a table a source range link is intended to occupy. See CellRange.
Source Range Link#
A source range link can exist anywhere within a table and its location can be updated after creation.
A single source range link may be attached to many destination range links.
Source range link changes are not automatically sent to destinations. To distribute the changes, the document, spreadsheet, or presentation must be published.
Destination Range Link#
A destination range link will fully occupy an entire table, removing any cells outside of the range.
A destination range link is always attached to a source range link.
A destination range link’s value and/or structure changes only when the source range link is published.
Range Link ID#
A unique identifier for a source or destination range link.
Link Publish#
A link publish operation causes source range links in a document to send their value and/or structural changes to destinations. See Introduction to Linking Endpoints.