Repository APIs

Interact with any defined repository by using the default repository APIs that are included in Pega Platform.

For example, you can delete or retrieve a file in a repository. You can also add a new custom repository type so that your application can manage files in a remote file storage repository using the same API that you use for your default repository types. For more information about configuring custom repositories, see Creating a custom repository type.

Pega Cloud Services File Storage notes

For Pega Cloud Services systems, the default storage repository is Pega Cloud Services File Storage, which appears as pegacloudfilestorage in the list of repositories in Records > SysAdmin > Repository.

To manage your files in a Pega Cloud File Storage repository from within a Pega Platform application, use the Repository API to interact with your files or configure a file listener to process your files. Direct access to files using any method other than the Repository API is not supported. For more information, see Configuring a file service and file listener to process data in files on Pega Community.

To manage your files in a Pega Cloud File Storage repository from an external application, you can use the optional SFTP service. For more information, see Configuring custom SFTP and FTPS implementations for Pega applications on Pega Community.

Implementation

Implement repository APIs by creating an activity that an existing data page can call. You must delegate the data page API to custom extension points in the form of 'py' activities to be implemented in the custom class. For example, Embed-Repository-Type-S3 and Embed-Repository-Type-Azure each have different 'py' activities.

Refer to the pyNewFile activity in the Embed-Repository-Type-S3 class for an example of implementing the pyNewFile activity for the custom repository type. For usage documentation of these APIs, see the History tab of each API's data page implementation in Dev Studio.

Repository notes and considerations

Some limitations apply when you build custom repository types by using repository APIs.

  • Pega repository APIs cannot operate on artifacts created outside of Pega, such as S3 buckets, Azure containers, JFrog artifactories, or any files, blobs, or folders in them, that contain any of the following characters: "\", "?", "*", "<", ">", "|", and ":", Either only operate on artifacts created using the Pega repository APIs or avoid using these illegal characters when you create artifacts outside of Pega.
  • Unlike Amazon S3, Microsoft Azure does not support the creation of an empty folder. To support the new folder API, when you invoke D_pxNewFolder, the Repository Manager creates an empty BLOB named $.PEGA$ under that folder.
  • When you use the get file API, D_pxGetFile, the file content is loaded into memory as a base-64 encoded string. When the size of the file to be read is larger than 45 MB, an exception is thrown and the content is not loaded into memory. You can configure the maximum file size by using the repository/maxFileSizeInMemory dynamic system setting in the Pega-IntegrationEngine ruleset.
  • The Import/Export wizard does not support custom repositories.
  • Each type of storage follows the consistency model of the underlying storage. For example, Amazon S3 follows the eventual consistency model. If you create or delete a file and immediately use the Exists API, the result might be the opposite of what you expect. Pega Cloud Services File Storage guarantees only eventual consistency.
  • If you switch from database storage to repository storage, you cannot switch back to database storage without losing access to case attachments stored in the repository.