What's New in IP*Works! Cloud 2020

Requirements: IP*Works! Cloud 2020

IP*Works! Cloud 2020 is the latest version of /n software's popular cloud storage product, and represents a major upgrade from Cloud Storage Integrator 2016. The IP*Works! Cloud 2020 toolkit introduces support for additional cloud storage providers, adds new functionality to existing providers, and offers refreshed APIs across the board.

This article is intended to provide both a high level overview of new features and functionality, as well as details about how to migrate existing code from the Cloud Storage Integrator 2016 components to the IP*Works! Cloud 2020 components. Please refer to the IP*Works! Cloud 2020 documentation for more information, and don't forget to check out the Getting Started with IP*Works! Cloud 2020 article as well.

Contents

New Components

IP*Works! Cloud 2020 now provides support for even more cloud storage services with the addition of the following components:

  • HadoopDFS: Any Hadoop Distributed File System (HDFS) cluster, via its WebHDFS endpoint
  • GoogleStorage: Google Cloud Storage
  • AzureFile: Microsoft Azure File Storage

Support for these services has also been added to the existing CloudStorage component.

Updated Components

Many of the cloud storage services already supported have continued to evolve over time, adding both quality-of-life improvements and new major features since the initial release of Cloud Storage Integrator 2016. In IP*Works! Cloud 2020, we've updated a number of components, augmenting them with additional functionality based on the current offerings of each cloud storage service. Along the way, we meticulously redesigned these components' APIs to provide a uniform and intuitive developer experience.

For each updated component, you'll find a section below that provides an overview of the additions and changes that have been made. Each section also includes a detailed API migration table to assist you in upgrading from Cloud Storage Integrator 2016 to IP*Works! Cloud 2020. For more information, please refer to the IP*Works! Cloud 2020 documentation, which provides in-depth details.

Box Component

Overview of Changes

  • Collections are now used in the .NET/Java editions (these are the Resource* and Metadata* properties in other editions).
  • Methods now accept resource Ids directly as parameters. The ResourceId and ResourceParentId properties no longer exist in .NET/Java, and in other editions they are no longer used to determine what resource (or parent resource) a method should operate on.
  • The component now exposes resource Ids prefixed with either f: (for files) or d: (for folders), and expects those prefixes to be present when resource Ids are passed in so that it knows ahead-of-time whether the associated resource is a file or a folder.
    • The ResourceType property no longer exists in .NET/Java, and in other editions it is no longer used to control whether to operate against a file or folder resource when calling methods.
  • The component now supports Box's resumable uploads API in addition to the simple upload API. The following API members have been added to support this functionality:
    • UseResumableUpload and ResumeURL properties.
    • AbortUpload() and PollUploadStatus() methods.
    • FragmentComplete event.
    • UploadFragmentSize and UploadExpDate configuration settings.
  • Numerous improvements to metadata manipulation have been made, including:
    • The component can now manipulate metadata items in any metadata container on any resource (the previous version was limited to manipulating metadata in the /global/properties container, and could only do so on file resources).
    • Additional metadata modification operations are now possible.
    • A MetadataList event has been added.
    • The Metadata collection property was added (and other API areas have been similarly updated).
  • Shared resource handling has been updated to align with Box design concepts. Shared link information is now exposed directly on each resource item.
    • The SharedResourceInfo object property (SharedResource* properties in non-.NET/Java editions) has been removed.
  • File resource "revisions" are now known as "versions", to match the Box terminology.
    • Additionally, there is now a VersionMarker property, used with ListVersions().
  • The MoveResource() method has been added.
  • The ability to download file thumbnails has been rolled into DownloadFile(). Use the new DownloadType property to control what gets downloaded.
    • Additionally, the ThumbnailFormat and ThumbnailSize properties are now configuration settings.
  • A number of configuration settings have been added to expose more of the Box API's functionality. Here are a few examples (refer to the documentation for the full list):
    • Shared links can now be configured when created using the CreateLinkAccess, CreateLinkAllowDownloads, CreateLinkExpiration, and CreateLinkPassword settings.
    • The VersionId setting can be used to modify the behavior of the CopyResource() and DownloadFile() methods.
    • The MetadataUpdateOrder setting can be used to specify an explicit order for metadata items to be updated in when the UpdateMetadata() method is called.

