I need to attach a document on a case specific sharepoint site in constellation application.

User Experience
1

I need to attach a document on a case specific share point site in constellation application.

Problem statement: In constellation application, I have attachment field and it is triggering the share point integration but it is failing as we have one share point site per case which has structure as “BaseURL/Domain/Org/CaseID”. Org and CaseID value are coming from my current case. In constellation we attachment any document then we lost the case context due to thread change and it doesn’t make the site URL properly. I think this is wider issue for the projects which are using share point with dynamic structure of site. Is there any solution which can be used to overcome this problem.

2

@Rahul Toky have you seen this from @Giovani? You don’t have access to action sets in Constellation but the attachment infrastructure is the same for all pega application, you’d need to look at intercepting or extending repository API’s to do this

3

Hi @Rahul Toky

Quick clarification:

  1. Are you using the SharePoint Online Integration component from Pega Marketplace, or planning a Custom Repository?
  2. Is the target SharePoint Online (Microsoft 365) or on‑prem?

Either way, here’s how Constellation handles attachments and how you can implement case‑specific storage and metadata.

How Constellation’s attachment flow works (two phases)

When users attach a file with the Constellation Attachment utility / DX APIs, the platform runs a two‑phase process:

  1. Upload – the client calls the /attachments/upload endpoint; Pega accepts the stream and stages the file on the server. This step does not have case context yet.
  2. Attach (link to the case) – the platform then creates the Data-WorkAttach-File instance and links it to the case; here you have full case context and can run your mapping and repository logic (e.g., set folder path, enrich metadata, call external APIs). The pyDefault on Data-WorkAttach-File is the canonical hook for metadata mapping and invoking your repository connector.

In our client pattern, we add an extension data transform (e.g., Map*Metadata) that runs in the work context during phase 2 to collect the right case properties (IDs, customer keys, classifications) and pass them to the repository API. We’ve also used a “final attachment” page parameter handed off by pyDefault to the extension mapping logic.

Option A — Using the Marketplace SharePoint Online Integration component

If you’re using the Marketplace connector, you’ll configure an app registration and auth profile, then call the component’s rules to create folders/files and set metadata. Be aware that SharePoint Add‑in/ACS app‑only auth is being deprecated by Microsoft; for new tenants (since late 2024) and upcoming timelines for existing tenants, prefer Microsoft Graph (Azure AD) app registrations. If the Marketplace component in your stack relies on ACS, plan a Graph upgrade path.

Alternative: there’s also a Marketplace component that integrates SharePoint Online via Microsoft Graph API if you want a Graph‑first path.

High‑level steps with the Marketplace connector

  1. Install and enable the component in your app.
  2. Register an Azure AD app for SharePoint Online; configure scopes and the Pega Authentication Profile accordingly (no hard‑coded secrets; use DSS/App Settings).
  3. In phase 1 (Upload), accept the file as usual.
  4. In phase 2 (Attach), call your mapping DT from Data-WorkAttach-File.pyDefault to compute site/folder path (e.g., /sites/<BusinessUnit>/cases/<pyID>), set desired metadata, then invoke the component’s create/move/update operations.

Option B — Custom Repository

If you need full control over foldering, metadata, and lifecycle (and to stay upgrade‑safe with Constellation), implement a Custom Repository and let the platform route all attachment operations through it.

1) Define the repository type

  • Create a child class of Embed-Repository-Type-Custom-<YourRepo>; override pyRepoConfiguration and the extension activities you need (pyPublishArtifact, pyFetchArtifact, pyBrowseArtifact, pyPingRepository).
  • Extend Code-Pega-List.pyRepoTypes to register your type.

2) Create a Repository rule & wire the app

  • Records ▸ SysAdmin ▸ Repository → create your repository (auth, endpoints, base directory).
  • In the Application rule ▸ Integration tab, set Content storage to “Store in repository” and select your repository.

3) Hook into the “Attach” phase for metadata

  • In Data-WorkAttach-File.pyDefault, call your extension DT (e.g., Map*Metadata) running in case context to collect keys (Case ID, customer identifiers, document class), and pass them to the repository API.
  • We’ve successfully used a “final attachment page” parameter handed from pyDefault to the mapping DT, which your repository activities consume when creating content.

4) Implement SharePoint‑specific operations

  • Upload (phase 1): write to a temporary folder or use Graph’s upload session if you’re going direct to SharePoint.
  • Finalize (phase 2): create/move to the case‑specific folder and apply metadata; return the external file ID to store on Data-WorkAttach-File.
