Comment on page
Use Cases
This page describes how the API can achieve a goal or objective and outlines the steps involved in a scenario, the tasks or actions to be performed, and the expected results or outcomes.
The use cases are set to a specific objective and outcome and intended as a template to leverage for all API needs.
The use cases are separated into three categories:
- 1.Introductory Use Cases: Objectives common for all PlexTrac users when getting started. These use cases are relatively straightforward.
- 2.Intermediate Use Cases: Objectives that are easy to achieve within the platform but contain non-intuitive steps when done via API. Some platform interactions send multiple API requests, which can be confusing to replicate when manually calling API endpoints.
- 3.Advanced Use Cases: Objectives not available within the platform but doable via API. Since certain platform functionality consists of making requests to multiple API endpoints, new functionality can be created by combining various API requests and data transformation. An example of an advanced use case is with data import/export. While Plextrac doesn't have the functionality to import/export all stored data, POST requests to create and GET requests exist in the database. Combining a GET request with saving the response to a JSON can create the functionality to export the data. Data can be imported by combining some data transformation to remove IDs and a POST request to create a new data object.
This page will be enhanced over time. If a use case that needs to be added is missing, contact the Support Portal and submit a request.
Objective: Obtain a valid token and cookie for a session.
- 1.Execute the POST Authentication API:
{{instanceUrl}}/api/v1/authenticateby providing a valid instance url, user name and password in the parameters of the request. - 2.If successful, the
tennant_id,cookie, andtokenvalues will be returned.
- 3.Extract the session token from the response body.
- 4.Use the value in the
tokenfield as the required Bearer token sent to other endpoints.
The token is good for 15 minutes.
Objective: Obtain a list of all users for a tenancy.
- 1.Execute the GET Tenant Users API:
{{instanceUrl}}/api/v2/tenants/{{tenantId}}/usersby providing a valid instance url and tenant ID in the parameters of the request. - 2.If successful, a list of users will be returned with several attributes tied to each user, such as when the user was created, what role they belong to, email address, and last login date.
Objective: Add images through the API that are rendered in the platform and on export as a Microsoft Word document.
Notes: This functionality exists within the platform, but accomplishing it through the API is not intuitive. POST Upload Image to
Tenant[https://api-docs.plextrac.com/#35efb6b8-22d3-4271- 98fa-b9865d072461] is used in conjunction with any endpoint that creates or updates an object that contains a CKEditor fieldSummary: When passing images through API requests, one common practice is to send the Base64 encoded image as a string. This will not work if exporting a report with the image to Microsoft Word, as this format does not support Base64 encoded images.
Steps:
- 1.Add the image to your instance with the POST Upload Image to
Tenant[https://api- docs.plextrac.com/#35efb6b8-22d3-4271-98fa-b9865d072461]endpoint. - 2.The fileUrl value should appear in the response. NOTE: If the file extension is not listed, it means the file was read as a byte stream, not as a file, and as such is not accessible (i.e. "uploads/0f645c65-ad95- 4a71-9c53-fb096442dfb8").
- 3.Add the HTML tag
<img src="/api/v1/{VALUE OF fileUrl FROM RESPONSE}">. For example:<img src="/api/v1/uploads/fee189cd-d7fa-46cd-962d-0cc5631099d6.jpg"> - 4.Create the JSON payload to generate a new finding and add this HTML tag to the description value.
- 5.Send the created JSON payload on the POST
Create Finding[https://api-docs.plextrac.com/#c7877845-5b51-40c9-ba50-931114aa0a30]request
Objective: Copy a finding from a report to the WriteupsDB repository.
Notes: This is currently done in the PlexTrac frontend with a deprecated endpoint,
POST /api/v2/repositories/copyFlawToWriteupsRepository. This endpoint has the same functionality as POST /api/v1/template/create, which should be used instead.Summary: In the platform, when viewing the finding list in a report, a writeup can be copied to a WriteupDB repository by clicking the metaballs menu in the finding row and clicking Copy to WriteupDB. This use case triggers a multi-step process to get the finding data and send it in a request to create a new writeup.
Steps:
- 1.Call the
GET/api/v1/client/{clientId}/report/{reportId}/flaw/{findingId}endpoint to get the finding JSON. - 2.Navigate into the WriteupsDB repository to copy the finding. Look at the page URL and copy down the CUID of the repository.
- 3.Add the key "repositoryId" and the value "" to the finding JSON (i.e., "repositoryId": "clgn7pad8046c28n27tbg8ue3").
- 4.Send the updated finding JSON as the payload in the
POST/api/v1/template/create endpoint.
Objective: Take an existing completed client assessment and create a new In Process assessment for another client.
Notes: The functionality to create a new In Process assessment for the same client exists within the platform, but this assessment cannot be created on a different client. However, this can be accomplished through the API with the GET Client Assessment and POST Create Client Assessment endpoints.
- 1.Identify the existing assessment to reuse.
- 2.Use the GET Client Assessment API on the completed client assessment. This will return the JSON of that assessment data including questions and answers.
- 3.Modify the JSON by removing the properties
tenant_id,client_id,assess_id, andcompleted_at. Change the value ofsaveOnlytotrue. - 4.Go through the list of answers and update the
notefield to be a non-empty string. - 5.Use the POST Create Client Assessment to create the new in process client assessment. Set the new
tenantIdandclientIdin the URL and send the modified JSON as the payload.
Last modified 18d ago