Pega DX API Attachment - v 2.docx (859.5 KB)
Good day, community.
I am sharing this guide that explains how to upload attachments using Pega DX API v2 and create a case with the document already attached. Also, sharing some Required attachment fields Must Not be missed when sending documents.
Regards
This approach is particularly useful for:
- Pega Constellation-based applications
- External system integrations
The process consists of two main steps:
- Uploading the attachment using the DX API
- Creating the case and referencing the uploaded attachment
Prerequisites
Before proceeding, ensure the following configurations are completed:
- OAuth 2.0 client registration is properly configured
- Postman is configured
- The data transform AllowedStartingFields is accessible for updates
For OAuth and Postman setup, refer to Pega Academy DX API exercises. Follow steps from 1 to 3 of the following link https://academy.pega.com/challenge/exploring-dx-api-postman/v3/in/94286#body
Step 1: Configure Attachment Category
In Dev Studio, navigate to:
Case Type > Settings > Attachment and categories
- Add a new attachment category use an out-of-the-box (OOTB) configuration
- When created, Pega automatically generates the corresponding property.
Ensure changes are saved.
Note: The property gets generated with the following configuration:
Step 2: Update AllowedStartingFields Data Transform
Update the AllowedStartingFields data transform to include the attachment property created in Step 1.
Important:
- Property is generated as a Page List, use Append and Map to
Save the changes after updating.
Step 3: Upload Attachment Using DX API
Use the following endpoint:
POST /attachments/upload
Request Configuration
- Method: POST
- Body type: form-data
- Key: content
- Type: File
- Value: Upload the file
Response
- A successful response returns an ID
This ID represents a temporary attachment stored in: Data-WorkAttach-File-Temp
Note: This temporary instance is required to link the file to a case in the next step.
Step 4: Create Case with Attachment
Use the following endpoint:
POST /cases
Include the attachment details in the request body.
Example Request Body
{
"caseTypeID": "<<your app class goes here>>",
"content": {
// pyWorkPage fields goes here
},
"attachments": [
{
"ID": "{{attachmentID}}",
"attachmentFieldName": "FileAttachments",
"category": "File",
"name": "Gorilaz",
"type": "File"
}
]
}
Field Definitions
| Field | Required | Description |
|---|---|---|
| ID | Yes | Temporary attachment ID returned from POST /attachments/upload |
| type | Yes | Must be set to “File” |
| attachmentFieldName | Yes | Property configured in Attachment settings |
| category | No | Typically set to “File” |
| name | No | Display name of the document |
Important Validation
The activity pzCheckFieldSecurity validates required fields during case creation.
- Validation occurs internally during request processing
- Missing required fields (such as ID, type, or attachmentFieldName) will cause the API to fail.
Validation in Pega
After a successful request:
- The case is created
- The attachment is automatically associated
- The file is no longer temporary and is persisted with the case
References
https://docs.pega.com/bundle/dx-api/page/platform/dx-api/endpoint-post-attachments-upload_1.html
https://docs.pega.com/bundle/dx-api/page/platform/dx-api/endpoint-post-cases_0.html
Enjoyed this article?
See suggested articles from our Constellation 101 series and view all our Knowledge Shares from our User Experience Expert Circle.