4

@Giovani Thanks for your response.

  1. Are you using the SharePoint Online Integration component from Pega Marketplace, or planning a Custom Repository? – Yes we are using the SharePoint Online component integration from Pega Marketplace.

  2. Is the target SharePoint Online (Microsoft 365) or on‑prem?-- As far my knowledge we are on prem and will be moving to Online in near future.

Also, regarding the 2 Phase approach we have tried this in another constellation application where we have selected Pega Cloud as repository in the first place to attach the temp file on Pega cloud storage which is during Upload phase of the document and then during Attach phase when we have the case context we are uploading it on SharePoint. The problem with this approach is it is not aligned with client policy on using pega cloud storage. So we want to change this design to get a solution which is more aligned with client policies.

Moreover, I am looking for a solution where I can use the SharePoint as document repository and can get the case context during the Upload Phase or if there is solution which can bypass the Upload Phase and directly go to the attach phase.

5

@Rahul TokyIf you are not allowed to temporary upload the file on Pega cloud repository, you can directly upload it to a temp folder on Sharepoint and later in the attachment phase you move to desired folder, like this you will not keep any files on Pega side.

For having access to work context during upload you would need to request an enhancement to Pega platform.

6

@Rahul Toky, our product team is working to expose the ContextID in the Upload phase as well, Changes are in progress for 25.1.2 and the fix is being backported at least up to 24.2.x

7

Continuing the discussion from I need to attach a document on a case specific sharepoint site in constellation application.:

@Giovani Figueiredo We need to do something similar to the “Option B - Custom Repository” you have explained above in one of your previous comments.

Summarizing we need to store case atachments in Pega Constellation applications into an external repository by using our company custom Rest API services to create, get and delete files from Pega case types into our company repository.

We are a bit concerned whether this use case is feasible in Constellation and make the following questions:

  • Will the attachment widget in Constellation be reusable? Appears to me that a new JS React component will have to be created in order to invoke our company REST API file operations, etc.
  • We do not want to store case attachments in any Pega Cloud repositories or any temporary file folder.
  • We need to send metadata on our custom Rest API operations when storing or retrieveing files and need to get document id in response REST API create or upload file operations. Is this achievable?
  • I have also followed what you have suggested to create a custom respository but i might be missing something because as far as i can see a target folder is needed in order to add the custom respository as a content source repository in the application. I mean we do not need to create a custom repository or configure it with auth, endpoints, base directory, etc. configuration. We will handle authentication when invoking the REST API services and we do not need any target folder in the custom respository. Find attached file with screenshot regarding with the application rule error triggered when saving the application rule. I guess a target folder is needed.

Much appreciated your help on this as we are stuck to advance and generating some uncertainty. Let me know whether we can use this post to communicate or we can contact each other in any other way.

We are currently in Pega infinity 25.1.2

Regards,

Israel

Post Custom repositoy.docx (89.6 KB)

8

Hi @IsraelU11 , if you can implement all of the extension points in the custom repository, then Constellation attachment widget should work OOTB. You should need to create a custom React component only if the user interface does not attend your needs, for example letting the End user to decide which metadata needs to be send to the repository in the widget, however most of the cases can be achieved without a custom react component, you can do it from the flow process for example.
About the folder to configure the application rule, even if your Company’s repository does not support or does not need to folder management, you can implement the pyListFiles in a way to return a mocked root folder e.g.: /, so you should be able to save the application rule with your custom repository.

Regarding the metadata, starting from Pega 25.1.2, you should be able to get “ContextID” during upload phase, in the upload API, like this you can map case data to the metadata you need, so, the workaround to temporary storing files into Pega repositories is not needed anymore.

9

@Giovani Thanks a lot for the quick response. Let me digest your explanation and also understand how case attachment work (upload and attach phases) because it is fairly new topic for me. I also need to know business and user interface needs.

When you mean to implement all the extension points i guess you refer to be able to customize all the Repositoy APIs activities such as pyNewFile, pyGetFile, pyListFiles, pyDelete, etc. in the custom repository, correct?

We are doing a POC right now related to this, we will perform the following steps for option B “Custom Repository” based on the info you provided in previous post:

1) Define the repository type

  • Create a child class of Embed-Repository-Type-Custom-<YourRepo>; override pyRepoConfiguration and the extension activities you need (pyNewFile, pyDelete, pyGetFile, etc)

  • From these extension activities, i guess we will have call or invoke the custom REST API services to upload, dowload, delete files, etc. in our company repository.

  • Extend Code-Pega-List.pyRepoTypes to register your type.

