Migration Guide

Introduction

File Service provides enhanced features and performance compared to Data Ocean. We recommend all users migrate to File Service to take advantage of these improvements. This guide explains the key differences between the legacy Data Ocean service and the new File Service, how those differences are handled during migration, and how to map fields between the two services.

Key differences between Data Ocean and File Service

Below are the key differences between Data Ocean and File Service from a usage point of view.

Logical separation

Data Ocean

• There is no explicit logical separation.
• Consumers achieve logical separation by defining first-level paths in API calls.
• Consumers are responsible for creating and maintaining this separation.
• Example: The Connect team uses projectId in first-level paths to achieve separation.

File Service

• Logical separation is provided through Spaces.
• A Space is a distinct container for files and folders.
• You operate within a Space, then interact with file and folder structures inside it.
• Example: The Connect team creates a separate Space per Connect project.

Migration

When migrating to File Service, choose how to organize your Data Ocean content: in a single Space or across multiple Spaces.

Regional and cloud provider isolation

Data Ocean

• Regions combine geographic storage location and cloud provider.
• Regional isolation is achieved by setting region_preferences in the create file request.
• Binary content is stored in specified region(s); metadata is stored in a single, global region.
• A single file can have one metadata record and exist in multiple regions.

File Service

• Geographic location and cloud provider are separated.
• A single cloud provider must be selected and all files will be stored in that region.
• Geographic regional isolation is achieved through separate application stacks with distinct region-specific URLs. This ensures all resources remain confined within their designated region.
• A file exist only one region. The same file can be created in an additional region, but it will have its own distinct metadata and not be connected to the first file in any way.
• See File Service Regions documentation.

Migration

During migration, the Data Ocean region determines the File Service region where the data and metadata are stored. For Data Ocean files stored in multiple regions, integrators must select one target region. A Space can exist in only one region. To store data in multiple regions, use separate Spaces.

File creation

Data Ocean

• A file is created and uploaded via a single endpoint and can be retrieved before content upload completes.

File Service

• Create an upload object first, then upload the file.
• The system creates the file only after the upload completes.
• Failed uploads do not create a file object.
• See File Service Upload documentation.

Access control

Data Ocean

• Each resource has an Access Control List (ACL) that lists TID entities and their permissions (read, write, delete) for the resource. In addition to permissions set in the ACL, the resource owner has full access to the resource.

File Service

• Each resource has an ACL with TID entities and roles (contentManager, contentContributor, contentViewer). Each role is a collection of permissions.
• Access is inherited from folders to children (inheritance can be broken).
• See File Service ACL documentation.

Migration

Data Ocean permissions map to File Service roles as follows:

Data Ocean permission	File Service role
read	contentViewer
write	contentContributor
delete	contentManager

File owners are added as contentManager at the Space level, giving access to all files.

Asynchronous activities

Data Ocean

• Asynchronous operations (copy file, copy directory) return 202 and a jobId in the response body.

HTTP 202 response body:

{
  "job": { "id": "eb6f48ab-465a-41ec-8ac0-ef05b0bead1c" }
}

File Service

• Asynchronous operations return 200 with a jobId in the Location header.
• A 200 response indicates the resource was updated and child resources update in the background.

Support files

Data Ocean

• Support files are independent files in the hierarchy that are associated with a “master” file by specifying the “master_id” on the support file.

File Service

• Support files are children of a parent file.
• They are retrieved from the parent using the links attribute.
• See Support File documentation.

Migration

During migration, Data Ocean support files will be migrated to File Service support files. They will become children of their “master” file in File Service. Links will be created to map each support file to the version of the “master” file that they relate to.

Deprecated Functionality

The following is a summary of Data Ocean functionality that has been deprecated in File Service.

• Regional replication: The ability to replicate a single file across multiple regions is no longer available. Resources must be stored in a single region. See Regional Isolation for more information.

• Directory creation by path: The ability to create a directory structure by specifying a path is no longer available. Folders need to be created individually.

• Malware scanning on demand: On-demand scanning has been removed. All files are scanned on upload, so there shouldn’t be a need to scan files manually.

• Versions: The ability to restore an older version of the file (by making it the newest version) has been removed. The ability to delete a specific version has been removed to prevent the history of a file from being modified.

• By-path mutations: All endpoints that allowed mutating a resource by path instead of by id have been removed. This includes updating, deleting, and copying files and directories. These endpoints were removed to ensure consistency in highly concurrent environments.

• Fileset path_template: The path_template field was used to store the directory template of the contents of a fileset. This field has been removed. If the information is still needed, the metadata field can be used to store the template value.

• Search: A small number of users had a search feature enabled in Data Ocean. Search is not yet available in File Service. If you use this feature, please contact us for more information.

