Personalization folder APIs | HCL Digital Experience
The Personalization folder REST APIs provide access to personalization folder capabilities using REST services.
For more information on HCL Digital Experience Personalization Folders, refer to the Personalization Help Center topic.
Personalization folder endpoints
- POST or create a new Personalization folder
- PUT or update an existing Personalization folder
- GET Personalization Folder details using folder id
- GET list of Personalization Folders
- DELETE Personalization Folder using folder id
For more details on the Personalization response payload, refer to the Response payload explanation section below.
Create (POST) a new Personalization folder
Use this API to create a new Personalization folder in the Personalization workspace.
- POST request to:
-
https://localhost:10039/wps/mycontenthandler/pzn-rest/folders
- POST Personalization Folder REST API example:
-
https://localhost:10039/wps/mycontenthandler/pzn-rest/folders
- Sample Request Payload:
-
{ "title": "demo", "description": "demo folder", "parentId": "b7bbddd7-95c6-4062-8971-134f780002f1" }
- Steps to execute the POST Personalization Folder RESTAPI:
-
- Login to your Digital Experience solution.
- The login cookie contains the Authentication token. Leave the cookie field empty if you are already authenticated, unless you intend to put a token value.
- Provide the title of the folder.
- (Optional): Provide a description of the folder.
- (Optional) Provide the
parentId
of the location of the folder where you want to create. Otherwise, the new folder is to be created in the workspace by default.
- Combined Response Structure:
-
When you execute the POST Personalization Folder REST API, it creates a folder in the Personalization interface Workspace or inside an existing folder.
parentId
is the main attribute to use to find the difference between the rules available in theWorkspace
andFolder
:Workspace parentId
always starts with a hyphen ("-").Example:
"parentId": "_6QR_0048AAQUGF0A1T2A_18L"
Folder parentId
always starts without a hyphen ("-").Example:
"parentId": "ee99433c-82d2-46eb-b48b-90cc234e57e2"
- Response Structure Details:
-
- The response structure gets the details of the created folder and the response for the created folder.
- For more details on the Response Payload, refer to the Response Payload section below.
- The example below shows the response for one Personalization
folder:
{ "id": "5bd89b0d-f024-4de2-a991-976315e917be", "description": "demo folder", "title": "demo", "authors": "uid=wpsadmin,o=defaultWIMFileBasedRealm", "creator": "uid=wpsadmin,o=defaultWIMFileBasedRealm", "created": "2022-01-13T07:14:01.035Z", "lastModified": "2022-01-13T07:14:01.035Z", "lastModifier": "uid=wpsadmin,o=defaultWIMFileBasedRealm", "parentId": "_6QR_0048AAQUGF0A1T2A_18L" }
- POST Personalization Folder REST API Success and Error Messages
-
Error Code Means 200 This code is returned when you create a folder successfully. 400 This code is returned if the input parameters are missing or invalid. Title
is missing in body.Title
is empty in body.ParentId
is invalid in body.
401 This code is returned when the LtpaToken
is invalid or expired.403 This code is returned when user access is restricted. 409 This code is returned when we you are trying to create a folder with the same of an existing folder. 500 This code is returned when an internal server error occurs.
Update (PUT) a Personalization folder
The Update a Personalization Folder REST API is used to update an existing Personalization Folder.
- PUT Request to:
-
https://localhost:10039/wps/mycontenthandler/pzn-rest/folders/{folder-id}
- Update a Personalization Folder REST API example:
-
https://localhost:10039/wps/mycontenthandler/pzn-rest/folders/5bd89b0d-f024-4de2-a991-976315e917be
- Sample Request Payload:
-
{ "title": "demo", "description": "demo folder", "parentId": "b7bbddd7-95c6-4062-8971-134f780002f1" }
- Steps to execute the Update a Personalization Folder REST API:
-
- Login to your Digital Experience solution.
- The login cookie contains the Authentication token. Leave the cookie field empty if you are already authenticated, unless you intend to put a token value.
- Provide the following Personalization Folder-ID details which is to be updated.
- Provide either title or description or
parentId
of the Personalization folder in the request body.Note 1: Updating a root folder/workspace is restricted. The API returns a 403 error code for this scenario.Note 2: TheparentId
input is to be passed if the selected Personalization folder has to be moved to a different location.To retrieve theparentId
for a specific workspace or existing Personalization using the JCR explorer, follow the steps below:- Navigate to the WCM Support Tools.
- Click Browse Nodes.
- To get the workspace
parentID
, navigate to Properties section and use the value of the jcr:uuid field as shown below. - To get the
parentID
for an existing folder, click to select a folder from the Children section and use the value of the jcr:uuid field as shown below.
- Combined Response Structure:
- When you execute the PUT Personalization Folder REST API to update a folder, it may move the folder either to the Workspace or inside another Folder.
- Response Structure Details:
-
- In the response structure, we get the details of the updated folder, and the response is attached below.
- For more details on the Response Payload, refer to the Response Payload section below.
- The example below shows the response for updating a selected
Personalization
folder:
{ "id": "5bd89b0d-f024-4de2-a991-976315e917be", "description": "demo folder", "title": "demo", "authors": "uid=wpsadmin,o=defaultWIMFileBasedRealm", "creator": "uid=wpsadmin,o=defaultWIMFileBasedRealm", "created": "2022-01-13T07:14:01.035Z", "lastModified": "2022-01-13T07:14:01.035Z", "lastModifier": "uid=wpsadmin,o=defaultWIMFileBasedRealm", "parentId": "_6QR_0048AAQUGF0A1T2A_18L" }
- PUT Personalization Folder REST API Success and Error Messages
-
Error Code Means 200 This code is returned when you update a folder successfully. 400 This code is returned if the input parameters are missing or invalid. Title
is missing in body.Title
is empty in body.ParentId
is invalid in body.
401 This code is returned when the LtpaToken
is invalid or expired.403 This code is returned when user access is restricted. (e.g. User tries to update a root folder/workspace)
409 This code is returned when we you are trying to create a folder with the same of an existing folder. 500 This code is returned when an internal server error occurs.
GET Personalization folder-id
The GET Personalization Folder ID REST API is used to get individual Personalization Folder ID details.
- GET Request format:
-
https://localhost:10039/wps/mycontenthandler/pzn-rest/folders/{folder-id}
- GET Personalization Folder ID REST API example:
-
https://localhost:10039/wps/mycontenthandler/pzn-rest/folders/5bd89b0d-f024-4de2-a991-976315e917be
- Steps to execute the GET Personalization Folder ID REST API:
-
- Login to your Digital Experience solution.
- The login cookie contains the Authentication token. Leave the cookie field empty if you are already authenticated, unless you intend to put a token value.
- Obtain the Personalization Folder ID details using the REST API
GET all
API command, as shown in the following example:
- Response structure details:
-
- The response structure gets the details of the selected Personalization ID folder.
- For more details, see Response Payload below.
- GET Personalization Folder ID Success and Error Messages:
-
Error Code Means 200 This code is returned when the folder details are obtained successfully. 401 This code is returned when the LtpaToken
is invalid or expired.403 This code is returned when access is restricted for user. 404 This code is returned when the Folder ID is not found or invalid. 500 This code is returned when an internal server error occurs.
GET list of Personalization folders
- GET Request format:
-
https://localhost:10039/wps/mycontenthandler/pzn-rest/folders/
- GET Personalization Folder list REST API example:
-
http://localhost:10039/wps/mycontenthandler/pzn-rest/folders?limit=30&offset=0&depth=Descendants&parent=ffbbddd7-95c6-4062-8971-134f780002f1
- Steps to execute the GET Personalization Folder list REST API
-
- Login to your Digital Experience solution.
- The login cookie contains the Authentication token. Leave the cookie field empty if you are already authenticated, unless you intend to put a token value.
- Add the following parameters:
- The limit or the pagination parameter that indicates the number of results to be returned.
- The offset or the pagination parameter that indicates the starting point from which results are to be returned.
- The depth or the level of depth to get the list of folders based on either children or descendants.
- The
parentid
of the folder you wish to get all descendant/children folders.
For example:
- Response Structure Details:
-
- In the response structure, you get the list of all descendant folders inside the parent folder with details.
- For more details on the
items
array and its elements, refer to the Response Payload section below. - Response for the get all folder is shown
below:
{ "offset": 0, "limit": 30, "total": 2, "items": [ { "id": "ffbbddd7-95c6-4062-8971-134f780002f1", "folderType": "Folder", "description": "Demo folder", "title": "DemoFolder2", "parentId": "_6QR_0048AAQUGF0A1T2A_18L", "authors": "uid=wpsadmin,o=defaultWIMFileBasedRealm", "creator": "wpsadmin", "created": "2021-09-30T11:25:57.090Z", "lastModified": "2021-09-30T11:25:57.090Z", "lastModifier": "wpsadmin" }, { "id": "b7bbddd7-95c6-4062-8971-134f780002f2", "folderType": "Folder", "description": "Demo folder2", "title": "DemoFolder2", "parentId": "ffbbddd7-95c6-4062-8971-134f780002f1", "authors": "uid=wpsadmin,o=defaultWIMFileBasedRealm", "creator": "wpsadmin", "created": "2021-09-30T11:25:57.090Z", "lastModified": "2021-09-30T11:25:57.090Z", "lastModifier": "wpsadmin" } ] }
- GET Personalization Folder list Success and Error Messages:
-
Error Code Means 200 This code is returned when you get all the list of folders details successfully. 400 This code is returned if the input parameters are missing or invalid. - Limit is a decimal value.
- Offset is a decimal value.
- Depth is not among allowed depths.
ParentId
is invalid in body.
401 This code is returned when your LtpaToken
is invalid/expired.403 This code is returned when access is restricted for user. 404 This code is returned when the API URL is inaccessible. 500 This code is returned when an internal server error occurs.
DELETE Personalization folder
- DELETE Request format:
-
https://localhost:10039/wps/mycontenthandler/pzn-rest/folders/{folder-id}
- DELETE Personalization Folder ID example:
-
https://localhost:10039/wps/mycontenthandler/pzn-rest/folders/880bb281-bb82-489c-a220-56104f0f638d
- Steps to execute the DELETE Personalization Folder ID REST API:
-
- Login to your Digital Experience solution.
- The login cookie contains the Authentication token. Leave the cookie field empty if you are already authenticated, unless you intend to put a token value.
- Delete the Personalization Folder you wish to delete by providing the folder ID as shown in the following example:
- Response structure details:
-
{ "message": Folder with id: 880bb281-bb82-489c-a220-56104f0f638d deleted successfully }
- DELETE Personalization Folder ID Success and Error Messages:
-
Error Code Means 200 This code is returned when the selected folder is deleted successfully. 401 This code is returned when the LtpaToken
is invalid or expired.403 This code is returned when access is restricted for user. 404 This code is returned when the Folder ID is not found or invalid. 500 This code is returned when an internal server error occurs.
Response payload explanation
"id"
- Field to indicate folder uuid."folderType"
- Field to indicate folder type root folder (Workspace) or custom Folder"description"
- Field to indicate description of the folder."title"
- Field to indicate that title of the folder."authors"
- Field to indicate that owner of the folder."creator"
- Field to indicate that creator of the folder."created"
- Field to indicate that creation date and time of the folder."lastModified"
- Filed to indicate that last modified date and time of the folder."lastModifier"
- Filed to indicate that details of the user who is last modified the folder."parentId"
- Field to indicate to find the difference between the location of the folder.