Interactive API¶

The Interactive API automates Epicor Prophet 21 as if a live user were operating the UI. Every business rule, validation, event, and lookup fires exactly as it would in the native PowerBuilder interface. This makes the Interactive API the correct choice whenever behavioral fidelity to the P21 application layer is required.

https://{your-server}/uiserver0/ui/interactive/v1/

Conceptual Overview¶

The Interactive API works by instantiating real P21 application windows on the server. The server maintains full window state between requests — open forms, current row positions, pending changes, and unsaved data all persist on the server for the lifetime of the session. The client drives the window by sending the same events a user would: opening a window, changing a field, clicking a tab, pressing a button.

Because the server is running the actual P21 application code, every consequence of a UI action also occurs through the API:

• Field-change events fire and may update other fields
• Lookups populate dependent fields (e.g., entering a customer ID fills ship-to, terms, credit limit)
• Validators run and return errors before a save is committed
• Business rules attached to windows, tabs, and fields all execute
• Required fields are enforced at save time

This is both the primary strength and primary performance cost of the Interactive API. For pure data throughput without business rule overhead, see the Entity API.

Operations Reference¶

POST /window — Open Window¶

Opens a P21 application window on the server. The window behaves exactly as if a user opened it from the P21 menu.

Request¶

Content-Type: application/xml

<WindowType xmlns="urn:epicor-com:p21:interactive:v1">
  <MenuId>OE-I-1</MenuId>
  <Name>Order Entry</Name>
  <ServiceName>oe_entry</ServiceName>
  <Title>Order Entry</Title>
</WindowType>

Response¶

Returns an OpenWindowResult object:

<OpenWindowResult>
  <WindowId>3fa85f64-5717-4562-b3fc-2c963f66afa6</WindowId>
  <Status>Ready</Status>
  <Events>
    <Event>
      <Name>WindowOpened</Name>
      <Timestamp>2026-03-12T14:22:01Z</Timestamp>
    </Event>
  </Events>
  <Messages />
  <DataWindows>
    <DataWindow name="d_oe_hdr">...</DataWindow>
    <DataWindow name="d_oe_line">...</DataWindow>
  </DataWindows>
</OpenWindowResult>

GET /window — Get Window State¶

Retrieves the full current state of an open window, including all datawindow data and window metadata.

Request¶

GET /window?id={windowId}

Response¶

Returns the complete window structure including all datawindows, field definitions, row data, and current status.

DELETE /window — Close Window¶

Closes the specified window and releases all server-side state for it. Always close windows when done to avoid resource leaks on the P21 application server.

Request¶

DELETE /window?id={windowId}

PUT /change — Send Field Changes¶

This is the most frequently called endpoint. It sends one or more field-value changes to P21 and returns the updated window state after all triggered events, lookups, and business rules have fired.

Request¶

Content-Type: application/xml

<ChangeRequest xmlns="urn:epicor-com:p21:interactive:v1">
  <WindowId>3fa85f64-5717-4562-b3fc-2c963f66afa6</WindowId>
  <Changes>
    <Change>
      <DataWindowName>d_oe_hdr</DataWindowName>
      <FieldName>customer_id</FieldName>
      <Value>C100001</Value>
      <Row>0</Row>
    </Change>
  </Changes>
</ChangeRequest>

Multiple Changes in One Request¶

You can batch multiple changes into a single ChangeRequest. They are processed in order. Each change's effects (lookups, events) complete before the next change is applied.

<ChangeRequest xmlns="urn:epicor-com:p21:interactive:v1">
  <WindowId>3fa85f64-5717-4562-b3fc-2c963f66afa6</WindowId>
  <Changes>
    <Change>
      <DataWindowName>d_oe_hdr</DataWindowName>
      <FieldName>customer_id</FieldName>
      <Value>C100001</Value>
      <Row>0</Row>
    </Change>
    <Change>
      <DataWindowName>d_oe_hdr</DataWindowName>
      <FieldName>ship_via</FieldName>
      <Value>UPS GND</Value>
      <Row>0</Row>
    </Change>
  </Changes>
</ChangeRequest>

Response¶

Returns a ChangeResult containing the full updated window state:

<ChangeResult>
  <WindowId>3fa85f64-5717-4562-b3fc-2c963f66afa6</WindowId>
  <Status>Ready</Status>
  <ChangedFields>
    <Field datawindow="d_oe_hdr" name="customer_name">Acme Corp</Field>
    <Field datawindow="d_oe_hdr" name="credit_limit">50000.00</Field>
    <Field datawindow="d_oe_hdr" name="terms_code">NET30</Field>
    <Field datawindow="d_oe_hdr" name="ship_via">UPS GND</Field>
  </ChangedFields>
  <Events>
    <Event name="CustomerLookup" />
    <Event name="TermsDefaulted" />
  </Events>
  <Messages />
  <Errors />
</ChangeResult>

POST /row — Add Row¶

Inserts a new blank row into a datawindow, equivalent to pressing the Insert key in a P21 grid.

Request¶

<RowRequest xmlns="urn:epicor-com:p21:interactive:v1">
  <WindowId>3fa85f64-5717-4562-b3fc-2c963f66afa6</WindowId>
  <DataWindowName>d_oe_line</DataWindowName>
</RowRequest>

Response¶

Returns the new row index and any default values P21 populated.

