Upload third-party files to folders

You can upload files to the /thirdparty folder or to subfolders that you create.

Uploading a file involves the following steps:

Generate a token for the file upload.
Upload the file to the desired location.
View a list of files and folders.
Publish the files and folders to the production environment.
Verify that the file is present on the production environment.

These steps are described in the sections that follow.

Generate a token for the file upload

Before you can upload a file, you must generate a token to associate with the upload. To do this, use the startFileUpload endpoint (PUT /ccadmin/v1/files). The request JSON for this endpoint includes three properties:

filename – The pathname for the file, relative to the /thirdparty folder. So, for example, if you want to upload a file named policy.html to be located directly in the /thirdparty folder, the value of the filename property would be policy.html. (Do not include a leading slash; /policy.html is incorrect.) If you want to upload a file named policy.html to be located in the /thirdparty/myfolder subfolder, the value of the filename property would be myfolder/policy.html. (If the subfolder does not already exist, it is created automatically when the file is uploaded.)
segments -- The file must be uploaded in segments of less than 1 GB each. If your file is larger than 1 GB, it must be up broken up into multiple segments, with each segment uploaded separately. The segments property specifies the number of segments to be uploaded.
uploadtype – Set the value of this property to thirdPartyFile.

The following request body generates a token for uploading a third-party file named /thirdparty/myfolder/sampleFile.txt in two segments:

{
  "filename": "myfolder/sampleFile.txt",
  "segments": 2,
  "uploadtype": "thirdPartyFile"
}

The response body includes the token and an array of the indices of the segments to be uploaded. The indices are zero-based, so the first segment is 0:

{
    "links": [
        {
            "rel": "self",
            "href": "http://myserver.example.com:7002/ccadmin/v1/files"
        }
    ],
    "segmentsNeeded": [
        0,
        1
    ],
    "token": "18a7878ddf1ab_1751"
}

Upload the file to the desired location

The actual upload is performed using the uploadSegment endpoint (POST/ccadmin/v1/files/<token>, where <token> is the token generated in the startFileUpload call). You must call uploadSegment once for each file segment, and each time specify these three properties:

filename -- The pathname for the file, relative to the /thirdparty folder. This must match the filename used to generate the token.
index -- The index for the file segment being loaded.
file -- The based64-encoded content of the segment.

The following sample request uses the token generated by the startFileUpload call in the previous section to upload the first segment of a file:

POST /ccadmin/v1/files/18d396ba091fa_1755 HTTP 1.1
Authorization: Bearer <access_token>

{
  "filename": "myfolder/sampleFile.txt",
  "index": 0,
  "file": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZ
WxpdC4gTWF1cmlzIGF1Y3RvciBmZXVnaWF0IGp1c3RvLCBpZCB1bHRyaWNlcyBsb3JlbSBzb2RhbGVzI
HNpdCBhbWV0LiBJbiBhdWN0b3Igc2VkIHNlbSBldCBpYWN1bGlzLiBNYWVjZW5hcyBiaWJlbmR1bSBua
XNsIG5lcXVlLiBBZW5lYW4gYXQgb3JuYXJlIGRpYW0uIEZ1c2NlIGlkIGRpZ25pc3NpbSBsb3JlbSwgc
nV0cnVtIGNvbmRpbWVudHVtIGxlY3R1cy4gUGVsbGVudGVzcXVlIHZhcml1cyBjb25zZWN0ZXR1ciBtZ
XR1cyBub24gc2FnaXR0aXMuIEludGVnZXIgZXN0IHF1YW0sIGRpZ25pc3NpbSBub24gbGVjdHVzIG5lY
ywgY29udmFsbGlzIGNvbnZhbGxpcyBuaXNpLiBFdGlhbSBpbiBlZmZpY2l0dXIgbnVsbGEuIFN1c3Blb
mRpc3NlIGVnZXQgdGluY2lkdW50IHR1cnBpcywgbmVjIHRlbXB1cyB1cm5hLiA="
}

For a multi-segment upload, the response body for each segment but the last is similar to this:

{
    "success": true,
    "links": [
        {
            "rel": "self",
            "href":
"http://myserver.example.com:7002/ccadmin/v1/files/18d396ba091fa_1755"
        }
    ]
}

For a single-segment upload, or the last segment of a multi-segment upload, the response body is similar to this:

{
    "result": {
        "@class": "atg.cloud.file.ThirdPartyUploadResultSummary",
        "failedFiles": 0,
        "allFilesFailed": false,
        "newFiles": 1,
        "modifiedFiles": 0,
        "unzipped": false,
        "failedFilesReasons": {}
    },
    "success": true,
    "links": [
        {
            "rel": "self",
            "href":
"http://myserver.example.com:7002/ccadmin/v1/files/18d396ba091fa_1755"
        }
    ]
}

View a list of files and folders

To list third-party files and their containing folders, issue a GET request to the /ccadmin/v1/files endpoint on the administration server. This endpoint has a required query parameter, folder, that you use to specify the folder to return results for. For example:

GET /ccadmin/v1/files?folder=/thirdparty HTTP 1.1
Authorization: Bearer <access_token>

You can use the assetType query parameter to specify whether to return a list of the files only (assetType=file), the folders only (assetType=folder), or both (assetType=all). The default is file, so if you omit this query parameter, a list of the files is returned.

The following example shows a sample call to the getFiles endpoint that returns both files and folders:

GET /ccadmin/v1/files?folder=/thirdparty&assetType=all HTTP 1.1
Authorization: Bearer <access_token>

The following example shows sample output from this call:

{
    "total": 2,
    "totalResults": 2,
    "offset": 0,
    "limit": 250,
    "links": [
        {
            "rel": "self",
            "href":
"http://myserver.example.com:7002/ccadmin/v1/files?folder=%2Fthirdparty&assetType=all"
        }
    ],
    "sort": [
        {
            "property": "name",
            "order": "asc"
        }
    ],
    "items": [
        {
            "path": "/thirdparty/myfolder",
            "repositoryId": "folder10004",
            "name": "myfolder",
            "url": "http://myserver.example.com:7002/file/thirdparty/myfolder"
        },
        {
            "path": "/thirdparty/myfolder/sampleFile.txt",
            "extension": "txt",
            "metadata": {},
            "size": 916,
            "repositoryId": "f10001",
            "name": "sampleFile.txt",
            "checksum": 6238228597895851000,
            "lastModified": "2017-01-04T21:19:14.015Z",
            "type": "file",
            "url":
"http://myserver.example.com:7002/file/v1857419716804211141/thirdparty/myfolder/sampleFile.txt"
        }
    ]
}

The getFiles endpoint can also take a filter query parameter to limit the set of folders and files returned. The value of this parameter is a simple sequence of characters (no wild-card or regular expression elements) that is used to do substring matching on file or folder names. For example, the following call returns a list of the files in the /thirdparty folder whose names include the string “red”:

GET /ccadmin/v1/files?folder=/thirdparty&filter=red  HTTP 1.1
Authorization: Bearer <access_token>

Publish the files and folders to the production environment

To make your changes available to the production environment, publish them, as described in Publish Changes.

Verify that the file is present on the production environment

View the file in your browser to verify that it is present on your production environment. For example, to view a file uploaded to /thirdparty/myfolder/sampleFile.txt:

http://myserver.example.com:7002/myfolder/sampleFile.txt