Adaptiva API Foundry - A practical example

Overview

This example shows you how to implement a REST API endpoint on your Adaptiva server to collect and view client information. You will import the workflow that implements the GET method for the API and then test the ability to retrieve client information via REST invocation.

Requirements

This solution runs on all versions of Adaptiva.

Download Workflow

This solution uses a custom workflow and PowerShell scripts which you will need to download to your server.

• Workflow_GetAdaptivaClientInfo.obex

• JWT_TestingScripts.zip

The included PowerShell scripts are only needed if you are using a self-signed certificate.

Import Workflow

Follow the instructions in the Import a Workflow article to import the workflow and resolve any issues.

By default, it will import into a folder named: My Rest API Workflows. 

Review the workflow

1. Open the Adaptiva Admin Portal and log in as a Super Admin.

2. In the left-hand navigation, expand Platform Features and click Workflows > Designer.

3. In the Workflow Designer navigation tree, click My Rest API Workflows and then in the details pane select GetAdaptivaClientInfo.

The workflow is running a simple query:

select
Device_ID as ClientID,
Device_Name as ClientName,
IP_address as IPAddress,
[Last_Check-in] as LastCheckIn
from a_AdaptivaClientDetails order by Device_Name

There is also an option to specify a specific computer name, which will modify the query to:

from a_AdaptivaClientDetails where Device_Name like '%" + Params.Output + "%' order by Device_ID"

The key to the workflow is the following:

• The results are returned in JSON format and added to the End1.ResultText field
• End1.ResultWholeNumber returns 200
• End1.ResultArrayOfText returns a single-entry array with the value [Content-Type: application/json]

Create a Certificate (PEM format) to be used for accessing the REST API Endpoint

Option 1: Issue a certificate from your CA

If you want to use a CA-based certificate, request a Client Authentication certificate.

The certificate will usually be provided as a .pfx file, which you will need to convert to a .pem file. You can use the directions in the CA Requirements | Adaptiva Docs documentation to use openssl to convert your .pfx file.

Option 2: Use a self-signed certificate in a lab environment

In a lab environment, you can use the provided PowerShell scripts to create a self-signed certificate and JWT authentication token to secure the REST API communication.

1. Extract the JWT_TestingScripts.zip file to a working directory.
2. Use the following PowerShell script to create a self-signed certificate as well as the needed JWT.

.\CreateJWTcert_v1.ps1 -Subject "CN=JwtSigningCertScriptTest" -Password "ThisShouldbeAFancyLongPassword" -ExportLocation .\CertFiles -Length 730

Navigate to the CertFiles folder in the local directory to find the jwt-public.pem and jwt-signing.pfx files generated.

Create the authorization token that will be used with the GET request

1. You can generate an authorization token from the .pfx file using the CreateJWTfromCert_v1.ps1 (for PowerShell v5) or CreateJWTfromCert_PSv7_v1.ps1 (for PowerShell v7). 
2. Run the following command to generate a new authorization token:

.\CreateJWTfromCert_v1.ps1 -PFXLocation $(Resolve-Path .\CertFiles\jwt-signing.pfx) -Pass "ThisShouldbeAFancyLongPassword" -Expire 10

3. Copy the token to notepad and make sure it is all a single line
4. Save the token for use later

Configure the Server to support REST API requests

1. Log in to the Adaptiva Admin Portal as a Super Admin.
2. Click the gear in the top right and click Settings > REST API Endpoints > Configuration.
3. Toggle REST Server Enabled ON.
4. Check the box for Allow RSA-256.
5. Copy the contents of the certificate (jwt-public.pem) to the Certificate box.
6. Click Save.

Create the REST API Endpoint

1. In the left-hand navigation, click Endpoints under REST API Endpoints.
2. Click New.
3. Enter the following information:

• Name: Client Info
• Description: REST API endpoint for client information
• REST API Endpoint Path: clientinfo
• Authentication Type: JWT
• Use Global JWT Settings: Toggled ON
• In the HTTP Methods section, next to GET, click Browse.
• In the left-hand navigation, click My Rest API Workflows, select GetAdaptivaClientInfo, click OK.

4. Click Save.

Test the request using Postman

1. Open Postman on a client machine with network access to the Adaptiva server.
2. Create a New Request.
3. Select GET and enter the URL: https://<yourAdaptivaServerFQDN:[port]>/restapifoundry/clientinfo
4. Click Authorization.
5. Select the Auth Type as Bearer Token.
6. Copy and paste the token into the field (be sure it is a single line).
7. Click Send.
8. In the returned Body be sure to change the output type to JSON.
9. The information returned will look like:

{
    "columnNames": [
        "ClientID",
        "ClientName",
        "IPAddress",
        "LastCheckIn"
    ],
    "rows": [
        [
            44,
            "pc1-2",
            "172.99.15.11",
            1776873608607
        ],
        [
            74,
            "pc1",
            "172.99.14.21",
            1776873626480
        ]
    ]
}

10. You can also supply a parameter to the GET request if you want to return info about a single device or devices that match a name:

clientinfo?client=<devicename>

• For example:

https://adaptiva.kaibab.forest.lab:9678/restapifoundry/clientinfo?client=pc1

If there are multiple devices that start with pc1, then all will be returned. If the name entered does not match any name in Adaptiva then the following is returned:

{
    "columnNames": [
        "ClientID",
        "ClientName",
        "IPAddress",
        "LastCheckIn"
    ],
    "rows": [
        "pc9",
        "No Records Found Matching this Device Name",
        0,
        null
    ]
}