API DocumentationTemplatingService DeskPlexTrac Home
Search
⌃K
Links

Use Cases

This page describes how the API can be used to achieve a goal or objective and outline the steps involved in a scenario, the tasks or actions to be performed, and the expected results or outcomes.
The uses cases are set to a specific objective and outcome and intended as a template to leverage for all API needs.

Use Cases Groupings

The use cases are separated into three categories:
  1. 1.
    Introductory Use Cases: Objectives that are common for all PlexTrac users when getting started. These uses cases are relatively straight-forward.
  2. 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. 3.
    Advanced Use Cases: Objectives that are not available within the platform but are doable via API. Since certain platform functionality consists of making requests to multiple API endpoints, new functionality can be created by stringing together multiple 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. This means combining a GET request with saving the response to a JSON can create the functionality to export the data. By combining some data transformation to remove IDs and a POST request to create a new data object, data can be imported.
This page will be enhanced over time. If a use case is missing that needs to be added, reach out to the Service Desk and submit a request.

Introductory Use Cases

Generating Session Token Without MFA
Objective: Obtain a valid token and cookie for a session.
Notes: POST Authentication is the auth endpoint for a user without MFA.
  1. 1.
    Execute the POST Authentication API: {{instanceUrl}}/api/v1/authenticate by providing a valid instance url, user name and password in the parameters of the request.
  2. 2.
    If successful, the tennant_id, cookie, and token values will be returned.
  3. 3.
    Extract the session token from the response body.
  4. 4.
    Use the value in the token field as the required Bearer token sent to other endpoints.
The token is good for 15 minutes.
Retrieving List of Tenant Users
Objective: Obtain a list of all users for a tenancy.
Notes: GET Tenant Users is the endpoint for obtaining a list of tenant users.
  1. 1.
    Execute the GET Tenant Users API: {{instanceUrl}}/api/v2/tenants/{{tenantId}}/users by providing a valid instance url and tenant ID in the parameters of the request.
  2. 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.
    ​

Intermediate Use Cases

Adding Images to CKEditor Fields
Objective: Add images through the API that are rendered in platform and on export as a Microsoft Word document.
Notes: This functionality exists within the platform but accomplishing 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 field
Summary: 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 to create a new finding with an image in the description field:
  1. 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. 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. 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. 4.
    Create the JSON payload to generate a new finding and add this HTML tag to the description value.
  5. 5.
    Send the created JSON payload on the POST Create Finding[https://api-docs.plextrac.com/#c7877845-5b51-40c9-ba50-931114aa0a30] request

Advanced Use Cases

Reusing an Assessment
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. 1.
    Identify the existing assessment to reuse.
  2. 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. 3.
    Modify the JSON by removing the properties tenant_id, client_id, assess_id, and completed_at. Change the value of saveOnly to true.
  4. 4.
    Go through the list of answers and update the note field to be a non-empty string.
  5. 5.
    Use the POST Create Client Assessment to create the new in process client assessment. Set the new tenantId and clientId in the URL and send the modified JSON as the payload.
Previous
Endpoints List
Next
Sunsets and Deprecations
Last modified 16d ago
© 2022 PlexTrac, Inc. All rights reserved.