Jeremiah Strong

Senior Systems Administrator who enjoys PowerShell, Technology, and simplicity. I also like cookie dough. And milk.

4 minute read

The IRIS Practice Engine (PE) platform offers an API to create robust, custom solutions. Or, in my case, a method to automate receiving an email for unreleased time.
As my preferred scripting language of choice, I used PowerShell.

INFO: The following overview has an assumption that you have a familiarity with APIs. As such, the information may be incomplete due to this assumption.

Before You Begin

Before you can start, create an account to perform your API queries. The Staff Account needs permissions for any query that you are aiming to do. To begin and for testing, consider a full Admin account.

After Staff Account creation, go to the Admin > Task Pad > API Authentication Administration. Choose ‘Create New App Id’ and input the User Id of the User you created above. Then hit save. It will look like this:

Administer API Access

Reminder Be sure to hit save!

Authorization Header

In order to make a query, generate an authentication token. The PE API uses bearer tokens.

The token endpoint URL: https://contoso.pehosted.com/auth/connect/token
Be sure to change contoso for your site.

PE API version 9.6 and later uses the OpenID connect protocol.

PowerShell

To create the authorization header in PowerShell:

<#
.Synopsis
    Create the bearer token to use on Practice Engine API Rests requests (header)
.DESCRIPTION
    After creating your Application App ID and App Key, you can use this
    to create the authorization header for your Practice Engine API Requests.
.PARAMETER AppID
    The Application ID generated from Practice Engine that is tied to a Practice Engine user.
.PARAMETER AppKey
    The Application Key generated from Practice Engine that is tied to a Practice Engine user.
.PARAMETER BaseURL
    The base URL of your Practice Engine site. The submitted URL must be a valid URL, for example
    https://mysite.practiceenginehosted.com would pass validation.
.EXAMPLE
    C:\PS>$PEAuthHeader = Create-PEAuthorizationHeader -AppId 'd88f9b633f664d62b7c5126348f27dff' -AppKey 'WGGV0y3EiD9M/MZV12NbO/lYrE174u3M1yaV1jZf3lg=' -BaseURL 'https://mypesite.practiceenginehosted.com'

#>
function Create-PEAuthorizationHeader {

    [CmdletBinding()]
    param (

        # AppId The App ID generated from Practice Engine.
        [Parameter(Mandatory=$True)]
        [ValidateNotNullOrEmpty()]
        [string] $AppId,

        #AppKey The App Key (secret) generated from Practice Engine.
        [Parameter(Mandatory=$True)]
        [ValidateNotNullOrEmpty()]
        [string] $AppKey,

        #BaseURL The base URL of your Practice Engine hosted website
        [Parameter(Mandatory=$True)]
        [ValidatePattern("https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_\+.~#?&=]*)")]
        [string] $BaseURL

    )

    $AuthURL = $BaseURL + '/auth'

    $Response = Invoke-RestMethod -Uri ($AuthURL +'/.well-known/openid-configuration') -Method Get

    $TokenURL = $Response.token_endpoint

    $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $AppId,$AppKey)))

    $PayLoad = @{
        grant_type = 'client_credentials'
        scope = 'pe.api'
    }

    $AuthToken = Invoke-RestMethod -Uri $TokenURL -Method Post -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)} -Body $PayLoad

    #Output as Hashtable
    $BearerToken = @{
        'Authorization' = 'Bearer ' + $AuthToken.access_token
    }

    return $BearerToken

} # End Create-PEAuthorizationHeader

Power Query M

For the Power Query M formula language

let
    app_id = "<appid>",
    app_key = "<appkey>",

    serverurl = "https:/contoso.pehosted.com",

    token_uri = serverurl & "/auth/connect/token",

     BasicAuth = "Basic " & Binary.ToText(Text.ToBinary(app_id & ":" & app_key),0),

     GetTokenRequestJson = Web.Contents(token_uri,
        [
            Headers = [#"Authorization"=BasicAuth,
                       #"Content-Type"="application/x-www-form-urlencoded"
            ],
            Content = Text.ToBinary(Uri.BuildQueryString(
                [
                    grant_type = "client_credentials",
                    scope = "pe.api"
                ]
            ))
        ]
    ),

    FormatTokenRequestJson = Json.Document(GetTokenRequestJson),
    AccessToken = FormatTokenRequestJson[access_token],

    BearerTokenHeader = "Bearer " & AccessToken
in
    BearerTokenHeader

Python

Github User KennyKennedy can help us here.

import requests, json

servurl = 'https://contoso.pehosted.com'
appid = '<appid>'
appkey = '<appkey>'

tokenurl = servurl+'/auth/connect/token'

auth = (appid,appkey)
authtype = {'grant_type': 'client_credentials', 'scope': 'pe.api'}
resptoken = requests.post(tokenurl, data=authtype, auth=auth)
token = resptoken.json()['access_token']
apiheader = {'Authorization': 'Bearer ' + token}

Postman

Launch the Postman client. Create a new HTTP request with the POST command. The request URL: https://contoso.pehosted.com/auth/connect/token
Create three keys with the following values:

KEY VALUE
grant_type client_credentials
client_id app id
client_secret app key

It will look something like this:

Bearer token creation via Postman

The returned value, access_token, is for the authorization Headers in your API requests. It will be in format ‘Bearer access_token’

The Headers section will have the key/value entry:

KEY VALUE
Authorization Bearer access_token

And will look like the following:

Postman header value

Your First Query!

To get underway, the easiest example is to get details about the staff account you created.

This can be done from the authorization headers created in the previous section.

Remember to update contoso for your site.

PowerShell

$me = Invoke-RestMethod -Uri 'https://contoso.pehosted.com/pe/api/StaffMember/Me' -Method Get -Headers $authorizationheader

Power Query M

let
  peme_uri = "https://contoso.pehosted.com/PE/api/StaffMember/Me",
  GetPEJsonQuery = Web.Contents(peme_uri,
        [
            Headers = [#"Authorization"=BearerTokenHeader]
        ]
    ),
    FormatPEJsonQuery = Json.Document(GetPEJsonQuery)

in
    FormatPeJsonQuery

Python

from pprint import pprint
apiurl = 'https://contoso.pehosted.com/pe/api/StaffMember/Me'

respapi = requests.get(apiurl, headers=apiheader)
pprint(respapi.json())

Postman

The request URL: https://contoso.pehosted.com/pe/api/StaffMember/ME

Postman API query

The Second Query

To explore the vast number of queries you can do, you could checkout swagger.

With that said, I find it easiest and best to use a packet capture program while doing the actual actions in the PE site. I prefer Wireshark or Google Chrome DevTools. The best part about using this option is your query and response are captured. As such, you will know exactly the ideal payloads to use.

Helpful Resources Referenced

The Practice Engine API has a lot of helpful resources.

INFO: The Swagger documentation and API Help Page may take a moment to load as it builds dynamically. Remember to replace Contoso for your site.

At the time of this writing, the PE Github does not appear to accept Pull Requests so I did create a fork.
In a new repository, I added the following examples that are in this post:

Closing out

I hope this was helpful! I love automation. My Internal Accounting team appreciates the PE API. After all, it is the PE API that allows me to get email/text reminders for unreleased time in the format that I desire. To be honest, my workload would not be sustainable without APIs.

If you have public blog, Github, or code with your PE automations, please drop a comment. I enjoy seeing others work of art (err, I mean automations).

Cheers,
Jeremiah

Leave a comment

You may also enjoy