2) Create a Repository rule & wire the app

  • Records ▸ SysAdmin ▸ Repository → create the custom repository.

  • In the Application rule ▸ Integration tab, set Content source to “Source from repository” and select our new created custom repository.

Then i need to understand how Pega behaves when a file is attached to a case through the Constellation attachment widget and what it does in the background, to understand what else needs to be done.

For instance if we are talking about uploading a new file, i guess somehow we will have to set the document id retrieved by the external repository by the custom Rest API into the Data-WorkAttach-File and Link-Attachment instance, and leave the pyAttachStream in the attachment table empty. Something like that. This is the part that i am still confused and need to clarify.

Trying to understand the step 3) Hook into the “Attach” phase for metadata you mentioned in a previous post.

10

Hi Israel, you’re welcome, and your understanding is on the right track.

Extension points (your point 1)

Yes, when I mentioned implementing the extension points, I was referring exactly to those Repository API activities (e.g., pyNewFile, pyGetFile, pyListFiles, pyDelete, etc.).

In your implementation:

  • pyNewFile → call your company’s REST API to upload the file to your repository

  • pyGetFile → retrieve/download the file using the repository’s unique document ID

  • pyDelete → invoke your API to delete the file

  • pyListFiles → list/search documents, typically using metadata you stored along with the file

So yes — these activities become the integration layer between Pega and your external repository.

Repository definition (your point 2)

Your approach is correct:

  • Define a custom repository type (Embed-Repository-Type-Custom-<YourRepo>)

  • Register it (Code-Pega-List.pyRepoTypes)

  • Create the Repository rule

  • Configure the Application → Integration tab → Content source = Repository

Once this is set, Pega will use your custom repository instead of storing files in the DB.

What happens when attaching a file (important part)

This is where the confusion usually happens.

Even with a custom repository, Pega continues to work OOTB from a case attachment perspective:

  • It still creates:

    • Data-WorkAttach-File

    • Link-Attachment

  • These are used to link the case to the attachment

However:

  • The binary (stream / pyAttachStream) is NOT persisted in the database

  • Instead, the file is stored in your external repository via pyNewFile

So effectively:

  • Pega manages relationships + metadata

  • Your repository manages file content

About the document ID (your question)

You are thinking in the right direction.

After uploading the file via your REST API, your repository will return a Unique ID.

You should:

  • Persist that ID in the attachment (typically in a property in Data-WorkAttach-File)

  • This ID is then used later by:

    • pyGetFile (download)

    • pyDelete

    • pyListFiles

Tip: You can extend Data-WorkAttach-File to store:

  • Document ID >> map to pyContentLocation, like this OOTB attachment gadget works as is to download or preview docs(supported preview)

  • Repository path

  • Any custom metadata

“Hook into the attach phase” (metadata clarification)

This is the part I was referring to in my previous post.

When a user uploads a file in Constellation:

  1. File is selected in the UI

  2. Pega triggers the repository APIs (pyNewFile)

  3. Attachment record is created

If you need to send additional metadata to your repository (e.g., Case ID, business attributes, classification, etc.), you can:

  • Extend the attachment data model (Data-WorkAttach-File)

  • Populate these fields before calling pyNewFile

  • Pass them as part of your REST payload

This allows:

  • Better search (pyListFiles)

  • Better organization in your external repositor

Key takeaway

  • Pega does not change its attachment model

  • You are simply replacing the storage layer

  • The integration happens at the Repository API level

  • Metadata handling is your responsibility (extension point + data model)

11

@IsraelU11 I was able to recover the article which was published sometime ago: Implementing Custom Repository Extension APIs | Support Center

12

@Giovani Really helpful your comments and the article. Glad to hear from you i am in the right track.

Getting close. Now hands on and make some progress in our POC to check whether we can achieve our use case and reuse without customizing the Constellation attachment widget.

I will get back to you as soon as we finish implementing our POC and let you know.

Regards,

Israel

13

@Giovani I finished implementing our POC, follow your suggestions and the attachment utility widget in Constellation work as expected, we could succesffully upload, download, open and delete files in Pega infinity 25.1.2 by using attachment utility ootb Pega widget creating a custom repository integrating via custom Rest API with an external repository.

Thanks a lot for your quick help, much appreciated.

Regards,

Israel

14

Hi Israel, I’m glad to hear from you that you achieved the requirements for your POC.