Managing Document Tags

Introduction

The Actionstep API provides the capability to assign one or more tags to a Matter document. In this tutorial we show how to add and update document tags, and how to search for a document by tag.

Creating a Matter Document with Tags

The first step is to create a Matter Document. The Matter Documents resource allows you to get and set the meta data associated with files stored against a Matter. Matter documents can have zero, one, or multiple tags attached depending on your individual requirement.

The first API request example creates a new Matter document. Since we already have an existing Conveyancing Purchase matter type (with an id of 15) we will associate our new document with this matter type and include a comma separated list of tag ids in an array (which we have already created through the tag endpoint, here we are using 10001 and 10002).

POST {api_endpoint}/api/rest/actiondocuments

{
    "actiondocuments": {
        "name": "My action document",
        "file": "DL::Actions::15::127",
        "links": {
            "action": "15",
            "tags": [
                10001,
                10002,
            ]
        }
    }
}

The response will be the following:

{
    "links": {
        "actiondocuments.action": {
            "href": "https://raveena--ap-southeast-2.actionstepdev.com.actionstep.com/api/rest/actions/{actiondocuments.action}",
            "type": "actions"
        },
        "actiondocuments.checkedOutBy": {
            "href": "https://raveena--ap-southeast-2.actionstepdev.com.actionstep.com/api/rest/participants/{actiondocuments.checkedOutBy}",
            "type": "participants"
        },
        "actiondocuments.folder": {
            "href": "https://raveena--ap-southeast-2.actionstepdev.com.actionstep.com/api/rest/actionfolders/{actiondocuments.folder}",
            "type": "actionfolders"
        },
        "actiondocuments.createdBy": {
            "href": "https://raveena--ap-southeast-2.actionstepdev.com.actionstep.com/api/rest/participants/{actiondocuments.createdBy}",
            "type": "participants"
        },
        "actiondocuments.tag": {
            "href": "https://raveena--ap-southeast-2.actionstepdev.com.actionstep.com/api/rest/tag/{actiondocuments.tag}",
            "type": "tag"
        },
        "actiondocuments.documentTemplate": {
            "href": "https://raveena--ap-southeast-2.actionstepdev.com.actionstep.com/api/rest/documenttemplates/{actiondocuments.documentTemplate}",
            "type": "documenttemplates"
        }
    },
    "actiondocuments": {
        "id": 129,
        "name": "My action document",
        "modifiedTimestamp": "",
        "status": "uploaded",
        "keywords": null,
        "summary": null,
        "checkedOutTimestamp": null,
        "fileType": null,
        "checkedOutTo": null,
        "checkedOutEtaTimestamp": null,
        "fileSize": 35204,
        "extension": ".",
        "sharepointUrl": "",
        "fileName": "15_20221124095129_My_action_document.",
        "isDeleted": "F",
        "file": "DL::Actions::15::129",
        "links": {
            "action": "15",
            "checkedOutBy": null,
            "folder": null,
            "createdBy": "22",
            "tags": [
                "10001",
                "10002"
            ]
            "documentTemplate": null
        }
    },
    ...
}

Updating Multiple Tags

You can update more than one tag value in a single PUT request, for example:

PUT {api_endpoint}/api/rest/actiondocuments/129

{
    "actiondocuments": {
        "links": {
           "tags": [
                10001,
                10002,
                10003,
                10004,

            ]
        }
    }
}

The response will be the following:

{
    "links": {
        "actiondocuments.action": {
            "href": "https://raveena--ap-southeast-2.actionstepdev.com.actionstep.com/api/rest/actions/{actiondocuments.action}",
            "type": "actions"
        },
        "actiondocuments.checkedOutBy": {
            "href": "https://raveena--ap-southeast-2.actionstepdev.com.actionstep.com/api/rest/participants/{actiondocuments.checkedOutBy}",
            "type": "participants"
        },
        "actiondocuments.folder": {
            "href": "https://raveena--ap-southeast-2.actionstepdev.com.actionstep.com/api/rest/actionfolders/{actiondocuments.folder}",
            "type": "actionfolders"
        },
        "actiondocuments.createdBy": {
            "href": "https://raveena--ap-southeast-2.actionstepdev.com.actionstep.com/api/rest/participants/{actiondocuments.createdBy}",
            "type": "participants"
        },
        "actiondocuments.tags": {
            "href": "https://raveena--ap-southeast-2.actionstepdev.com.actionstep.com/api/rest/tags/{actiondocuments.tags}",
            "type": "tags"
        },
        "actiondocuments.documentTemplate": {
            "href": "https://raveena--ap-southeast-2.actionstepdev.com.actionstep.com/api/rest/documenttemplates/{actiondocuments.documentTemplate}",
            "type": "documenttemplates"
        }
    },
    "actiondocuments": {
        "id": 129,
        "name": "My Action Document 2",
        "modifiedTimestamp": "",
        "status": "uploaded",
        "keywords": null,
        "summary": null,
        "checkedOutTimestamp": null,
        "fileType": null,
        "checkedOutTo": null,
        "checkedOutEtaTimestamp": null,
        "fileSize": 35204,
        "extension": "",
        "sharepointUrl": "",
        fileName": "15_20221124105546_My_Action_Document_2.",
        "isDeleted": "F",
        "file": "DL::Actions::15::129",
        "links": {
            "action": "15",
            "checkedOutBy": null,
            "folder": null,
            "createdBy": "22",
            "tags": [
                "10001",
                "10002",
                "10003",
                "10004"
            ],
            "documentTemplate": null
        }
    },
    }
}

Locating Documents Based on Tags

You can apply a filter to the actiondocuments endpoint when performing a GET request to locate documents by one or more tags. In the example below, the response will include all those documents that contain either the tag ID 10002 or the tag ID 10005.

Filtering action document with single tag:

GET {api_endpoint}/api/rest/actiondocuments?tags=10002

Filtering action document with multiple tags:

GET {api_endpoint}/api/rest/actiondocuments?tags_in=10002,10007

Summary

In this tutorial we showed how to create a matter document and assign multiple tags to its meta data. We also showed how you can change the assigned tags using a PUT request. Finally we showed how you can search for documents based on a filter containing one or more tags.