• Datahub integration: A small number of users were integrated with the Datahub solution. If you use this, please contact us for more information.

Field comparison

Below are fields available in Data Ocean and their corresponding fields in File Service. File Service has additional fields not listed here.

Note: In Data Ocean’s responses, all file object properties are organized under a primary ‘file’ field. In contrast, the file service’s responses provide these properties directly.

Data Ocean field	File Service field	Description	Comments
id	id	Resource identifier	Exact match.
name	name	Resource name	Exact match.
path	path	Resource path	Exact match.
multipart	multipart	Specifies if the upload is a multipart	Exact match.
fileset	fileset	Indicates if the resource is a fileset	Exact match.
md5	md5	MD5 hash of file	Exact match.
size	size	File size	Exact match.
metadata	metadata	Custom metadata can be set for the resource.	Exact match.
download	download	Container for the download url for the resource.	Exact match.
version (int)	version (string)	File version	Similar, but the value format differs. > Data Ocean uses an integer for content updates. > File Service uses major.minor, where major tracks content changes and minor tracks metadata changes. > During Migration, the Data Ocean version becomes the File Service major version. The minor version is set to 0 (for example, 1.0).
restricted_access	restrictedAccess	Set to false to create a static download url for the file. This will allow any user with the download url to access the file indefinitely.	Same meaning, different attribute name, same content.
expires_at	expiresAt	Auto-delete timestamp	Same meaning, different attribute name, same content.
malware_status	malwareScanStatus	Malware scan status	Same meaning, different attribute name; values map as: CLEAN → CLEAN, INFECTED → INFECTED, UNSCANNED → UNSCANNED, CANNOT_SCAN → CANNOT_SCAN, SCAN_FAILED → FAILED, <not present> → QUEUED_FOR_SCAN.
last_scanned_at	lastMalwareScanDate	Malware scan time	Same meaning, different attribute name, same content.
created_at	createdAt	Resource creation time	Same meaning, different attribute name, same content.
updated_at	updatedAt	Resource update time	Same meaning, different attribute name, same content.
regions	N/A	Indicates in which region the binary content is stored.	Data Ocean only. See Regional Isolation, for details on the differences in how Data Ocean and File Service handle regions.
region_preferences	N/A	Indicates the preferred region in which the binary content should be stored.	Data Ocean only. See Regional Isolation, for details on the differences in how Data Ocean and File Service handle regions.
path_template	N/A	Used with filesets only. Stores a template for the url structure of a filesets.	Data Ocean only.
first_version_created_at	N/A	First version creation time	Data Ocean only.
owner_id	createdByTrn	The concept of a resource “owner” does not exist in File Service, but the creator of the resource will be tracked.	Available only in Data Ocean. But “createdByTrn” is a similar field in the File Service. Migration: When migrated, owner_id will be mapped to createdByTrn.
application_id	N/A	Id of the application through which the resource was created.	Data Ocean only.
status	N/A	Indicates the status of the resource.	Data Ocean only; File Service treats all files as AVAILABLE.
acl	permissionsLocal	Actors and roles set on the current resource.	Different structure; see Access Control.
response_headers	responseHeaders	content-type, content-disposition, and cache-control headers for the file. These can be set by the user. If not set, the system will generate them.	Same meaning, different name.

API endpoint comparison

All Data Ocean endpoints and their File Service equivalents are listed below. File Service provides additional endpoints not shown here.

Directories and folders

Operation	Data Ocean	File Service	Comments
Create directory	POST /directories	POST /2.0/spaces/{spaceId}/folders	Direct equivalent.
By ID
Update directory	PATCH /directories/{directory_id}	PATCH /2.0/spaces/{spaceId}/folders/{folderId} POST /2.0/spaces/{spaceId}/folders/{folderId}/move POST /2.0/spaces/{spaceId}/folders/{folderId}/rename	Direct equivalent for updates to general metadata. Move and Rename actions use separate endpoints in File Service.
Copy directory	POST /directories/{directory_id}/copy	POST /2.0/spaces/{spaceId}/folders/{folderId}/copy	Direct equivalent.
Delete directory	DELETE /directories/{directory_id}	DELETE /2.0/spaces/{spaceId}/folders/{folderId}	Direct equivalent.
Get directory	GET /directories/{directory_id}	GET /2.0/spaces/{spaceId}/folders/{folderId}	Direct equivalent.
List Files/Directories in Directory	GET /directories/{directory_id}/files GET /directories/{directory_id}/directories	GET /2.0/spaces/{spaceId}/folders/{folderId}/children	Listing of files and directories has been combined into a single endpoint. To list only files or folders, use the query parameter ?type=files
By Path
Get directory by path	GET /directories?path=	GET /2.0/spaces/{spaceId}/folders?path=	Direct equivalent.
List Files/Directories in Directory by path	GET /directories/files?path= GET /directories/directories?path=	GET /2.0/spaces/{spaceId}/folders/children?path=	Listing of files and directories has been combined into a single endpoint. To list only files or folders, use the query parameter ?type=files
By-path mutations	DELETE /directories?path= PATCH /directories?path= POST /directories/copy?path=	N/A	No longer supported.

