{ "openapi": "3.0.3", "info": { "title": "ADAS AID v2", "description": "ADAS is an AT&T internal tool that allows archiving files, searching for them and retrieving them. \nThese are the APIs ADAS exposes to its customers.", "contact": { "email": "gh253d@intl.att.com" }, "version": "2.0.0" }, "externalDocs": { "description": "ADAS AID", "url": "https://att-my.sharepoint.com/:u:/p/gh253d_intl/Efr5qVCpzqREkFlKLPox2bABup-TxFNthQyXEUL_UKnp_g?email=golan.harel%40intl.att.com&e=esapx0" }, "tags": [ { "name": "ADAS APIs", "description": "AT&T Document & Archive System Interface.", "externalDocs": { "description": "AID", "url": "https://att-my.sharepoint.com/:w:/r/personal/gh253d_intl_att_com/Documents/ADAS%20AID/Future%20API/ADAS%20-%20Application%20Interface%20Design%20-%20Future%20AID.docx?d=w58b94e0eb9164c1ea7aef24862afd775&csf=1&web=1&e=fATIeH" } }, { "name": "Document Groups", "description": "Operations performed on Document Groups." }, { "name": "Document Folders", "description": "Operations performed on Document Folders." }, { "name": "Archive", "description": "Upload and download links." }, { "name": "Search", "description": " Search Documents." }, { "name": "Document Operations", "description": "Operations performed on documents." }, { "name": "Dashboard", "description": "Presentation layer." } ], "paths": { "/document-groups": { "post": { "tags": [ "Document Groups" ], "summary": "Create a document group.", "description": "Create a single documentGroup.", "operationId": "createGroup", "requestBody": { "description": "Create a new documentGroup.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentGroup" } } }, "required": true }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentGroup" } } } }, "400": { "description": "BAD REQUEST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "409": { "description": "CONFLICT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "get": { "tags": [ "Document Groups" ], "summary": "Search all document groups or documentGroup by name.", "description": "Provides a list of all documentGroups existing in the system or a one documentGroup (not ina an array) when searched by an existing name.", "operationId": "getAllGroups", "parameters": [ { "name": "name", "in": "query", "required": false, "description": "documentGroup Name.", "example": "contracts", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/documentGroup" } } } } } } }, "404": { "description": "NOT_FOUND (only when name is provided and not found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/document-groups/{id}": { "get": { "tags": [ "Document Groups" ], "summary": "Get a single document group by ID.", "description": "Provides a single documentGroup details.", "operationId": "getSingleGroup", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the document group.", "example": "g1", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentGroup" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "put": { "tags": [ "Document Groups" ], "summary": "Update a document group.", "description": "Allows to update all documentGroup's data except for its ID or Name. Must send all data on every call.", "operationId": "updateDocumentGroup", "parameters": [ { "name": "id", "in": "path", "description": "documentGroup ID. When sent also in the body (not required), it must match with this value.", "required": true, "example": "g1", "schema": { "type": "string" } } ], "requestBody": { "description": "update an existing documentGroup.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentGroup" } } }, "required": true }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentGroup" } } } }, "400": { "description": "BAD REQUEST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "409": { "description": "CONFLICT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/document-folders": { "post": { "tags": [ "Document Folders" ], "summary": "Create a document folder.", "description": "Create a single documentFolder.", "operationId": "createFolder", "requestBody": { "description": "Create a new documentFolder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentFolder" } } }, "required": true }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentFolder" } } } }, "400": { "description": "BAD REQUEST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "409": { "description": "CONFLICT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "put": { "tags": [ "Document Folders" ], "summary": "Update a document folder by name.", "description": "Allows to update all documentFolder's fields except for its ID or Name.", "operationId": "updatedocumentFolder", "parameters": [ { "name": "name", "in": "query", "description": "documentFolder name. Only one (id or name) is required.", "required": true, "explode": false, "example": "contracts_folder", "schema": { "type": "string" } } ], "requestBody": { "description": "update an existing documentFolder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentFolder" } } }, "required": true }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentFolder" } } } }, "400": { "description": "BAD REQUEST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "409": { "description": "CONFLICT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "get": { "tags": [ "Document Folders" ], "summary": "Get all document folders or one by name.", "description": "Returns all documentFolders in an array. When specifying a name, return just one (not in an array).", "operationId": "getAllFolders", "parameters": [ { "name": "name", "in": "query", "description": "documentFolder name. When provided returns one, otherwise returns all.", "required": false, "example": "contracts_folder", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentFolder" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/document-folders/{id}": { "get": { "tags": [ "Document Folders" ], "summary": "Get a single document folder by id.", "description": "Rerurns a single documentFolder.", "operationId": "getSingleFolder", "parameters": [ { "name": "id", "in": "path", "description": "documentFolder id. When id does not exist returns an error, otherwise returns one record.", "required": true, "allowEmptyValue": true, "example": "f15", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentFolder" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "put": { "tags": [ "Document Folders" ], "summary": "Update a document folder by id.", "description": "Allows to update all documentFolder's fields except for its ID or Name.", "operationId": "updatedocumentFolderById", "parameters": [ { "name": "id", "in": "path", "description": "documentFolder ID.", "required": true, "explode": false, "example": "f15", "schema": { "type": "string" } } ], "requestBody": { "description": ".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentFolder" } } }, "required": true }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/documentFolder" } } } }, "400": { "description": "BAD REQUEST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "409": { "description": "CONFLICT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/dashboard/document-folders/{name}": { "get": { "tags": [ "Dashboard" ], "summary": "Get the client's screen layout for a specific folder", "description": "Extract, from the documentFolder and its associated documentGroups, information needed for the customer's UI.", "operationId": "getFolderScreenDisplay", "parameters": [ { "name": "name", "in": "path", "description": "documentFolder name.", "required": true, "explode": false, "example": "contracts_folder", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/screenDisplay" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/archive/upload-links": { "get": { "tags": [ "Archive" ], "summary": "Get the upload link to upload documents to ADAS (using azcopy).", "description": "Provides an upload link containing a SAS (Shared Access Signature) with read, write and crete permissions only. The SAS, hence the link, is available for 24 hours in which you can upload files.", "operationId": "getUploadURL", "responses": { "200": { "description": "Successful Response.", "content": { "uploadUrl": { "schema": { "type": "string", "description": "The URL to use as a whole in the AZCOPY tool.", "example": "https:///stage?sv=2021-04-10&se=2023-09-15T12%3A44%3A37Z&sr=c&sp=racw&sig=s3QpNHXjNiwI10XS4JENSGNJ1jLP7VnGIxoj2bYMbzE%3D" } } } } } } }, "/archive/document-url/{id}": { "get": { "tags": [ "Archive" ], "summary": "Get a link to download a specific document from ADAS.", "description": "based on a document ID (_id), returns a download link containing a SAS (Shared Access Signature) to download the actual requested document. The SAS, hence the link, is available for 24 hours in which you can download the file requested.", "operationId": "getUDownloadURL", "parameters": [ { "name": "id", "in": "path", "description": "The Document ID (_id) found in the search document results.", "required": true, "explode": false, "example": "NHXjNiwI10XS4JENSGNJ1jLP7VnGIxoj2bYMbzE", "schema": { "type": "string" } }, { "name": "fullDocument", "in": "query", "description": "Applicable to AFP files only, when set to true, get the entire AFP file (may contain multiple documents) When false, gets one document our of the file (might be a subset of the whole document).", "required": false, "example": true, "schema": { "type": "boolean" } }, { "name": "cmodDocId", "in": "query", "description": "Optional. Default - false. When set to true, it means that the id provided to search by, as a resouce, is a cmodDocId and not an ADAS ID. (DV feature only).", "required": false, "example": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "downloadUrl": { "type": "string", "example": "https://prod02adasblobdpcust.blob.core.windows.net/archive/NEXTGEN_AG_S%2F2023%2F09%2F09%2F726185bb-12af-42a1-81fd-9029ce7fe1dc?sv=2023-08-03&se=2023-12-13T12%3A32%3A21Z&sr=b&sp=r&sig=SwFMySLm0RrzckE3uE6P3KoYFOZY15epVXsv13StQrU%3D", "description": "The download link containing a SAS (Shared Access Signature). The SAS, hence the link, is available for 24 hours in which you can dlwonload the file." }, "filename": { "type": "string", "example": "my-upload-file-1973.pdf", "description": "The filename as uploaded to ADAS / Migrated from CMOD including its extension. For partial AFP document the extension of a single document is changed to .afp even if the original document is a .out file." } } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/search/documents": { "get": { "tags": [ "Search" ], "summary": "Search for documents within a defined document folder.", "description": "Allows to search documents, based on a query sent, on all documentGroups associated with the specified documentFolder, resulting zero to many metadata items related to uploaded documents, each with all its details.", "operationId": "SearchDocumentsByFolder", "parameters": [ { "name": "folderName", "in": "query", "description": "documentFolder name to search by - either folderName or groupName are required - not both", "required": true, "explode": true, "example": "contracts_folder", "schema": { "type": "string" } }, { "name": "groupName", "in": "query", "description": "documentGroup name to search by - either folderName or groupName are required - not both", "required": false, "explode": true, "example": "contracts", "schema": { "type": "string" } }, { "name": "$filter", "in": "query", "description": "oData (See AID) to search by. When documentGroup is passed the field names are the group's, when the folderName is provided, the field names are the searchNames defined in the documentFolder.", "required": true, "explode": true, "example": "$filter=accounts gt 3 and CustomerName like 'ATT*USA*'", "schema": { "type": "string" } }, { "name": "$limit", "in": "query", "description": "Number of results to return (up to 10,000).", "required": true, "explode": true, "schema": { "type": "integer" } }, { "name": "invisibleOnly", "in": "query", "description": "Optional: when true: Shows only document metadata items marked as invisible.When false (default), shows only documents marked as visible true..", "required": false, "explode": true, "example": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "successful operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hasMore": { "type": "boolean", "example": true, "description": "When true, specifies that there are more results for this query than the $limit." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/document" } } } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/search/documents/count": { "get": { "tags": [ "Search" ], "summary": "Upload count per document group on a date range.", "description": "Get a summary of the total number of uploads made, with a count per documentGroup between a provided date range.", "operationId": "getCount", "parameters": [ { "name": "fromDate", "in": "query", "description": "UTC. Format: mm-dd-yyyy. (Beginning of the day)", "required": true, "explode": false, "example": "2023-08-14", "schema": { "type": "string", "format": "date" } }, { "name": "toDate", "in": "query", "description": "UTC. Format: mm-dd-yyyy. (End of the day)", "required": true, "explode": true, "example": "2023-08-14", "schema": { "type": "string", "format": "date" } }, { "name": "gmt", "in": "query", "description": "Optional. Default: 0. Decimal. An offset for the time of the day (from midnight). for example, if the user wants midnight EST, the value will be -5, ADAS will calculate from 7PM UTC of the previous day to 7PM UTC of the next day. ", "required": false, "example": -5.5, "schema": { "type": "number" } } ], "responses": { "200": { "description": "successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/uploadCount" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/search/documents/download-count": { "get": { "tags": [ "Search" ], "summary": "Counts the number request for download URL. (ADAS can't count the actual download as it is done directly from the Azure Blob).", "description": "Get a summary of the total number of get download URL requests made, including a count per documentGroup distibution between a provided date range.", "operationId": "getDownloadCount", "parameters": [ { "name": "fromDate", "in": "query", "description": "UTC. Format: mm-dd-yyyy. (Beginning of the day)", "required": true, "explode": false, "example": "2023-08-14", "schema": { "type": "string", "format": "date" } }, { "name": "toDate", "in": "query", "description": "UTC. Format: mm-dd-yyyy. (End of the day)", "required": true, "explode": true, "example": "2023-08-14", "schema": { "type": "string", "format": "date" } }, { "name": "gmt", "in": "query", "description": "Optional. default: 0. Decimal. An offset for the time of the day. for example, if the user wants midnight EST, the value will be -5, ADAS will calculate from 7PM UTC of the previous day to 7PM UTC of the next day. ", "required": false, "example": -5.5, "schema": { "type": "number" } } ], "responses": { "200": { "description": "successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/downloadCount" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "500": { "description": "INTERNAL_SERVER_ERROR", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } }, "/documents": { "put": { "tags": [ "Document Operations" ], "summary": "Update a document visibility.", "description": "This API updates a document metadata item(s).", "parameters": [ { "name": "documentId", "in": "query", "description": "Required if uploadId is not provided. Updates a single metadata item.", "required": false, "explode": false, "example": "4cfcf60d-bb49-46b0-b8f8-f5735c4220c5", "schema": { "type": "string" } }, { "name": "uploadId", "in": "query", "description": "Required if documentId is not provided. Updates all metadata items with the same uploadId provided upon upload. Could refer to one or multiple files.", "required": false, "explode": false, "example": "EOSJLMDwI10XS749NSGNJ1jLP7VnGIWsdew233Sk", "schema": { "type": "string" } }, { "name": "entireDoc", "in": "query", "description": "Relevant only when documentId is provided, updates all metadata referring to the same physical file (non AFP) or a specific documet within an AFP file when containig multiple documents).", "required": false, "example": true, "schema": { "type": "boolean" } } ], "requestBody": { "description": "Allows to update a document's metadata object as visibile or invisible affecting its visibility in search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateDocBody" } } } }, "responses": { "201": { "description": "successful operation." }, "400": { "description": "BAD_REQUEST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } }, "delete": { "tags": [ "Document Operations" ], "summary": "Delete documents.", "description": "This API allows to delete a document or a group of documents' metadata. In case the last reference to a physical file is deleted, the file is deleted as well.", "parameters": [ { "name": "documentId", "in": "query", "description": "Required if uploadId is not provided. Deletes a single metadata data item. If it is the last one, the file is deleted from the archive.", "required": false, "explode": false, "example": "4cfcf60d-bb49-46b0-b8f8-f5735c4220c5", "schema": { "type": "string" } }, { "name": "uploadId", "in": "query", "description": "Required if documentId is not provided. Deletes all metadata items with the same uploadId provided upon upload including the physical files from the archive. Could be one or multiple files.", "required": false, "explode": false, "example": "EOSJLMDwI10XS749NSGNJ1jLP7VnGIWsdew233Sk", "schema": { "type": "string" } }, { "name": "entireDoc", "in": "query", "description": "Relevant for documentId only, deletes all metadata referring to the same phisical file and deletes the file itself (If pointing to a single document in a multiple documents AFP, the file remainsa as long as it is not the last reference to the AFP file). ", "required": false, "example": false, "schema": { "type": "boolean" } } ], "responses": { "202": { "description": "ACCEPTED" }, "400": { "description": "BAD_REQUEST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errorModel" } } } } } } } }, "components": { "schemas": { "errorModel": { "type": "object", "description": "A generic error structure.", "properties": { "code": { "type": "integer", "format": "int64", "example": 1007, "description": "ADAS internal code." }, "message": { "type": "string", "example": "Specific error message", "description": "ADAS message of the specific error code" }, "additionalInfo": { "type": "string", "example": "Specific error message", "description": "Defines the document retention period in months" } } }, "documentGroup": { "type": "object", "description": "DocumentGroup(s) are the equivalent of ApplicationGroup within CMOD. They provide a category into which to place archived documents and include the definition of certain parameters/settings for the group – such as Retention Period, as well as the definition of metadata items to be set for documents being associated with the group. The DocumentGroup into which to place an uploaded document must be specified upon upload.", "required": [ "name", "retentionPeriod", "fields" ], "properties": { "id": { "type": "string", "example": "g1", "readOnly": true, "description": "POST - Auto generated. PUT - When provided, must match with the id in the url." }, "name": { "type": "string", "maxLength": 256, "example": "contracts", "description": "POST – required - Must be unique, PUT – identifier – cannot be changed. Allowed characters: alphanumeric (a-z, A-Z, 0-9), underscore '_' and dash '-'" }, "description": { "type": "string", "maxLength": 256, "description": "Optional. A more descriptive field to the group name. Allowed characters: alphanumeric (a-z, A-Z, 0-9), underscore '_', dash '-' and space ' '.", "example": "Special Contracts" }, "forceAllMetadata": { "type": "boolean", "default": false, "description": "Optional. Default: false. When set to true, forces all metadata of the documentGroup fields to be sent (even with null value) when uploading a document, otherwise an error is returned. When set to false, at least one metadata item matching the documentGroup should be sent, otherwise an error.", "example": true }, "creationDate": { "type": "string", "format": "date", "readOnly": true, "description": "Read-only. The date the documentGroup was first created.", "example": "2023-11-20" }, "lastUpdated": { "type": "string", "format": "date", "readOnly": true, "description": "Read-only. The date the documentGroup was last updated.", "example": "2024-03-08" }, "retentionPeriod": { "type": "integer", "format": "int64", "example": 61, "description": "Defines the document retention period in months." }, "legalHold": { "type": "boolean", "description": "Optional: Default: true. When set to true, prevents retiring documents under this documentGroup. When legalHoldStartDate, legalHoldEndDate are set and value is true, only documents within these dates are not purged upon retirement. When set to false, documents will purge upon retentionPeriod disregarding the legal hold dates.", "example": false, "default": true }, "legalHoldStartDate": { "type": "string", "format": "date", "description": "Optional: MM/DD/YYYY. When set and legalHold=true, documents, which retention field date >= that date, will not delete on retention.", "example": "2020-12-30" }, "legalHoldEndDate": { "type": "string", "format": "date", "description": "Optional: MM/DD/YYYY. When set and legalHold=true, documents, which retention field date <= that date, will not delete on retention. ", "example": "2021-02-15" }, "retentionEoy": { "type": "boolean", "default": false, "description": "Optional. Default: false. When set to true, forces the retention process to retire the files at the end of the year they supposed to retire on (e.g. a file that should retire on May 2023 will be purged on December 31 of that year. When set to false, the file will be deleted on the date it was set to retire).", "example": true }, "fields": { "type": "array", "description": "Definition of the metadata to load with each document.", "items": { "$ref": "#/components/schemas/documentGroupMeta" } } } }, "documentGroupMeta": { "type": "object", "description": "An item in an array of metadata definition of documentGroup.", "properties": { "name": { "type": "string", "example": "Language", "description": "The metadata field name as appears in the metadata file to be sent during all document uploads (case sensitive and unique). See loadNames below for an expension of this definition." }, "type": { "type": "string", "example": "string", "description": "The type of the metadata item. Allowed: string, date, or number." }, "length": { "type": "number", "example": 10, "description": "Required for strings, omitted for other types. When validValues exist, the length of the largest value or more." }, "dateFormat": { "type": "string", "description": "Available for date datatype only, states the format of the date. e.g. MM/DD/YYYY." }, "retention": { "type": "boolean", "example": false, "description": "Available for date datatype only, can be only one with true value in this list, when true, this will be the field to calculate the retention period from, otherwise, uploadDate is taken." }, "defaultValue": { "type": "string", "example": "FR", "description": "Optional. When set (always as a string) and no value is sent on upload, this value will be set (and considered as sent by the customer). The value must comply with the field's datatype and one of the validValues keys when exist." }, "loadNames": { "type": "string", "description": "Optional. Indicates alternate metadata field names. A unique array (case insensitive) listing field names ADAS searches in all metadata or AFP/Tar files. If the metadata name isn't found, ADAS searches for additional alternate names from this list (case insenstive)." }, "ignoreChars": { "type": "string", "example": "[]()-", "description": "Optional. During ADAS auto-import from AFP/Tar files, these characters are removed from the field value prior to import. This doesn't apply to non-AFP/Tar files or those not utilizing ADAS automated processing." }, "validValues": { "type": "array", "items": { "$ref": "#/components/schemas/validValues" }, "example": [ { "key": "EN", "value": "English" }, { "key": "FR", "value": "French" } ] } }, "required": [ "name", "type" ] }, "validValues": { "type": "object", "properties": { "key": { "type": "string", "description": "The value received when uploading files. Only items in this list can be received, others are errored." }, "value": { "type": "string", "description": "The value saved in the DB, used on search criteria and presented to the user." } } }, "documentFolder": { "type": "object", "required": [ "name", "fields" ], "properties": { "id": { "type": "string", "example": "f1", "readOnly": true, "description": "Auto generated on create. Cannot chante." }, "name": { "type": "string", "maxLength": 256, "example": "contracts_folder", "description": "POST – required - Must be unique, PUT – identifier – cannot be changed. Allowed characters: alphanumeric (a-z, A-Z, 0-9), space ' ', ampersand '&' , hyphen '-' , underscore '_' , slash '/' ,backslash, colon ':' , parenthesis '(' and ')', curly brackets '{' and '}', pound '#', apostrophe, comma ',', asterisk '*'. Use URL encoding when special signs are sent. Percentage sign is not allowed anywhere due to Azure bug." }, "description": { "type": "string", "maxLength": 256, "example": "Customer Contracts", "description": "optional - Provide a description for the documentFolder." }, "creationDate": { "type": "string", "format": "date", "readOnly": true, "description": "Read-only. The date the documentFolder was first created.", "example": "2023-11-20" }, "lastUpdated": { "type": "string", "format": "date", "readOnly": true, "description": "Read-only. The date the documentFolder was last updated.", "example": "2024-03-08" }, "fields": { "type": "array", "description": "Defines the list of fields the customer can search by and their attributes.", "items": { "$ref": "#/components/schemas/folderFieldsArray" } } } }, "folderFieldsArray": { "type": "object", "description": "Each item defines the search field name to be searched by, its association to groups and additional parameters defning the search.", "required": [ "groupId", "fieldName", "searchName", "searchDateFormat", "documentGroupMapping" ], "properties": { "searchName": { "type": "string", "example": "Bill Date", "description": "The name to be searched by." }, "sortLevel": { "type": "number", "example": 1, "description": "Optional. Default: null. Allowed values: 1-5. When set, must be unique, specifies that the results are sorted by this field. The number specifies the level. e.g. 1 - specifies that this is the primary field to sort by. 2 - sorts by the field specified as 1 and then by this field, etc. Allowed values: null (This field does not participate in the sorting), 1-5. When none of the searchNames has a value, the sorting is done by uploadDate descending." }, "sortAscDesc": { "type": "string", "example": "D", "description": "Optional: Default: A. Applicable when sortLevel is specified. Allowed values: A or D only. A=Ascending, D=Descending." }, "searchDateFormat": { "type": "string", "maxLength": 30, "example": "MM/DD/YYYY", "description": "Required when type is date in one of the groups for this field. Used for a definition of this field when used in the search criteria ($filter). Allowed formats: Day: d or dd, Month: M, MM or MMM, Year: yyyy or yy, Hours: H or HH, Minutes: m or mm, Seconds: s or ss, Milliseconds: SSS. Separators: “-“, “/”, “:”, . or space." }, "resultDateFormat": { "type": "string", "maxLength": 30, "example": "MM/DD/YYYY", "description": "Optional. Used to define the date format this field will display dates in the results. When not set, each record date will display in the documentGroup’s format. Allowed formats: Day: d or dd, Month: M, MM or MMM, Year: yyyy, Hours: H or HH, Minutes: m or mm, Seconds: s or ss, Milliseconds: SSS. Separators: “-“, “/”, “.” or space." }, "creationDate": { "type": "string", "format": "date", "readOnly": true, "description": "Read-only. The date the documentFolder was first created.", "example": "2023-11-20" }, "lastUpdated": { "type": "string", "format": "date", "readOnly": true, "description": "Read-only. The date the documentFolder was last updated.", "example": "2024-03-08" }, "documentGroupMapping": { "type": "array", "description": "Maps metadata in documentGroups to this searchName.", "items": { "$ref": "#/components/schemas/documentGroupMappingArray" } }, "documentFolderDisplay": { "description": "The list of display parameters relevant to the user interface. ADAS doesn't do anything with these values but presenting them in the dashboard API or documentFolder as is. Not sending the object retains the fields as they were. Sending an empty object {} – deletes all values (set to null)", "type": "object", "properties": { "searchPresentationOrder": { "type": "number", "example": 1, "description": "Number. Optional. Represents the field order in the customer’s search screen. Not sending this specific field retains its value. sending Null, will reset to null." }, "searchDefaultWildcard": { "type": "string", "maxLength": 10, "example": "Append", "description": "Signals the UI to add a wildcard before, after or on both ends of a string. Not sending this specific field retains its value. sending Null, will reset to null. Allowed values: a-z, A-Z, 0-9, , /,-, _" }, "searchDefaultOperator": { "type": "string", "maxLength": 50, "example": "Greater Than Or Equal To", "description": "Optional. String. Represents the default operator to use for this searchName. Not sending this specific field retains its value. sending Null, will reset to null. Allowed values: a-z, A-Z, 0-9, , /,-, _" }, "searchDefaultValue": { "type": "string", "maxLength": 256, "example": "Last 3 Months", "description": "Optional. String. Represents the defult value to set by the UI for this searchName. Not sending this specific field retains its value. sending Null, will reset to null. Allowed values: a-z, A-Z, 0-9, , /,-, _" }, "resultsPresentationOrder": { "type": "number", "example": 1, "description": "Optional. Represents the column order in the customer’s search screen. It is the customer's responsibility to act upon it. Not sending this specific field retains its value. Sending Null, will reset to null." } } } } }, "documentGroupMappingArray": { "description": "This array maps a searchName in the folderFieldArray item to a field name defnied in a specific documentGroup.", "type": "object", "properties": { "groupId": { "type": "string", "example": "g2", "description": "documentGroup Id to map to." }, "fieldName": { "type": "string", "example": "bill_date", "description": "The field name associated to this searchName in the above documentGroup." } }, "required": [ "groupId", "fieldName" ] }, "screenDisplay": { "type": "object", "properties": { "searchNames": { "type": "array", "description": "Array of objects (one per the documentFolder's searchNAme' that conatins the UI represetnation for that field (both for search fields and for the results).", "items": { "$ref": "#/components/schemas/screenDisplaySearchName" } } } }, "screenDisplaySearchName": { "type": "object", "description": "A single item in an array for screen display representing a searchName field attributes.", "properties": { "searchName": { "type": "string", "example": "Bill Date", "description": "The searchName as defined in the documentFolder." }, "type": { "type": "string", "example": "date", "description": "Taken from the first documentGroup assiciated to this field in the documentFolder." }, "maxLength": { "type": "number", "description": "Null for types other than string. Presents the max length of all documentGroups." }, "searchDateFormat": { "type": "string", "example": "MM/DD/YYYY", "description": "Optional. Represents the date format to be used in this field. Taken from the relevant searchName of the documentFolder." }, "resultDateFormat": { "type": "string", "example": "MM/DD/YYYY", "description": "Optional. Represents the date format to be used in this field. Taken from the relevant searchName of the documentFolder." }, "searchPresentationOrder": { "type": "number", "example": 1, "description": "Optional. Represents the field order in the customer’s search screen. 0/null - might mean it is hidden from the search screen. The data is taken from the documentFolder." }, "searchDefaultOperator": { "type": "string", "example": "Greater Than Or Equal To", "description": "Optional. Represents the default operator for the relevant field. taken from the relevant searchName of the documentFolder." }, "searchDefaultValue": { "type": "string", "example": "Last 3 Months", "description": "Optional. Represents the default value for the relevant field. taken from the relevant searchName of the documentFolder." }, "resultsPresentationOrder": { "type": "number", "example": 1, "description": "Optional. Represents the column order in the customer’s search results. The customer will do the actual ordering, this is just the infro taken from the documentFolder." }, "searchDefaultWildcard": { "type": "string", "maxLength": 10, "example": "Append", "description": "Optional. Signals the UI to add a wildcard before, after or on both ends of a string (or none at all)." }, "validValues": { "type": "array", "example": [ "English", "French" ], "description": "Optional: An array of strings of all validValues values (not key). Extracting a unique list out of all documentGroups associated to this field.", "items": { "type": "string" } } } }, "document": { "description": "Represents a single document (metadata item) + additional information such as built-in fields.", "type": "object", "properties": { "_id": { "type": "string", "readOnly": true, "description": "The ADAS document genrated ID. Used to request a download link for the file.", "example": "d8283ab3-8886-4346-835f-cdac4f54e542-31920" }, "filename": { "type": "string", "readOnly": true, "example": "testFlowAfp-file-1683029295844.ard", "description": "The name of the file as uploaded." }, "documentGroupId": { "type": "string", "example": "g1", "description": "The documentGroup ID the file is associated with." }, "documentGroupName": { "type": "string", "example": "contracts", "description": "The documentGroup name the file is associated with." }, "uploadDate": { "type": "string", "readOnly": true, "format": "date" }, "docType": { "type": "string", "readOnly": true, "description": "File extension as (if) uploaded.", "example": "ard" }, "docSize": { "type": "number", "readOnly": true, "description": "The file size in bytes.", "example": 749 }, "cmodDocId": { "type": "string", "readOnly": true, "description": "The document ID in CMOD so it can be searched by. This feature is extracted for specific appGroups on the migration process. (DV)", "example": "v7126-6273-6354-6623-YKA11-6423FAAC%24-0-956-9416790-33336-78-79-3-39-0-%5E" }, "relationId": { "type": "string", "readOnly": true, "description": "This key is present only when more than one metadata set is linked to a specific document/file. In that case, the same relationId will be set to all matching metadata sets.", "example": "bf983ab3-8526-6fjk-9d7f-4736ef74e542-cgodj" }, "metadata": { "type": "array", "description": "Array of metadata fields, uploaded with the file, that match with the definition in its associated documentGroup.", "items": { "$ref": "#/components/schemas/documentMeta" } } } }, "documentMeta": { "type": "object", "description": "Metadata fields uploaded with their associated binary file.", "properties": { "Language": { "type": "string", "example": "English", "description": "Metadata field provided with the document that matches the documentGroup." }, "bill_date": { "type": "string", "example": "07/19/2007", "description": "Metadata field provided with the document that matches the documentGroup." }, "PAGECNT": { "type": "number", "example": 2, "description": "Metadata field provided with the document that matches the documentGroup." } } }, "uploadCount": { "type": "object", "description": "Total number of metadata items upload count and count per documentGroup between the required dates.", "properties": { "fromDate": { "type": "string", "format": "date", "example": "2023-08-14", "description": "From date as requested in the param - beginning of the day (UTC)." }, "toDate": { "type": "string", "format": "date", "example": "2023-08-14", "description": "To date as requested in the param - end of the day (UTC)." }, "gmt": { "type": "number", "format": "decimal", "example": -5.5, "description": "Offset time calculation from UTC" }, "totalCount": { "type": "number", "example": 379777, "description": "The total number of metadata items (documents) uploaded between the date range requested." }, "groupUploads": { "type": "array", "description": "Upload count per documentGroup between the requested dates.", "items": { "$ref": "#/components/schemas/uploadCountPerGroup" } } } }, "uploadCountPerGroup": { "type": "object", "description": "Each item contains a documentGroup name and its upload count.", "properties": { "groupName": { "type": "string", "description": "The name of the documentGroup." }, "uploadCount": { "type": "string", "description": "The number of upload made to the groupName between the required dates." } } }, "downloadCount": { "type": "object", "description": "Total number of documents request for downloadURL count also distribution per documentGroup between the required dates.", "properties": { "fromDate": { "type": "string", "format": "date", "example": "2023-08-14", "description": "From date as requested in the param - beginning of the day (UTC)." }, "toDate": { "type": "string", "format": "date", "example": "2023-08-04", "description": "To date as requested in the param - end of the day (UTC)." }, "gmt": { "type": "number", "format": "decimal", "example": -5.5, "description": "Offset time calculation from UTC" }, "totalCount": { "type": "number", "example": 379777, "description": "The total number of request for download URL asked between the date range requested." }, "groupDownloads": { "type": "array", "description": "Request for download URL count per documentGroup between the requested dates.", "items": { "$ref": "#/components/schemas/downloadCountPerGroup" } } } }, "downloadCountPerGroup": { "type": "object", "description": "Each item contains a documentGroup name and its upload count.", "properties": { "groupName": { "type": "string", "description": "The name of the documentGroup." }, "downloadCount": { "type": "string", "description": "The number of upload made to the groupName between the required dates." } } }, "updateDocBody": { "type": "object", "description": "Allows updating the visibility attribute for metadata object(s).", "properties": { "visible": { "type": "boolean", "example": true, "description": "Required. When true, hides the document from search results, unless specifically asking for hidden documents. When false, makes this document (metadata item) visible." } } } } } }