Tags and tag types
AirBase provides the ability to tag documents with metadata, called system tags. System tags are associated with user configured tag types: A tag type describes a structured tag which includes the tag type's name, its data type, and (optionally) a default value. Tag types are configured at the library level and must be associated with child folders. The child folders may also override any default values defined at the library level.
One example could be a tag type called Account Manager. Account Manager can be defined as a string with a default value of Jane Doe. This tag type is associated with a library called Accounts Payable. A child folder is associated with this tag type, and could have its default value overridden. For example, a child folder called Invoices could be associated with the Account Manager tag type and the default value changed to Joe Smith.
Configuring tag types
Creating a new tag type
As mentioned earlier, tag types can only be created at the library level. A tag type's name and associated properties are first created at the library level and then must be subsequently associated with its relevant child folders.
To create a new tag type, issue the following POST request:
POST /api/libraries/{libraryId}/tagtypes
Where:
- libraryId: the ID number of the library to create the tag on
With the following body:
{
"TagTypeName":"Account Manager",
"DataType":"{String|Date|Numeric}",
"Constraints": {constraints}
}
Where:
- TagTypeName: the string value that will become the name of the tag type - in the above example, this would be Account Manager
- DataType: a string in the set of {String|Date|Numeric} that indicates the data type of the tag type - in the Account Manager example, this would be a String
And where {constraints} is an object of the form:
{
"DefaultValue":"Jane Doe",
"DataSetValues":null
}
- Constraints: an object that defines the constraints for the tag type - if there are no constraints, this property can be omitted
- DefaultValue: the default value for this tag type, it should be applied as the value when a user uploads a document that has this tag type associated with it, and doesn't manually supply a value - its format must be consistent with its data type. Default values for date must be of the form MMddyyyy
- DataSetValues: data sets are not presently implemented for tag types and, as an optional parameter, may be ignored
The response returns a TagType object in the response body like the following:
{
"TagTypeId": 2752,
"TagTypeName": "Account Manager",
"FlavorName": "Simple",
"DataType": 0,
"DataTypeName": "String",
"Constraints": "{\"DefaultValue\":\"Jane Doe\",\"DataSetValues\":null}",
"Links": {
"TagValuesUri": "https://app.sharebase.com/sharebaseapi/api/tagtypes/2752/values"
}
}
Getting the tag types on a library
To retrieve the tag types associated with a library, issue the following GET request:
GET /api/libraries/{libraryId}/tagtypes
Where:
- libraryId: the ID number of the library to retrieve the tag types for
The response is an array of tag types:
[
{tagtype1},
{tagtype2},
{...}
]
Click here to see the structure of the tag type object.
To retrieve the tag types with a specific tag type name associated with a library, issue the following GET request:
GET /api/libraries/{libraryId}/tagtypes/{tagTypeName}
Where:
- libraryId: the ID number of the library to retrieve the tag types for
- tagTypeName: the tag type name of the tag types to retrieve
The response is an array of tag types:
[
{tagtype1},
{tagtype2},
{...}
]
Click here to see the structure of the tag type object.
Note, if the library does not exist, or if the tag type name could not be found, an HTTP 404 Not Found status code is returned along with a message indicating which object could not be found.
If the user does not have read access for the library, an HTTP 403 Forbidden status code is returned with the following response body:
{
"AccessDenied" : true,
}
Where:
- AccessDenied: will have a value of true indicating that access was denied
Associating tag types to a folder
Once a tag type is created at the library level, it must be associated with one or more child folders.
To associate one or more tag types to a folder, issue the following PUT request:
PUT /api/folders/{folderId}/tagtypes
Where:
- folderid: the ID number of the folder to associate with the supplied tagtype(s)
With the following body:
[
{association1},
{association2},
{association3}
]
Where:
- {association} is an object of the form:
{
"TagTypeId" : 2752,
"Constraints" : {
"DefaultValue":"Joe Smith",
"DataSetValues":null
}
}
Where:
- TagTypeId: is the unique identifier for the tag type.
- Constraints: see constraints.
Getting the tag types associated with a folder
To get a list of currently configured tag types for a folder, issue the following GET request:
GET /api/folders/{folderId}/tagtypes
Where:
- folderId: the ID number of the folder to retrieve the configured tags of
This will return an array of tag types:
[
{tagtype1},
{tagtype2},
...
]
Click here for the structure of the tag type.
Updating constraints on a tag type
You can update the constraints on a tag type either at the folder level or the library level. Updating the constraints at the library level applies default constraints in the case where a child folder has not overridden the constraints. Applying constraints at the folder level applies these overrides.
Issue the following PUT request:
PUT /api/libraries/{libraryid}/tagtypes/{tagtypeId}/constraints
PUT /api/folders/{folderid}/tagtypes/{tagtypeId}/constraints
The body of the post should be a constraints object.
You can also issue a PATCH on a tag type to update just the name, the constraints, or both:
PATCH /api/libraries/{libraryId}/tagtypes/{tagtypeId}
With a body of the new values:
{
"TagTypeName": "Account Senior Manager",
"Constraints": {
"DefaultValue": "Mary Sue",
"DataSetValues": null
}
}
Using system tags
Setting the value of a tag type
Once one or more tag types have been created at the library level and assigned to a child folder, each document in that folder is able to have its own values assigned to those tag types.
Issue the following PUT request:
PUT /api/documents/{documentId}/systemtags
Where:
- documentid - the unique identifier of the document to set the tag values on
With the following body:
[
{TagTypeValue1},
{TagTypeValue2},
{TagTypeValue3}
]
Where:
{
"TagTypeId":2752,
"Value":"Larry McDonald"
}
Where:
- TagTypeId: the unique identifier of the tag type to supply a value for
- Value: a string value to set as the value of this tag on this document - the string value must be consistent with the data type, for example, values for a Numeric data type must be strings that can be parsed as a number, and values for a Date must be strings of the form MMddyyyy
This supplied value should respect any constraints set on the tag type at the folder and library levels: it is up to the consumer of the API to respect constraints, as the API will not enforce these constraints to allow for legacy values.
Note: any tag types on the document that do not get supplied a tag type value object in the PUT request will have their value reset to null.
Getting the values of tag types associated with a document
To get a list of the current tag type values for a document, issue the following GET request:
GET /api/documents/{documentId}/tags
Where:
- documentId: the unique identification number of the document to retrieve the tag values of
The response returns an array of Tag objects like the following:
[
{
"TagTypeId": 2752,
"TagTypeName": "Account Manager",
"Tags": [
"Larry McDonald"
]
},
{
"TagTypeId": 2753,
"TagTypeName": "Order Date",
"Tags": [
"01302017"
]
}
]
Where:
- TagTypeId: the unique identifier for this tag type
- TagTypeName: the string name of this tag type
- Tags: an array of strings that holds the value(s) of this tag type for this document - presently, only one value can be assigned to a tag type on a document
Getting all values of a tag type
To get a list of the current tag type values for any given tag, issue the following:
GET /api/tagtypes/{tagtypeId}/values
Where:
- tagtypeId: the unique identification number of the tag type to retrieve the values of
The response returns an array of all values that are currently attached to that tag type. For our Account Manager example, it might return the following:
[
"Jane Doe",
"Joe Smith",
"Larry McDonald"
]
Searching across a library or folder based on tag values
The API provides the ability to search for documents with given values for multiple tag types, either on a per folder basis, or across a whole library.
Issue the following PUT request:
POST /api/libraries/{libraryId}/search/systemtags-v2
POST /api/folders/{folderId}/search/systemtags-v2
Where:
- libraryId: the ID of the library to search
- fodlerId: the ID of the folder to search
With the following body:
[
{TagTypeValue1},
{TagTypeValue2},
{TagTypeValue3}
]
Using older version of this endpoint?
The body of the post is an array of Tag Type Value objects where:
- TagTypeId: the unique identifier of the tag type that you are searching on
- Value: the value for the tag type that you are searching for
The response is an object that contains a count of the documents that match the search criteria and the documents themselves, like the following:
{
"TotalCount": 1,
"Embedded": {
"Documents": [
{
"DateModified": "2018-02-28T21:03:15.1",
"DocumentId": "2063",
"DocumentName": "9SF invoice 9",
"DocumentAutoName": "Order Date: 2/8/2017 \u0000 | \u0000 Account Manager: Larry McDonald",
"FolderId": 82,
"FolderName": "Invoices",
"LibraryName": "Accounts Payable",
"StatusInformation": [
{
"TagTypeName": "&&_AirBase_Content_Status",
"TagValueString": "",
"TagValueNumeric": null,
"TagValueDate": null,
"DataType": 0
},
{
"TagTypeName": "&&_AirBase_ToDo_Status",
"TagValueString": "ToDo status 2",
"TagValueNumeric": null,
"TagValueDate": null,
"DataType": 0
},
{
"TagTypeName": "&&_AirBase_Assigned_Date",
"TagValueString": null,
"TagValueNumeric": null,
"TagValueDate": "2017-07-13T00:00:00",
"DataType": 2
},
{
"TagTypeName": "&&_AirBase_Assigned_UserId",
"TagValueString": null,
"TagValueNumeric": 12,
"TagValueDate": null,
"DataType": 1
}
],
"Links": {
"Self": "https://app.sharebase.com/sharebaseapi/documents/2063",
"Content": "https://app.sharebase.com/sharebaseapi/documents/2063/content",
"DocumentUri": "https://app.sharebase.com/sharebaseapi/documents/2063",
"FolderUri": "https://app.sharebase.com/sharebaseapi/folders/82",
"LibraryUri": "https://app.sharebase.com/sharebaseapi/libraries/13",
"FolderIconUri": "https://app.sharebase.com/sharebaseapi/icons/28"
}
}
]
}
}