API Migration Table

Cloud Storage Integrator 2016 IP*Works! Cloud 2020
ResourceId, ResourceParentId, and ResourceType properties While these properties still exist in non-.NET/Java editions, they are no longer used to specify which resource to operate on. Methods now accept prefixed resource Ids directly as parameters.
MetadataFields collection property Renamed to Metadata
ResourceCreatedDate and ResourceModifiedDate properties Renamed to ResourceCreatedTime and ResourceModifiedTime. (In .NET/Java editions, these are BoxResource object fields rather than properties.)
ResourceDeletedDate and ResourcePurgedDate properties These properties are now the ResourceTrashedTime[i] and ResourcePurgeTime[i] configuration settings.
SharedResourceInfo object property Removed. The fields from this object property have all become either BoxResource object fields or ResourceSharedLink* configuration settings.
ThumbnailFormat and ThumbnailSize properties These properties are now configuration settings.
TotalSpace and UsedSpace properties These properties are now fields on the BoxAccount object accessible through the Account property.
CopyResource() method This method now returns the Id of the newly-copied resource.
CreateMetadata(), DeleteMetadata(), GetMetadata(), and UpdateMetadata() methods These methods now accept parameters that specify which metadata container to operate against. Also, GetMetadata() has been renamed to ListMetadata().
GetPreviewLink() method Renamed to CreatePreviewLink()
GetSharedResourceInfo() method Removed.
GetThumbnail() method Removed. Set the new DownloadType property appropriately and call DownloadFile() instead.
ListDeletedResources() method Removed. Pass trash to the ListResources() method (in place of an actual resource Id) instead.
ListRevisions() and PromoteRevision() methods Renamed to ListVersions() and PromoteVersion().
ShareResource() and UnshareResource() methods Renamed to CreateLink() and RevokeLink().
ResourceList event Additional resource fields are now exposed. Refer to the documentation for more information.
IncludeFileHash configuration setting Renamed to HashSimpleUploads.
MaxResults configuration setting This setting is still present, but now only affects ListResources() and ListVersions(). Use the new MaxSearchResults configuration setting to limit the results returned by Search().
ResourceClientCreatedDate and ResourceClientModifiedDate configuration settings Renamed to ClientCreatedTime and ClientModifiedTime.

Dropbox Component

