Beta

Sessions and Workflows

Stage your data, start a workflow against it, and find out when the result is ready.

Two surfaces do this work. A session holds the data a product runs against: you stage it, and you can re-stage it as often as you like without starting anything. A workflow is one run of a product against that data: it reads what the session holds, runs the product, and produces a result. Staging is free. Starting a workflow is billed, unless your product uses outcome-based billing, where what became of the application decides.

The whole loop
What you need from PPS
Where to go next

The whole loop

You do three things: start a workflow, wait for PPS to tell you a result is ready, then read it.

sequenceDiagram
    autonumber
    participant You
    participant PPS
    participant Endpoint as Your endpoint
    You->>PPS: POST /v1/sessions/{id}/workflows
    PPS-->>You: 202 workflowId
    Note over PPS: the product runs
    PPS->>Endpoint: workflow.updated, data.status "ready"
    You->>PPS: GET /v1/findings/workflows/{workflowId}/findings
    PPS-->>You: the findings

No event fires when you start a workflow. The delivery arrives later, when there is something to read.

What you need from PPS

Most of these come from a person and can take days, so ask before you write any code.

A PPS access token. See Obtaining An Access Token.
Your org unit GUID, a string like OU41502, which your PPS account manager supplies. You need it to register a webhook endpoint.
An authorized destination domain. PPS must authorize the domain your endpoint lives on before it will send anything there; ask your PPS account manager.
The service and model values your account can start workflows for, which your PPS account manager also supplies, because no endpoint lists them.
For outcome-based billing only: your product set up to take outcome reports, and the permission to report granted to your integration system’s credential. See Reporting Outcomes.

Where to go next

Getting Started — authenticate, stage your data, start a workflow and read its result, step by step.
Failures and Reconfirms — what to do when a run fails, how to run a workflow again, and how to find a lost one.
Reporting Outcomes — tell PPS what became of each application, for products billed on outcomes.
Error Handling — the two error shapes, how to branch on them, and limits worth knowing.
Retrying Safely — retry a call that timed out without doing the work twice.
Session API Reference and Workflow API Reference — every operation, field and response.

Sessions and Workflows

The whole loop

What you need from PPS

Where to go next

Table of contents