File upload

Operation	Data Ocean	File Service	Comments
Create file	POST /files	POST /2.0/spaces/{spaceId}/uploads	File creation has been replaced by uploads. A file object is not created until the upload has completed successfully.
Get file (upload)	GET /files/{file_id}	GET /2.0/spaces/{spaceId}/uploads/{uploadId}	Replacement for getting information about a file/upload before the upload has completed.
Complete multipart upload	POST /files/{file_id}/assemble	PATCH /2.0/spaces/{spaceId}/uploads/{uploadId}	Direct equivalent.

Files

Operation	Data Ocean	File Service	Comments
By ID
Get file	GET /files/{file_id}	GET /2.0/spaces/{spaceId}/files/{fileId}	Direct equivalent.
Get file version	GET /files/{file_id}?version=	GET /2.0/spaces/{spaceId}/files/{fileId}/versions/{versionId}	File Service provides a separate endpoint for retrieving versions instead of specifying the version with a query parameter.
Delete file	DELETE /files/{file_id}	DELETE /2.0/spaces/{spaceId}/files/{fileId}	Direct equivalent.
List file versions	GET /files/{file_id}/versions	GET /2.0/spaces/{spaceId}/files/{fileId}/versions	Direct equivalent.
Copy file	POST /files/{file_id}/copy	POST /2.0/spaces/{spaceId}/files/{fileId}/copy	Direct equivalent.
Copy file version	POST /files/{file_id}/copy?version=	POST /2.0/spaces/{spaceId}/files/{fileId}/versions/{versionId}/copy	File Service provides a separate endpoint for retrieving versions instead of specifying the version with a query parameter.
Update file	PATCH /files/{file_id}	PATCH /2.0/spaces/{spaceId}/files/{fileId} POST /2.0/spaces/{spaceId}/files/{fileId}/move POST /2.0/spaces/{spaceId}/files/{fileId}/rename	Direct equivalent for updates to general metadata. Move and Rename actions use separate endpoints in File Service.
Get fileset manifest	GET /files/{file_id}/manifest	GET /2.0/spaces/{spaceId}/files/{fileId}/manifest	Direct equivalent.
Direct download	GET /files/{file_id}/download	GET /2.0/spaces/{spaceId}/files/{fileId}/download	Direct equivalent.
By Path
Get file by path	GET /files?path=	GET /2.0/spaces/{spaceId}/files?path=	Direct equivalent.
List file versions by path	GET /files/versions?path=	GET /2.0/spaces/{spaceId}/files/versions?path=	Direct equivalent.
Get file version by path	GET /files/{file_id}?path=&version=	GET /2.0/spaces/{spaceId}/files/versions/{versionId}?path=	File Service provides a separate endpoint for retrieving versions instead of specifying the version with a query parameter.
Get fileset manifest by path	GET /files/manifest?path=	GET /2.0/spaces/{spaceId}/files/manifest?path=	Direct equivalent.
Direct download by path	GET /files/download?path=	GET /2.0/spaces/{spaceId}/files/download?path=	Direct equivalent.
By-path mutations	PATCH /files?path= DELETE /files?path= POST /files/copy?path=	N/A	No longer supported.

Other

Operation	Data Ocean	File Service	Comments
Malware scanning	POST /files/{file_id}/scan POST /files/scan?path=	N/A	No longer supported; all files are scanned on upload.
Get job	GET /jobs/{job_id}	GET /2.0/jobs/{jobId}	Direct equivalent.
Create archive	POST /directories/archive	POST /2.0/spaces/{spaceId}/exports	The File Service Export feature works similarly to Archives in Data Ocean. However, they are stored outside of the file hierarcy as a distinct object separate from a file.
Get File (Archive)	GET /files/{file_id}	GET /2.0/spaces/{spaceId}/exports/{exportId}	Archives (Exports) are separate object type in File Service. Retrieving an export is a separate endpoint rather than getting a file. Exports expire after 30 days. The expiration cannot be changed.

Reference materials

User documentation

• File Service
• Data Ocean

Cloud Console

• File Service Product

Support

If you need assistance, contact tc-file-service-ug@trimble.com or the Trimble cloud support team.