Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Repository APIs

Updated on April 6, 2022

Pega Platform provides default repository APIs to interact with a define repository. To understand how to use and configure repository APIs, review the following descriptions of each repository API.

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 Creating a save plan for a data page in Dev Studio.

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.

Note: 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 Creating a save plan for a data page in Dev Studio.

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".

Note: It is a best practice to use the Stream responseType. Use the String option only for backward compatibility purposes.

Using the file content that the get file API returns to the external application

Consider a use case in which you use the D_pxGetFile data page in an activity to source a file that is then sent back to the browser to be downloaded to local disk storage.

responseType parameter set to STREAM

If the D_pxGetFile data page is invoked with the responseType parameter set to STREAM, the file content is displayed on the data page as a java.io.InputStream object that is the value of the pyStream property.

The following example shows the Java step in which the data page is given as the step page:

// Get the file contents from the data page as a Base64-encoded string value
Object fileStream = myStepPage.getObject("pyStream");
if (fileStream != null && fileStream instanceof java.io.InputStream) {
  try {
    // Send the file data back to the browser
    // NOTE: fileName is a local variable of type String that has been set to the name of the file being downloaded
    tools.sendFile((java.io.InputStream)fileStream,fileName,null,true);
  }
  finally {
    // Always close the input stream
    try {
      ((java.io.InputStream)fileStream).close();
    }
    catch (java.io.IOException e) {
      oLog.error("caught exception while closing input stream", e);
    }
  }
}

Note: The application that is calling this data page must close the stream object after downloading the file data. If the application leaves the stream object open, subsequent calls to the data page might fail because all of the available HTTP connections to the repository are left open.

responseType parameter set to STRING

If the D_pxGetFile data page is invoked with the responseType parameter set to STRING, the file content is displayed on the data page as a Base64-encoded string that is the value of the pyContents property.

The following example shows the Java step that sends the file data to the browser and has the data page given as the step page:

// Get the file contents from the data page as a Base64-encoded string value
String fileContents = myStepPage.getString("pyContents");
if (fileContents != null && fileContents.length() > 0) {
  // Decode the Base64 string to a byte array
  byte[] fileBytes = java.util.Base64.getDecoder().decode(fileContents);
  // Send the file data back to the browser
  // NOTE: fileName is a local variable of type String that has been set to the name of the file being downloaded
  tools.sendFile(fileBytes,fileName,false,null,true);
}

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.

Have a question? Get answers now.

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

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us