Table of Contents

Repository APIs

+

This content applies to On-Premises Services and Cloud environments.

You can use the default repository APIs that are included in Pega Platform™ to interact with any defined repository. For example, you can delete or retrieve a file in a repository. Using Dev Studio, you can find documentation for each API by clicking the History tab of that API data page implementation. 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 Custom repository types.

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. Pega does not support direct access to files in a Pega Cloud File Storage repository. You manage your files in a Pega Cloud File Storage repository by using the Repository API to interact with your files or configuring a file listener to process your files. Alternatively you can configure a file listener to process files in a Pega Cloud File Storage repository. For details, see Configuring a file service and file listener to process data in files.

Repository notes and considerations

Some limitations apply when you build custom repository types by using repository APIs in Pega Platform™.

  • For Pega Platform versions prior to 8.3, do not use the following characters in the filePath or folderPath parameters: "\", "?", "*", "<", ">", "|", or ":"
  • 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 above listed illegal characters. 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 because the only way to create a folder in Azure is to create a BLOB under the 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.
  • Once 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.

For more information about building repository types, see Custom repository types.

Create folder API

The create folder API is a savable data page, D_pxNewFolder. The API represents the new folder as a data page when the data page is loaded. To create a folder with this API, pass in the following parameters:

  • repositoryName- the name of the repository in which to create the file
  • folderPath- the path to the folder to be created relative to the root path of the repository

To create a folder, save the savable data page. For information about how to save savable data pages, see step 13 in Creating a data page to save data.

Create file API

The create file API is a savable data page, D_pxNewFile. The API represents the new file as a data page when it is loaded. You can use this API to create a file or overwrite an existing file. To define a file with this API, define the following parameters:

  • repositoryName- the name of the repository in which to create the file.
  • filePath- the path, including the name of the file, to be created, relative to the root path of the repository. To find out what the path is, run D_pxListFiles against the repository and view the pyPath property.

This API accepts a base-64 string as the file content or a java.io.InputStream object as the source for file content. If both options are specified, preference is given to the string. If neither option is specified, an empty file is created.

Set the file content, pyContents, or the stream, pyStream, on the data page.

For large files, use the java.io.InputStream option.

To create a file, save the savable data page. For information about how to save savable data pages, see step 13 in Creating a data page to save data.

Get file API

The get file API is a read-only data page, D_pxGetFile. This API loads content or a stream to a file when the data page is loaded. To use this API, define the following parameters:

  • repositoryName- the name of the repository from which to get the file
  • filePath- the path, including the name of the file, to be retrieved, relative to the root path of the repository
  • responseType- the type of content that is in the file to be retrieved, either "STREAM" or "STRING"
It is a best practice to use the Stream responseType. Use the String option only for backward compatibility purposes.

List files API

The list files API is a read-only data page, D_pxListFiles. This API lists files and folders in a specific a folder on a repository. To use this API, define the following parameters:

  • repositoryName- the name of the repository
  • folderPath- the path, relative to the root path of the repository, to the folder whose contents you want to list

This API returns the following metadata for files and folders in the directory that you defined:

  • pyName - the short name of the file or folder.
  • pyPath - the complete path to the file or folder.
  • pyIsFolder - a Boolean value that is true if the content is a folder and false if it is a file.
  • pyLength - the size of a file in bytes. This value is not returned for folders.
  • pyLastModifiedTime - the last time that a file or folder was modified.

Exists API

The exists API is a when rule, pxExists. This API returns a true Boolean value if the folder or file exists. To use this API, define the following parameters:

  • repositoryName- the name of the repository
  • filePath- the path to the file or folder, relative to the root path of the repository

Delete API

The delete API is a read-only data page, D_pxDelete. This API deletes a specific file or folder in a repository. To use this API, define the following parameters:

  • repositoryName- the name of the repository from which you want to delete the file or folder.
  • filePath- the path to the file or folder that you want to delete, relative to the root path of the repository.
  • recursiveDelete- specifies whether to recursively delete the folder contents. As a best practice, set this parameter to true. If you set this value to false for a folder, the folder must be empty.

Is authenticated API

The is authenticated API is a read-only data page, D_pxIsAuthenticated. This API returns a true Boolean value if a user or system is authenticated with a specific repository. To use this API, define the following parameter:

  • repositoryName- the name of the repository.
Suggest Edit

60% found this useful


Related Content

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.