Iron Mountain InSight Core Data Vault (CDV) APIs
Contents
Introduction
The Core Data Vault (CDV) APIs are used to define and query metadata fields as well as to upload, edit and export documents.
The high level architecture diagram below shows the REST CDV APIs. This API documentation provides instructions for an IRM partner or customer to access these APIs.
Access to an environment for testing the APIs requires approval to get the necessary security tokens. Access by partners is only given to specific data when requested and agreed upon by an InSight customer.
The services below marked with * are for Q1 2020 (not yet released).
Document & Attribute Values APIs
Service Name | API Contracts | Note | Permissions Required |
---|---|---|---|
Create Asset Document & Attribute Values | POST /companies/{companyId}/documents Request Body: AssetDocument {
"documentTypeId":"00000000-0000-0000-0000-000000000001",
"fileName":"test.pdf",
"mlPipeline": "ml1",
"barcode": "20011234567890",
"attributeValues":[
{
"name": "departmentId",
"value": "2222"
},
{
"name": "divisionId",
"value": "1111"
},
{
"name": "majorDescription",
"value": "test 3"
},
{
"name": "count",
"value": "20"
}
]
}
Or remote storage for the document:
{
"documentTypeId":"00000000-0000-0000-0000-000000000001",
"fileName":"test.pdf",
"mlPipeline": "ml1",
"barcode": "20011234567890",
"remoteStorage":true,
"connectorConfigId":"ca1885e4-4207-474e-8cdf-3eabd70cafe2",
"externalDocumentId":"https://s3.amazonaws.com/bill-test-dit2/Insight/600163.pdf",
"attributeValues":[
{
"name": "departmentId",
"value": "2222"
},
{
"name": "divisionId",
"value": "1111"
},
{
"name": "majorDescription",
"value": "test 3"
},
{
"name": "count",
"value": "20"
}
]
} Response: AssetDocument {
"createdDate": "2018-07-30T17:49:10.042+00:00",
"createdUserId": "gateway",
"companyId": 2001,
"documentGUID": "c29d43fe-06a4-400e-9166-eb15f865d3b5",
"documentTypeId": "00000000-0000-0000-0000-000000000001",
"size": 0,
"state": "METADATA_UPLOADED",
"fileName": "test.pdf",
"fileStorageId": "00000000-0000-0000-0000-000000000001",
"deleted": false,
"lastAccessDate": "2018-07-30T17:49:10.042+00:00",
"lastAccessUserId": "gateway",
"mlPipeline": "ml1",
"pageCount": 0,
"barcode": "20011122334455",
"attributeValues": [
{
"attributeValueId": "39056acf-0810-4b7a-bb29-039aee57efbd",
"type": "long",
"value": "1111",
"name": "departmentId"
},
{
"attributeValueId": "83d0d652-670a-4d92-afcf-cdc3d098b57b",
"type": "long",
"value": "1111",
"name": "divisionId"
},
{
"attributeValueId": "7c6b05de-2258-4ce9-84e1-bd8f89bccab7",
"type": "String",
"value": "test 6",
"name": "majorDescription"
},
{
"attributeValueId": "aa95ca28-8a2f-4b99-bd6d-23d32fd4aefb",
"type": "long",
"value": "1",
"name": "count"
}
],
"remoteStorage": false,
"imageURL": "https://storage.cloud.google.com/rmaas-us-dit1/company/2001/...",
"imageDownloadURL": "https://storage.googleapis.com/rmaas-us-dit1/company/2001/...",
"imageUploadURL": "https://storage.googleapis.com/rmaas-us-dit1/company/2001/...",
"imageContentType": "application/pdf"
}
|
|
|
Update Asset Document & Attribute Values * | PUT /companies/{companyId}/documents/{documentGUID} Request Body: AssetDocument
{
"state": "METADATA_UPLOADED",
"fileName": "test.pdf",
"mlPipeline": "ml1",
"facility": "test",
"barcode": "20011122334455",
"attributeValues":[
{
"name": "departmentId",
"value": "2222"
},
{
"name": "divisionId",
"value": "1111"
},
{
"name": "majorDescription",
"value": "updated description"
},
{
"name": "count",
"value": "1"
}
]
}
Response: AssetDocument |
|
|
Update a document Attribute Values Only * | PUT /companies/{companyId}/documents/{documentGUID}/attributes Request Body: List<AssetAttributeValue> Response: List<AssetAttributeValue> |
|
|
Update Asset Document State Only | PUT /companies/{companyId}/documents/{documentGUID}/fields/state/{state} Request Examples: companies/2001/documents/c29d43fe-06a4-400e-9166-eb15f865d3b5/fields/state/DOCUMENT_UPLOADED companies/2001/documents/c29d43fe-06a4-400e-9166-eb15f865d3b5/fields/state/METADATA_UPLOADED Response: AssetDocument | This API updates the document state only. The new state is passed in the URL. Available states are
|
|
Get Asset Document * | GET /companies/{companyId}/documents/{documentGUID} Response: AssetDocument |
|
|
Delete Asset Document | DELETE /companies/{companyId}/documents/{documentGUID}? Query Parameter: permanent is optional (true or false), requestId is optional (any string). if permanent=true, the document and its related data will be deleted permanently immediately. Response: 1 | document and attribute values are deleted |
|
Restore/Undo-Delete Asset Document | PATCH /companies/{companyId}/documents/{documentGUID} Response: AssetDocument |
| |
Query All documents * | GET /companies/{companyId}/documents Query Parameter: deletedOnly is optional. Only soft-deleted documents returned if deletedOnly=true |
|
|
Get attribute value histories for a Document | GET /companies/{companyId}/documents/{documentGUID}/histories Response: List<AssetAttributeValueHist> | ||
Get attribute value histories for a company | GET /companies/{companyId}/documents/histories Response: List<AssetAttributeValueHist> | ||
Download the media File for a document | GET /companies/{companyId}/documents/{documentGUID}/media Response: A file content |
| |
Update document metadata in Batch mode | PUT companies/{companyId}/documents?state=<30 or 40> Request: See document_batch_metadata_esMetaData.json Response: | Internal Use only | |
Trigger A Destruction Process for Documents, their attribute values and image/support files | DELETE: /companies/{companyId}/documents?requestId=<request id> Request Body: List<String> documentGUIDs, List<String> emailTos. Response: 1, process is started successfully; 0 otherwise. |
|
|
Download the Destruction Report for a request | GET: /companies/{companyId}/documents/destructionReport Request Param: emailTos (optional), requestId (optional), fromDate (optional) - ISO date format, toDate (optional) - ISO date format Response: a csv file |
| |
Calculate the Retention Destruction Eligibility Date for a Document * Internal Use Only | PATCH: /companies/{companyId}/documents/{documentGUID}/retention/calculation Response: AssetDocument with retention attribute values |
|
|
Trigger a Task to Calculate the Retention Destruction Eligibility Date for all Documents of a Company * Internal Use Only | PATCH: /companies/{companyId}/documents/retention/calculation Response: 1, the task is started successfully; 0 otherwise. |
| |
Trigger a Task to Calculate the Retention Destruction Eligibility Date for all Documents of a Document Type * Internal Use Only | PATCH: /companies/{companyId}/documentTypes/{docTypeId}/documents/retention/calculation Response: 1, the task is started successfully; 0 otherwise. |
|
|
Trigger a Task to Reset the Retention Calculation Status for all Documents of a Company * | PATCH: /companies/{companyId}/documents/retention/status Response: 1, the task is started successfully; 0 otherwise. |
| |
Trigger a Task to Reset the Retention Calculation Status for all Documents of a Document Type * | PATCH: /companies/{companyId}/documentTypes/{docTypeId}/documents/retention/status Response: 1, the task is started successfully; 0 otherwise. |
|
|
Example image URLs:
Document State Mappings
State Text in Request/Response | State Value |
---|---|
METADATA_UPLOADED | 10 |
DOCUMENT_UPLOADED | 20 |
PROCESSED | 30 |
INDEXED | 40 |
REPROCESS | 50 |
Retention Calculation Status
Retention Calculation Status | |
---|---|
RECALCULATE | ready for calculation |
CALCULATING | in the process of calculation |
DONE | calculation is finished with RetentionErrorCode (see below table). |
Retention Error Code
Retention error code | |
---|---|
SUCCESS | Retention eligibility date is calculated successfully. |
RETENTION_PERIOD_MISSING | There is no retention period. |
RETENTION_PERIOD_UNIT_MISSING | There is no retention period unit. Usually it is years, months, days for PCS retention rules. |
RETENTION_PERIOD_UNIT_INVALID | The retention period unit is not either of years, months, days. |
DOCUMENT_TYPE_MISSING | There is no document type id for the document. |
RULE_MISSING | There is no retention rule for the document type of the document. |
RETENTION_TRIGGER_ATTRIBUTE_MISSING | There is no retention trigger attribute id (name) for the retention rule of the document type of the document. |
RETENTION_TRIGGER_DATE_MISSING | There is no attribute value for the document for the retention trigger attribute. |
RETENTION_TRIGGER_DATE_INVALID_TYPE | The attribute value is not a "Date" type. |
RETENTION_TRIGGER_DATE_INVALID | The attribute value (string presentation) cannot be parsed as a Date. |
NO_RETENTION_TYPE | The company is neither CUSTOMER nor PCS retention type. |
EXCEPTION | Runtime exception(s) occur during the calculation. |
Document Images / Files APIs
ES stands for ElasticSearch
Service Name | API Contracts | Note | Permissions Required |
---|---|---|---|
Update ES metadata only | PUT /companies/{companyId}/documents/{documentGUID}/es Request Body: text |
| |
Get ES metadata | GET /companies/{companyId}/documents/{documentGUID}/es Response : text |
| |
Upload/Update an Image | POST /companies/{companyId}/documents/{documentGUID}/image Request Body: multipart/form-data (file & fileName) |
|
|
Upload/Update an Image by resource | PUT /companies/{companyId}/documents/{documentGUID}/image Request Body: ResourceUploadInfo |
|
|
Download an Image | GET /companies/{companyId}/documents/{documentGUID}/image Response: URL |
| |
Upload/Update a Support File | POST /companies/{companyId}/documents/{documentGUID}/files Request Body: multipart/form-data (file & fileName) |
|
|
Download a Support File | GET /companies/{companyId}/documents/{documentGUID}/files/{fileName} Response: URL |
| |
Delete a Support File | DELETE /companies/{companyId}/documents/{documentGUID}/files/{fileName} |
| |
Delete all of Support Files | DELETE /companies/{companyId}/documents/{documentGUID}/files |
| |
List all of Support Files | GET /companies/{companyId}/documents/{documentGUID}/files |
|
Requirements for a file name
fileName and filename must be less than 950 characters. They can not contain the following characters.
Attributes / Metadata Fields APIs
Service Name | API Contracts | Note | Permissions Required |
---|---|---|---|
Get metadata fields Data Type Mapping | GET /companies/{companyId}/attributes/dataTypes Response : AssetMetadataTypeListResponse | ||
Get Asset Attribute | GET /companies/{companyId}/attributes/{attributeId} Request Body: None Response : AssetAttribute | An authenticated user with the following permissions:
OR
| |
Query Asset Attributes | GET /companies/{companyId}/attributes Support Query Pagination, Sorting and Filtering Response: List<AssetAttribute> | ||
Create Attribute | POST /companies/{companyId}/attributes Request Body: List<AssetAttribute> Response: AssetAttribute |
| An authenticated user with the following permissions:
|
Update Asset Attribute | PUT /companies/{companyId}/attributes/{attributeId} Request Body: AssetAttribute Response : AssetAttribute | An authenticated user with the following permissions:
| |
Update Asset Attributes | PUT /companies/{companyId}/attributes Request Body: List<AssetAttribute> Response: AssetAttributeListResponse | An authenticated user with the following permissions:
| |
Delete Asset Attribute | DELETE /companies/{companyId}/attributes/{attributeId} Request Body: None Response : ServiceResponse<Integer> | An authenticated user with the following permissions:
| |
Delete Asset Attributes | DELETE /companies/{companyId}/attributes Request Body: List<String> - a list of attributeId's Response : ServiceResponse<Integer> | An authenticated user with the following permissions:
| |
Assign/Unassign/Override an attribute Id to document type ids * | PUT /companies/{companyId}/attributes/{attributeId}/documentTypes?action=<ASSIGN,UNASSIGN or OVERRIDE> Request Body: documentTypeIds Response: AssetAttribute |
| An authenticated user with the following permissions:
|
Assign/Unassign/Override attribute Ids to document type ids * | PUT /companies/{companyId}/attributes/documentTypes?action=<ASSIGN,UNASSIGN or OVERRIDE> Request Body: attributeIds and documentTypeIds Response: List<AssetAttribute> |
| An authenticated user with the following permissions:
|
Supported attribute data types
Attribute Type | Attribute Value |
---|---|
int | A string represents an integer, for example, "123" |
long | A string represents a big integer, for example "1298381" |
Date | A string represents a date or date and time in the following format patterns which are defined in Java 8 SimpleDateFormat. |
String | A plain text string |
boolean | A string of "true" or "false" |
double | A string represents a double, for example "1.0", or "1" |
Coordinates | A string represents a coordinates point in format of "Numeric, Numeric[, Numeric]", for example "40.112312, -71.192291" |
Document Type APIs
Service Name | API Contracts | Note | Permissions Required |
---|---|---|---|
Create a Document Type | POST /companies/{companyId}/documentTypes Request Body: AssetDocumentType Response: AssetDocumentType |
|
|
ASSIGN/UNASSIGN/OVERRIDE Attributes for a Document Type * | PUT /companies/{companyId}/documentTypes/{docTypeId}/attributes Query Parameter: action=ASSIGN/UNASSIGN/OVERRIDE, default is OVERRIDE Request: attributeIds Response: AssetDocumentType with updated attributes |
|
|
ASSIGN/UNASSIGN/OVERRIDE Attributes for Document Types * | PUT /companies/{companyId}/documentTypes/attributes Query Parameter: action=ASSIGN/UNASSIGN/OVERRIDE, default is OVERRIDE Request: attributeIds and documentTypeIds Response: List<AssetDocumentType> with updated attributes |
|
|
Query Document Types & Attributes by a company | GET /companies/{companyId}/documentTypes Support Query Pagination, Sorting and Filtering Response: List<AssetDocumentType> |
| |
Update a Document Type | PUT /companies/{companyId}/documentTypes/{docTypeId} Request Body: AssetDocumentType without attributes Response: AssetDocumentType without attributes |
|
|
Update PCS Document Type Id * | PUT /companies/{companyId}/documentTypes/{docTypeId}/pcsDocumentTypeId/{pcsDocTypeId} Response: AssetDocumentType without Retention Rules |
|
|
Update Retention Trigger Attribute for a Retention Rule of a Document Type * | PUT /companies/{companyId}/documentTypes/{docTypeId}/rules/retention/{ruleId}/attribute/{attributeId} Response: AssetDocumentType |
|
|
Update Retention Trigger Attribute for all Retention Rules of a Document Type * | PUT /companies/{companyId}/documentTypes/{docTypeId}/rules/retention/attribute/{attributeId} Response: AssetDocumentType |
|
|
Get a Document Type * | GET /companies/{companyId}/documentTypes/{docTypeId} Response: AssetDocumentType |
|
|
Get a list of Document Types by ids | PUT /companies/{companyId}/documentTypes Query Parameters: details - include attributes in the response or not, default is true Request Body: documentTypeIds Response: List<DocumentType> |
| |
Delete a Document Type | DELETE /companies/{companyId}/documentTypes/{docTypeId} Response: 1 | Delete the document type in the spanner rmaas_document_type table if no documents is linked to this document type. |
|
Retention Status
Each document type has a retention status indicating the availability of the retention rules and their retention information. If a company is NONE retention type, all document types of the company should have retentionStatus=NONE.
Retention status | |
---|---|
NONE | The document type should not have a retention rule. |
REQUESTED | PCS document type is requested, but there are no retention rules are created on the PCS yet. (TBD for a document type with CUSTOMER retention type) |
RETENTION_PERIOD_MISSING | Retention rules are available, but retention period is missing |
RETENTION_TRIGGER_ATTRIBUTE_MISSING | The retention trigger attribute id(name) is not assigned yet. |
RETENTION_PERIOD_TRIGGER_ATTRIBUTE_MISSING | Neither retention period nor trigger attribute is available. |
READY | Retention rule includes retention period and trigger attribute. And it is ready for calculating the destruction eligibility date. |
URL Structure
https://cdvapi.<environment name>.com
Using a REST Client
Use a REST client such as the Google Rest Client
You will need to get an authorization token from the InSight Team
Include the token in the header when calling the service. See example below:
© 2020 Iron Mountain Incorporated. All Rights Reserved.