Overview of Changes

  • Collections are now used in the .NET/Java editions (these are the Resource* and SharedLink* properties in other editions).
  • Methods now accept one or more types of "resource identifiers" directly as parameters. The ResourcePath property no longer exists in .NET/Java, and in other editions it is no longer used to determine what resource a method should operate on.
    • Depending on the method, a "resource identifier" is either a resource path, a resource Id, an Id-based relative resource path, or a revision Id.
  • Resource-Id-based operations are now supported.
    • The CopyResource(), CreateFolder(), RestoreResource(), and UploadFile() methods all return a resource Id now. (Previously, UploadFile() returned a resource path, and the others didn't return a value.)
  • It is no longer necessary to call ListResources() before using ListChanges(); refer to the documentation for more information.
  • The RenameIfExists configuration setting now applies to the following methods: CopyResource(), CreateFolder(), and MoveResource().
  • The ability to download file previews and image thumbnails has been rolled into DownloadFile(). Use the new DownloadType property to control what gets downloaded.
  • A number of configuration settings have been added to expose more of the Dropbox API's functionality. Here are a few examples (refer to the documentation for the full list):
    • DownloadFile() can now download folders as ZIP files if the AllowFolderDownloads setting is enabled.
    • Shared links can now be configured when created using the CreateLinkExpiration, CreateLinkVisibility, and CreateLinkPassword settings.
    • The IfRevision setting can be used to modify the behavior of the DeleteResource() and UploadFile() methods.

API Migration Table

Cloud Storage Integrator 2016 IP*Works! Cloud 2020
ChangeMarker property This property still exists, but it is used differently. The new NextChangeMarker property serves the same purpose (i.e., holding a future change marker); while this property is now only used for paging.
ResourcePath property While the ResourcePath property still exists in non-.NET/Java editions, it is no longer used to specify which resource to operate on. Methods now accept resource paths/Ids/etc. directly as parameters.
ResourceModifiedDate property Renamed to ResourceModifiedTime. (In .NET/Java editions, this is a DropboxResource object field rather than a property.)
SearchMarker property This property's type has changed from string to long.
SharedResources collection property Renamed to SharedLinks.
ThumbnailFormat and ThumbnailSize properties These properties are now configuration settings (along with the new ThumbnailMode setting).
TotalSpace and UsedSpace properties These properties are now fields on the DropboxAccount object accessible through the Account property.
GetPreview() and GetThumbnail() methods Removed. Set the new DownloadType property appropriately and call DownloadFile() instead.
GetUsageInfo() method Removed. Its functionality has been rolled into GetAccountInfo(), which should be used instead.
ListChanges() method Usage has changed. Refer to the documentation for more information.
ListRevisions() method Revisions history can now be listed by path or by Id. Refer to the documentation for more information.
ListSharedResources() method Renamed to ListSharedLinks().
ShareResource() and UnshareResource() methods Renamed to CreateLink() and RevokeLink().
ResourceList event Additional resource fields are now exposed. Refer to the documentation for more information.
SearchResult event Removed. A SearchMatch parameter has been added to the ResourceList event, which should be used instead.
SharedResourceList event Renamed to SharedLinkList. Additional shared link fields are now exposed. Refer to the documentation for more information.
UploadComplete event Removed.
ResourceClientDate configuration setting Renamed to ClientModifiedTime.
ShortURL configuration setting Removed. This information this setting exposed is no longer available in the Dropbox API.

GoogleDrive Component

Overview of Changes

  • Support for team drives has been added, including:
    • Listing team drives with ListTeamDrives(), which fires the event TeamDriveList.
    • Listing team drive members by passing a team drive Id to ListPermissions().
    • The ListResourcesScope, IncludeTeamDriveItems, and TeamDrive properties have been added to modify the behavior of the component when listing changes and resources when desired. Refer to the documentation for ListResources() and ListChanges() for more information.
    • Checking whether you have permission to create team drives with the CanCreateTeamDrives configuration setting.
    • Creating and deleting team drives with the CreateTeamDrive() and DeleteTeamDrive() methods.
    • Adding, updating, and removing team drive members with the AddTeamDriveMember(), UpdateTeamDriveMember(), and RemoveTeamDriveMember() methods.
      • Note that since team drive members are defined by manipulating permissions on a team drive itself, you may also use the general process for manipulating permissions (see documentation for the UpdatePermissions() method).
    • The ability to make certain requests using your domain administrator privileges with the UseDomainAdminAccess configuration setting.
  • Collections are now used in the .NET/Java editions (these are the Change*, Permission*, Resource*, and TeamDrive* properties in other editions).
  • Methods now accept resource/team drive/permission Ids directly as parameters. The ResourceId property no longer exists in .NET/Java, and in other editions it is no longer used to determine what resource a method should operate on.
  • Resource child and parent information handling has been streamlined.
    • ListResource(), ListParents(), and GetResourceInfo() all use the Resources collection property and the ResourceList event.
    • ListChildren() uses the Children collection property and the ResourceList event.
    • Full resource metadata is available after calling the ListChildren() and ListParents() methods.
    • Ids of a resource's parents are now available via the ParentIds field on the items in the Resources and Children collection properties.
  • Manipulating permissions is now accomplished by queuing create/update/delete operations for one or more permissions, and then applying them with the new UpdatePermissions() method. The previous version's AddPermission(), UpdatePermission(), and DeletePermission() methods have been removed. Refer to the documentation for more information.
  • The EmptyTrash() and MoveResource() methods have been added.
  • Many methods now allow batching requests, and/or now have parameters for more common metadata:
    • AddParents(), RemoveParents(), ListChildren(), CreateFolder(), CopyResource(), and MoveResource() method all accept a comma-separated list of parent folder Ids.
    • GetResourceInfo() accepts a list of comma-separated file and folder Ids.
  • The AddChild() and DeleteChild() methods have been removed.

API Migration Table

Cloud Storage Integrator 2016 IP*Works! Cloud 2020
ResourceId property While the ResourceId property still exists in non-.NET/Java editions, it is no longer used to specify which resource to operate on. Methods now accept resource/team drive/permission Ids directly as parameters.
XChildren (.NET/Java), XChild* (non-.NET/Java), XElement, XParent, XPath, XSubTree, and XText properties These properties are now configuration settings.
AddChild() and DeleteChild() methods Removed. Use the AddParents(), RemoveParents(), and MoveResource() methods instead.
AddParent() and DeleteParent() methods Renamed to AddParents() and RemoveParents(); both now allow you to add and remove multiple parents at once.
AddPermission(), DeletePermission(), and UpdatePermission() methods Removed. Permission manipulation is now accomplished by queuing create/update/delete operations for one or more permissions, and then applying them with the new UpdatePermissions() method. Refer to the documentation for more details.
CopyResource() method Now allows you to specify new parents for the copied resource.
CreateFolder() method Now allows you to specify parents for the new folder directly.
GetCurrentChangeMarker() method This method now (correctly) populates the NextChangeMarker property instead of the ChangeMarker property. The documentation, which previously contradicted itself on which of the two properties was populated, has been fixed as well.
Also, while basic behavior of the component has not changed, this method is now sensitive to the new TeamDrive property. Refer to the documentation for more information.
GetResourceInfo() method Now accepts a comma-separated list of file and folder Ids so that it can be used to retrieve multiple resources' information at once.
ListChanges() method Default behavior has not changed, but this method is now sensitive to the IncludeTeamDriveItems and TeamDrive properties. Refer to the documentation for more information.
ListChildren() method This method now functions in the same manner as ListResources(), and accepts a comma-separated list of folder Ids.
ListParents() method This method is now a convenience method which simply retrieves the parent Ids for a resource and passes them to GetResourceInfo().
ListResources() method This method is now sensitive to the ListResourcesScope, IncludeTeamDriveItems, and TeamDrive properties.
MoveToTrash() method Renamed to TrashResource().
RestoreFromTrash() method Renamed to RestoreResource().
UpdateResource() method This method now searches the Resources collection for an item whose Id matches the given one, and then uses that item's fields to update the resource.
PermissionAuthKey configuration setting Removed. The Google Drive v3 API no longer exposes the functionality this setting was used for.
IncludeFiles and IncludeFolders configuration settings Replaced by the ListResourcesMode configuration setting.
ListOnlyRootItems configuration setting Removed. Pass root (an alias for the root folder of Google Drive) to the ListChildren() method instead.

OneDrive Component

Overview of Changes

  • The Microsoft Graph API is now fully supported. New functionality is now available in addition to all previously supported functionality.
    • Note: Support for the legacy OneDrive API (https://api.onedrive.com/v1.0) has been discontinued. Associated configuration settings have been removed.
    • This may impact your OAuth authorization process. Refer to the documentation for the component's Authorization property for more information.
  • Collections are now used in the .NET/Java editions (these are the Resource* and Drive* properties in other editions).
  • The new RemoteId and RemotePath properties are now used to select a remote resource for methods to operate against. The ResourceId, ResourcePath, ResourceParentId, and ResourceParentPath properties no longer exist in .NET/Java, and in other editions they are no longer used to determine what resource (or parent resource) a method should operate on.
  • The new Drive property is now used to select the drive to operate against. The DriveId property no longer exists in .NET/Java, and in other editions it is no longer used to determine what drive the component should operate on.
    • The DefaultDrive configuration setting has also been removed; when the Drive property is empty, the component automatically selects a default drive.
  • The component now has improved support for OneDrive for Business/SharePoint Online drives, since the Microsoft Graph API treats them the same as personal OneDrive drives. Component API additions/changes include:
    • The GroupId configuration setting's behavior has been overhauled.
    • A SiteId configuration setting has been added.
    • The ListGroupDrives configuration setting has been removed in favor of a new ListDrivesScope configuration setting. This new setting provides finer control, and can be used in tandem with the GroupId or SiteId settings.
    • The UsersGroups and SubSites configuration settings have been added. These are convenience settings which return Ids for groups the currently-authenticated user is a part of, and Ids of subsites of the site selected by SiteId (respectively).
    • The CopyToDrive configuration setting has been added, allowing resources to be copied between OneDrive for Business/SharePoint Online drives.
    • The CreateLinkScope configuration setting has been added, allowing organization-only sharing links to be created.
  • The ListChanges() and Search() methods now populate their own marker properties (ChangeMarker/NextChangeMarker, and SearchMarker) instead of reusing the ResourceMarker property (now only used by the ListResources() method).
    • All still use the Resources collection property (Resource* properties in non-.NET/Java editions).
  • A DriveMarker property has been added; the ListDrives() method will use it when necessary.
  • When retrieving the status of a copy operation that has been completed, the Id of the newly-copied resource is now exposed by the CopiedResourceId property.
  • For use-cases that require it, the RelativePath configuration setting has been added. When the RemoteId property is set to the Id of a folder resource, it can be used to select a resource using a path relative to that folder.
  • The usage of ListChanges() has been changed slightly; refer to the documentation for more information.
  • Resource paths are now exposed without the leading /drive/root: prefix so as to work correctly with the new RemotePath property.

API Migration Table

Cloud Storage Integrator 2016 IP*Works! Cloud 2020
ResourceId, ResourcePath, ResourceParentId, and ResourceParentPath properties While these properties still exist in non-.NET/Java editions, they are no longer used to specify which resource to operate on. Use the new RemoteId and RemotePath properties instead.
DriveId property While this property still exists in non-.NET/Java editions, it is no longer used to specify which drive to operate against. Use the new Drive property instead.
ResourceMarker property This property still exists, but it is now only used when calling ListResources(). When calling ListChanges(), use the new ChangeMarker and NextChangeMarker properties; and when calling Search(), use the new SearchMarker property.
ResourceCreatedDate and ResourceModifiedDate properties Renamed to ResourceCreatedTime and ResourceModifiedTime. (In .NET/Java editions, these are OneDriveResource object fields rather than properties.)
ResourceDownloadURL property Removed.
ResourceCRC32Hash and ResourceSHA1Hash properties Resource hashes are now exposed by the ResourceHash property, and the ResourceHashAlgorithm specifies which hash to populate that property with. (In .NET/Java editions, these are OneDriveResource object fields rather than properties.)
URL property Removed. The component only supports the Microsoft Graph API endpoint.
GetCopyInfo() method Renamed to PollCopyStatus().
GetUploadStatus() method Renamed to PollUploadStatus().
ListChanges() method Usage has changed. Refer to the documentation for more information.
DriveList and ResourceList events Additional drive and resource fields are now exposed. Refer to the documentation for more information.
DefaultDrive configuration setting Removed. The functionality provided by this setting is now part of the new Drive property.
GroupId configuration setting This setting is still available, but its usage has changed significantly. Refer to the documentation for more information.
ListGroupDrives configuration setting Replaced by the new ListDrivesScope configuration setting. Refer to the documentation for more information.
UseGraphAPI configuration setting Removed. The Microsoft Graph API is now the only API supported by the component.

Other Updates

IP*Works! Cloud 2020, like any major release, also contains numerous minor improvements and bug fixes. Here are a few we felt were particularly notable, in no particular order:

  • Components that support both plaintext and SSL/TLS connection now use SSL/TLS by default.
  • Support for additional encryption algorithms has been added to all components. Refer to any component's EncryptionAlgorithm property for more information.
  • Error codes have been consolidated and renumbered. Common error codes are now used across all components in nearly all cases.
  • A handful of unused settings in the AmazonS3 component API have been removed. Notably, the Region and LocationConstraint configuration settings have been removed (their functionality duplicated the still-available Region property).

For more information about any of the components, please refer to the IP*Works! Cloud 2020 documentation, which has been heavily revised and greatly expanded for this release. We hope that you'll enjoy using IP*Works! Cloud 2020.


We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.