How to use Repository API

General
,
1

Hi,

Recently I have written up an article about how to set up Repository at https://collaborate.pega.com/discussion/how-set-repository. In this post, I am sharing how to use Repository API, which allows developers to do files / folders CRUD operation in Repository. Be noted, other type of methods such as custom Java are not supported for Repository interaction. You can reference Help for API, but I’ve included a concrete sample code and hope that helps beginners understand quicker. Please see attached for the documentation.

Below is a table of Repository APIs that I included.

No Repository API Rule name Rule type Parameters Note
1 Create folder API D_pxNewFolder Savable Data Page
1. repositoryName
1. folderPath
 This API creates a folder in a repository. If you want to create a sub folder under existing folder, use slash (ex. “/parentfolder/childfolder”). To call this API, in an activity, use Save-DataPage method and specify “D_pxNewFolder”.
2 Create file API D_pxNewFile Savable Data Page
1. repositoryName
1. filePath
 This API creates (uploads) a file in a repository. You need to prepare a file contents before calling API. You can either pass file contents to API either by String (pyContents) or Stream (pyStream). Unlike Get file API, there is no explicit parameter that differentiates these and whichever property is populated will be used. If both properties are populated, String will take precedence.
3 Get file API D_pxGetFile Read-only Data Page
1. repositoryName
1. filePath
1. responseType
 This API retrieves (downloads) a file from repository. In order to download file to client terminal, you can use tools.sendFile API in a Java step. You can handle the file either by String or Stream (the best practice is to use Stream). If you use Jave step, D_pxGetFile has to be spcified in the Step Page.
4 List files API D_pxListFiles Read-only Data Page
1. repositoryName
1. folderPath
 This API lists all the files and folders in a folder in a repository. This is limited to only the specified folder and it won’t give you all the folder hierarchy. The returned information is put into pxResults page list of D_pxListFiles.
5 Exists API pxExists When rule
1. repositoryName
1. filePath
 This API evaluates if the specified folder or file exists in a repository and returns Boolean value. You may want to use this before Create file API or Delete file API to confirm.
6 Delete API D_pxDelete Read-only Data Page
1. repositoryName
1. filePath
1. recursiveDelete
 This API deletes a file or folder in a repository. If “recursiveDelete” parameter is checked, it recursively deletes all the folder contents. As a best practice, set this parameter to true. If you set this value to false for a folder, and the folder is not empty, system throws an error “The target folder was not empty”.

Thanks,

HowToUseRepositoryAPI_0.xlsx (2.6 MB)

2

@KenshoTsuchihashi

Cool. This is very useful and helpful post. ^^)

3

@KenshoTsuchihashi Thank you for very very useful post. However I had a question. I am surprised the list API does not allow for specifying a file mask like “." to only retrieve folders or ".doc” to only retrieve word files, etc. I have a situation where I need to only return sub-folders in a folder and I ended up having to write another D_Page with a data transform that looks for property informing item in list is folder.

Is this a miss on the part of Pega? Or maybe underlying S3 implementation does not allow this? A lame to be in, regardless.

4

@KenshoTsuchihashi : Very helpful post. Thanks

5

@KenshoTsuchihashi

I am trying to use the D_pxNewFile Api to write files using the pyStream property. For my example, I am using the attaching screen and creating a PRInputStream from the uploaded file. I am then setting the pyStream property via a java step..

From what I can tell, the pyStream is getting set. I tested this using the following java step:

java.io.InputStream stream = (java.io.InputStream)stepPage.getObject(“pyStream”);
int avail = stream.available();

and I am getting values.

My file gets created in my repository, but the size of the file is zero. I am struggling to figure out what the issue is. pyContent does not show up on the clipboard.

6

@Chris_Boone

after a fair amount of trial and error we finally figured out that the data page does not save file streams when he data page is used as a data page referencing property. You must reference the data page directly in order to attach a file stream to it.

7

@Chris_Boone We’re running into a similar issue, can you share a screenshot of your implementation, that will be really helpful.

8

@KenshoTsuchihashi

Do you know whether these APIs - exposed by a custom repository - when getting called (specifically “file create”) by Pega, do get contextual Pega information/metadata about the file being handled?

I am assuming here that the repository is a smart repository like a DMS or Archive platform that can make use of context metadata “case ID” from which storage is initiated, so that the DMS could present a back-reference link in its own DMS UI or expose that metadata in its own views.