POST /row/data — Add Row With Data¶

Inserts a new row and immediately populates fields in a single call. More efficient than POST /row followed by PUT /change when you know all field values upfront.

Request¶

<RowDataRequest xmlns="urn:epicor-com:p21:interactive:v1">
  <WindowId>3fa85f64-5717-4562-b3fc-2c963f66afa6</WindowId>
  <DataWindowName>d_oe_line</DataWindowName>
  <Fields>
    <Field name="item_id">WIDGET-001</Field>
    <Field name="unit_quantity">10</Field>
  </Fields>
</RowDataRequest>

PUT /data — Save¶

Saves all pending changes on the current window. Equivalent to clicking the Save (floppy disk) toolbar button.

Request¶

<SaveRequest xmlns="urn:epicor-com:p21:interactive:v1">
  <WindowId>3fa85f64-5717-4562-b3fc-2c963f66afa6</WindowId>
</SaveRequest>

Response¶

On success, returns the saved record's key (e.g., the new order number). On validation failure, returns an Errors collection with the validation messages that prevented the save.

<SaveResult>
  <Status>Saved</Status>
  <KeyValue>SO-0045892</KeyValue>
  <Errors />
</SaveResult>

PUT /tab — Switch Tab¶

Switches the active tab on the window. Tab names are PowerBuilder tab control names (e.g., tab_line_items, tab_notes, tab_header).

Request¶

<TabRequest xmlns="urn:epicor-com:p21:interactive:v1">
  <WindowId>3fa85f64-5717-4562-b3fc-2c963f66afa6</WindowId>
  <TabName>tab_line_items</TabName>
</TabRequest>

GET /tools and POST /tools — Toolbar Actions¶

GET /tools returns the list of available toolbar buttons for the current window. POST /tools executes one.

Execute a Tool¶

<ToolRequest xmlns="urn:epicor-com:p21:interactive:v1">
  <WindowId>3fa85f64-5717-4562-b3fc-2c963f66afa6</WindowId>
  <ToolName>post</ToolName>
</ToolRequest>

Common tool names include post, print, copy, delete, search. Actual available tools depend on the window.

GET /values — Valid Values¶

Returns the list of valid values for a dropdown or code-restricted field. Useful for building UI pickers or validating input before sending changes.

Request¶

GET /values?windowId={windowId}&datawindow={dwName}&field={fieldName}

Response¶

<Values>
  <Value code="UPS GND" description="UPS Ground" />
  <Value code="UPS 2DA" description="UPS 2nd Day Air" />
  <Value code="FEDEX" description="FedEx Priority Overnight" />
</Values>

Complete Workflow: Create a Sales Order¶

The following pseudocode illustrates a complete order entry session. Error handling is omitted for brevity.

# Step 1: Establish session (Common Services)
session = POST /common/session { username, password, company }

# Step 2: Open the Order Entry window
result = POST /window { MenuId: "OE-I-1" }
window_id = result.WindowId

# Step 3: Enter the customer — triggers customer lookup
#         P21 will populate: customer_name, terms, ship_via, tax_code,
#         ship_to addresses, credit_limit, and more.
POST /change {
  window_id,
  datawindow: "d_oe_hdr",
  field: "customer_id",
  value: "C100001"
}

# Step 4: Override the ship via if needed
POST /change {
  window_id,
  datawindow: "d_oe_hdr",
  field: "ship_via",
  value: "FEDEX"
}

# Step 5: Switch to the line items tab
PUT /tab { window_id, tab: "tab_line_items" }

# Step 6: Add a new order line
POST /row { window_id, datawindow: "d_oe_line" }

# Step 7: Enter item ID — triggers item lookup
#         P21 will populate: description, unit_of_measure, unit_price,
#         available_qty, lead_time, and more.
POST /change {
  window_id,
  datawindow: "d_oe_line",
  field: "item_id",
  value: "WIDGET-001"
}

# Step 8: Set quantity
POST /change {
  window_id,
  datawindow: "d_oe_line",
  field: "unit_quantity",
  value: "10"
}

# Step 9: Save the order
#         Returns the new order number (e.g., SO-0045892)
result = PUT /data { window_id }
order_no = result.KeyValue

# Step 10: Close the window and release server resources
DELETE /window { window_id }

Key Concepts and Gotchas¶

Window State Is Server-Side¶

The Interactive API is fundamentally stateful. The P21 application window lives on the server between API calls. This means:

• You must DELETE /window when done, even on error paths
• You cannot share a WindowId across threads
• Session timeouts will invalidate open windows
• High concurrency requires one window instance per concurrent operation

DataWindow Names¶

Field changes target a specific DataWindow — a PowerBuilder data control that maps to one or more database tables. Common DataWindow names:

Use P21's PowerBuilder source (if available) or the Transaction API service explorer to discover DataWindow names.

Field Names Are Database Column Names¶

Field names in the Interactive API are the actual P21 database column names, written in snake_case. They match the columns in the SQL Server tables exactly. When in doubt, check the sys.columns view in the P21 database.

Change Order Matters¶

When sending multiple changes, order is significant. If item_id must be set before unit_quantity (so the item lookup can validate the quantity against pack sizes), send them in that order — either as sequenced <Change> elements in a single request or as sequential calls.

Interactive API vs. Entity API¶

Error Handling¶