Manipulating Clarity's Data with APIs

Liferay's headless APIs provide robust functionality to create, modify, and delete data across Liferay's components. Clarity's team wants to test manipulating data with APIs to better understand how to leverage them for their custom UIs and applications effectively. In these exercises, you'll use REST methods to create and modify Ticket object entries.

Exercise: Creating Clarity's Ticket Object Entries

Here, you'll leverage object APIs to create a new ticket and ensure it's successfully added to the system.

1. Sign in as the Clarity Admin user.

   • Username: admin@clarityvisionsolutions.com
   • Password: learn

2. Navigate to the API Explorer at http://localhost:8080/o/api.

3. Click the REST Applications drop-down menu and select c/tickets.

4. Under the Ticket section, expand the postTicket endpoint.

5. Input the following code to the Request body:

   {
   	"subject": "Color degradation",
   	"externalReferenceCode": "TCK0035",
   	"priority":  {
   		"key": "critical"
   	},
   	"r_accountToTickets_accountEntryId": "54639",
   	"r_userToTickets_userERC": "USER_RENEE",
   	"region":{
   		"key": "lATAM"
   	},
   	"resolution": {
   		"key": "approved",
   		"name": "Approved"
   	},
   	"ticketStatus": {
   		"key": "open"
   	},
   	"type": {
   		"key": "other"
   	}
   }
   

   Copy

6. Click Execute and verify the server response code is 200.

7. Expand the getByExternalReferenceCode endpoint.

8. Enter TCK0035 as the externalReferenceCode parameter and click Execute.

   

9. Within the response body, verify that the returned information lists the previously created ticket:

   ...
   "externalReferenceCode": "TCK0035",
   ...
   "subject": "Color degradation",
   "description": "",
   "r_userToTickets_userERC": "USER_RENEE",
   ...
   

   Copy

Exercise: Updating Clarity's Tickets with PUT

Here, you'll modify the created ticket with a PUT request to add a description.

1. Within the Tickets object on API explorer, expand the putByExternalReferenceCode endpoint.

2. Enter TCK0035 for the externalReferenceCode parameter.

3. Input the following code to the Request body:

   {
   	"subject": "Color degradation",
   	"externalReferenceCode": "TCK0035",
   	"description": "The delivered lenses are presenting color degradation",
   	"priority":  {
   		"key": "critical"
   	},
   	"r_accountToTickets_accountEntryId": "54639",
   	"r_userToTickets_userERC": "USER_RENEE",
   	"region":{
   		"key": "lATAM"
   	},
   	"resolution": {
   		"key": "approved",
   		"name": "Approved"
   	},
   	"ticketStatus": {
   		"key": "open"
   	},
   	"type": {
   		"key": "other"
   	}
   }
   

   Copy

   Since this is a PUT request, the ticket's existing fields and values must still be included to retain the stored information.

4. Click Execute and verify the server response code is 200.

5. Expand the getByExternalReferenceCode endpoint.

6. Enter TCK0035 as the externalReferenceCode parameter and click Execute.

7. Within the Response body, verify that the returned information lists the updated description:

   ...
   "description": "The delivered lenses are presenting color degradation",
   ...
   

   Copy

Exercise: Updating Clarity's Tickets with PATCH

Here, you'll update the ticket by sending a PATCH request adjusting its priority.

1. Within the Tickets object on API explorer, expand the patchByExternalReferenceCode endpoint.

2. Enter TCK0035 for the externalReferenceCode parameter.

3. Input the following code to the Request body:

   {
   	"priority":  {
     		"key": "major"
   	}
   }
   

   Copy

   

4. Click Execute and verify the server response code is 200.

5. Expand the getByExternalReferenceCode endpoint.

6. Enter TCK0035 as the externalReferenceCode parameter and click Execute.

7. Check that the server response code is 200 and that the description has been updated:

   ...
   "subject": "Color degradation",
   "description": "The delivered lenses are presenting color degradation",
   "r_userToTickets_userERC": "USER_RENEE",
   "priority": {
   	"key": "major",
   	"name": "Major"
   },
   ...
   

   Copy

   By leveraging the PATCH endpoint, existing field values were retained without being explicitly included in the PATCH call.

Exercise: Assigning Clarity's Tickets with Object Actions

Here, you'll configure the AssignToMe Object Action and leverage its API to assign yourself a ticket.

1. In your browser, go to the Clarity Public Enterprise Website.

2. Open the Global Menu (), go to the Control Panel tab, and click Users and Organizations.

3. Click on the Clarity Admin user and copy the User ID for use in a later step.

   

4. Open the Global Menu (), go to the Control Panel tab, and click Objects.

5. Go to the Ticketing folder and being editing Ticket.

6. Select the Actions tab and click Assign Ticket to Me.

   

7. Go to the Action Builder tab.

8. Under the Values section click Add (ICON).

9. Select the User to Tickets field and click Save.

   

10. Check the Input as a value checkbox.

11. In the New Value column add Clarity's User ID.

    

12. Click Save.

13. Navigate back to the API Explorer at http://localhost:8080/o/api.

14. Click on the REST Applications drop-down menu and select c/tickets.

15. Expand the putTicketAssignTicketToMe endpoint for ERCs.

    

16. Enter TCK0035 for the externalReferenceCode parameter and click Execute.

17. Verify that the server response code is 204.

    NOTE
    A 204 “No Content” response code means a request is successful but doen't include a response payload.

18. Expand the getByExternalReferenceCode endpoint.

19. Enter these parameters and click Execute.

    Parameter	Value
    externalReferenceCode	TCK0035
    nestedFields	userToTicket

    
    
    
     

20. Verify in the Response body that the ticket has been assigned to Clarity Admin:

    ...
    "r_userToTickets_user": {
    ...
    "alternateName": "clarityadmin",
    ...
    "familyName": "Admin",
    "givenName": "Clarity",
    ...
    

    Copy

Exercise: Removing Clarity's Tickets with DELETE

Here, you'll delete the ticket by sending a DELETE request, permanently removing it from the system.

1. Within the Tickets object on API explorer, expand the deleteByExternalReferenceCode endpoint.

2. Enter TCK0035 for the externalReferenceCode parameter and click Execute.

3. Verify the server responds with a 204:

   

4. Expand the getByExternalReferenceCode endpoint.

5. Enter TCK0035 as the externalReferenceCode parameter and click Execute.

6. Verify a server response of 404 and Response body of Not Found, confirming the ticket's deletion:

   {
        "status": "NOT_FOUND"
   }
   

   Copy

Conclusion

Great! You've successfully used headless APIs to create, update, and remove data from Clarity's system. Clarity's developers can leverage these APIs within their planned dashboards to perform intricate data manipulation actions.

Next, you'll learn how to handle attachments with Liferay's headless APIs.