Epicor Service Connect: Workflow and Integration Engine Capabilities

TL;DR

• Bottom line: Epicor Service Connect (ESC) is a middleware integration engine that uses visual workflow orchestration to connect Epicor Kinetic with external systems via XML-based message processing, .NET assemblies, web services, and multiple input/output channels (FTP, email, file drop, MSMQ, COM). [src1]
• Key limit: No built-in API rate limiting -- throttling must be configured at the IIS or reverse proxy level. ESC requires a separate license beyond base Epicor Kinetic. [src5]
• Watch out for: Always use a dedicated Service Connect user account that never logs in interactively -- sharing accounts causes session context issues (plant, company context switching mid-workflow). [src3]
• Best for: Multi-step data transformations between Epicor and external systems, scheduled file imports (CSV/Excel/XML), and BPM-triggered outbound integrations. [src1, src2]
• Authentication: REST API supports Basic Auth and OAuth 2.0 (ROPC). Service Connect uses Epicor session credentials for .NET Reference calls. API Key auth available on REST v2 only. [src4]

System Profile

Epicor Service Connect (ESC) is the built-in integration middleware for Epicor Kinetic (formerly Epicor ERP 10). It provides a visual Workflow Designer for building data transformation and orchestration flows without extensive custom code. ESC operates as a Windows service and processes messages through configurable input/output channels. Available for on-premise and hybrid deployments; cloud SaaS deployments may have restricted ESC access. As of Kinetic 2023.2, Epicor also offers Data Fabric (Kafka-based) as a cloud-native alternative. [src1, src2]

API Surfaces & Capabilities

ESC interacts with Epicor and external systems through multiple API surfaces. The primary method is .NET Reference calls to Epicor business objects within ESC workflows, while REST and SOAP APIs provide alternative access paths for external integrations. [src1, src4]

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Authentication

Authentication Gotchas

• Dedicated ESC user account is mandatory: Shared accounts cause plant/company context switching mid-workflow when the interactive user changes contexts. [src3]
• API Key requires REST v2: Not available on REST API v1. Instances on v1 must use Basic Auth or OAuth ROPC. [src4]
• OAuth ROPC stores credentials: Unlike modern client credentials flows, Epicor's OAuth uses resource owner password grant, meaning the integration must store username/password. [src4]

Constraints

• Service Connect requires a separate license -- not included in base Epicor Kinetic. Cost varies by deployment and concurrent workflow count. [src1]
• No built-in API rate limiting -- must implement via IIS Dynamic IP Restrictions or reverse proxy. Misbehaving integrations can overwhelm the Epicor server. [src5]
• ESC is Windows-only -- runs as Windows service (EpicorServiceConnect.exe). Cannot run on Linux or in containers. [src1]
• XML is the internal message format -- non-XML inputs require conversion maps, adding complexity. [src2]
• Synchronous execution by default -- long operations can block ESC thread pool. [src2]
• BPM-to-ESC coupling is version-dependent -- BO schema changes during upgrades can break workflow mappings. [src2, src7]

Integration Pattern Decision Tree

START -- Integrate with Epicor Kinetic
|-- What is the integration surface?
|   |-- Service Connect (ESC) workflow orchestration
|   |   |-- Data source format?
|   |   |   |-- XML --> Direct input channel (File, FTP, MSMQ, Web Service)
|   |   |   |-- CSV/Excel/Fixed-width --> Conversion Map + File channel
|   |   |   |-- Database --> dbLookup functoid within workflow
|   |   |   |-- Epicor BO call --> .NET Reference activity
|   |   |-- Integration trigger?
|   |   |   |-- Scheduled --> File channel with folder polling
|   |   |   |-- Event-driven --> BPM directive triggers ESC workflow
|   |   |   |-- On-demand --> Expose workflow as Web Service endpoint
|   |   |   |-- Queue-based --> MSMQ channel for reliable delivery
|   |   |-- Error handling approach?
|   |       |-- Simple notification --> Choice + Poster (email) [src3]
|   |       |-- UD table logging --> Choice + UpdateExt to UD table [src3]
|   |       |-- Full reprocessing --> Log all fields to UD + errors [src3]
|   |-- Direct REST API (bypass ESC)
|   |   |-- Volume < 1,000 records/day --> REST API v2 + Basic Auth/API Key
|   |   |-- Volume > 1,000 records/day --> REST API v2 + batch + IIS throttle
|   |   |-- Real-time notifications --> BPM + Epicor Functions + REST callout
|   |-- Epicor Data Fabric (Kinetic 2023.2+)
|       |-- Cloud-native event streaming --> Apache Kafka via Confluent Cloud
|       |-- High-volume real-time CDC --> Data Fabric preferred over ESC

Quick Reference

Step-by-Step Integration Guide

1. Set up dedicated Service Connect user

Create a dedicated Epicor user for ESC that will never be used for interactive logins. Assign appropriate security groups. [src3]

Epicor Admin steps:
1. Go to System Setup > Security Maintenance > User Account Maintenance
2. Create user: "ESC_SvcAcct" with strong password
3. Assign to security groups covering required BO access
4. Set default plant, company, and site context
5. NEVER log in interactively with this account
6. Configure ESC service to use these credentials

Verify: Log in to ESC Administration Console and confirm the service account can connect to the Epicor application server.

2. Create a workflow package and input channel

Open the Workflow Designer, create a new Workflow Package, then configure an input channel for your data source. [src2]

Workflow Designer steps:
1. Right-click Workflow Packages > New Package > name: "SalesOrderImport"
2. Right-click package > New Workflow > name: "ImportSalesOrders"
3. Configure Input Channel:
   - Type: File Drop
   - Path: \\server\share\incoming\sales_orders\
   - File Pattern: *.xml (or *.csv with conversion map)
   - Polling Interval: 60 seconds
4. If CSV: Add Conversion Map activity to convert CSV to XML

Verify: Drop a test file in the monitored folder and confirm ESC picks it up via Workflow Monitor.

3. Add .NET Reference activities for BO calls

Drag .NET Reference activities onto the workflow canvas. Browse to target Epicor business objects and map fields via XML Mapper. [src2, src4]

.NET Reference configuration:
1. Drag ".NET Reference" activity to workflow canvas
2. Browse Assembly: Erp.Contracts.BO.SalesOrder.dll
3. Select Method: GetNewOrderHed
4. Open XML Mapper: drag source XML fields to target BO dataset fields
5. Add second .NET Reference: SalesOrderSvc.Update
6. Map all required fields (CustNum, OrderDate, OrderLines, etc.)

Verify: Right-click the .NET Reference activity > Test with sample data. Check Epicor for created records.

4. Implement error handling with Choice elements

After every .NET Reference call, add a Choice element to check for errors. Branch to error handling (email, UD table, or both). [src3]

Error handling pattern:
1. After each .NET Reference, add Choice element
2. Condition: Check callContext.ExceptionMessage != ""
   - TRUE branch: Error occurred
     - Option A: Poster (email to admin) -- simplest
     - Option B: .NET Reference to UD table (UpdateExt) -- queryable audit trail
     - Option C: Log all input fields + error details -- enables re-run
   - FALSE branch: Continue to next step

Verify: Send malformed data deliberately. Confirm error notification received and/or UD table entry created.

Code Examples

Python: Query Epicor via REST API v2

# Input:  Epicor server URL, credentials, business object name
# Output: JSON array of records from Epicor

import requests
from requests.auth import HTTPBasicAuth

server = "https://epicor-server/ERP_Instance"
username = "ESC_SvcAcct"
password = "YourSecurePassword"

url = f"{server}/api/v2/odata/Erp.BO.SalesOrderSvc/SalesOrderHeds"
params = {
    "$filter": "OrderHeld eq false",
    "$select": "OrderNum,CustNum,OrderDate,OrderTotal",
    "$top": 50,
    "$orderby": "OrderDate desc"
}

response = requests.get(
    url, params=params,
    auth=HTTPBasicAuth(username, password),
    headers={"Accept": "application/json"}
)

if response.status_code == 200:
    data = response.json()
    for order in data.get("value", []):
        print(f"Order {order['OrderNum']}: ${order['OrderTotal']}")
elif response.status_code == 401:
    print("Authentication failed - check credentials")
else:
    print(f"Error {response.status_code}: {response.text}")

JavaScript/Node.js: Create a Sales Order via REST API v2

// Input:  Epicor server URL, credentials, customer number
// Output: Created sales order number

const fetch = require("node-fetch"); // npm install node-fetch@2
const server = "https://epicor-server/ERP_Instance";
const credentials = Buffer.from("username:password").toString("base64");

async function createSalesOrder(custNum) {
  const getNewResp = await fetch(
    `${server}/api/v2/odata/Erp.BO.SalesOrderSvc/GetNewOrderHed`,
    {
      method: "POST",
      headers: {
        Authorization: `Basic ${credentials}`,
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({ ds: {} }),
    }
  );
  if (!getNewResp.ok) throw new Error(`GetNewOrderHed: ${getNewResp.status}`);

  const ds = await getNewResp.json();
  ds.parameters.ds.OrderHed[0].CustNum = custNum;

  const updateResp = await fetch(
    `${server}/api/v2/odata/Erp.BO.SalesOrderSvc/Update`,
    {
      method: "POST",
      headers: {
        Authorization: `Basic ${credentials}`,
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({ ds: ds.parameters.ds }),
    }
  );
  if (!updateResp.ok) throw new Error(`Update: ${updateResp.status}`);

  const result = await updateResp.json();
  console.log("Created Order:", result.parameters.ds.OrderHed[0].OrderNum);
}
createSalesOrder(1234).catch(console.error);

cURL: Quick REST API test

# Input:  Epicor server URL, credentials
# Output: JSON response from business object query

# Test Basic Auth connectivity
curl -s -X GET \
  "https://epicor-server/ERP_Instance/api/v2/odata/Erp.BO.SalesOrderSvc/SalesOrderHeds?\$top=5" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Accept: application/json" | jq .

# Test OAuth token acquisition
curl -s -X POST \
  "https://epicor-server/ERP_Instance/Token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=ESC_SvcAcct&password=YourPassword" | jq .

Data Mapping

Field Mapping Reference

Data Type Gotchas

• DateTime format differs between REST and ESC XML: REST API v2 uses ISO 8601; ESC .NET Reference uses .NET DateTime serialization. Mismatches cause dates to default to 1900-01-01. [src4]
• Decimal precision is UOM-dependent: Sending 1.5 for an integer UOM ("Each") causes validation errors. Always check UOM decimal places. [src4]
• Company/Plant context affects all BO calls: Every .NET Reference executes in the configured user's context. Shared accounts cause wrong-plant data writes. [src3]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Epicor upgrade breaks ESC XML mappings: BO datasets gain new required fields during upgrades; existing workflows fail with "null property" errors. Fix: Export all workflow XML mappings before upgrade. Compare BO schemas and update mappings for new required fields. Test every workflow in pilot. [src7]
• Shared service account causes cross-plant data corruption: Interactive user switching plants changes ESC session context. Fix: Create a dedicated, never-interactive ESC service account with locked plant/company. [src3]
• Large CSV imports cause OutOfMemoryException: ESC loads entire files into memory for XML conversion. Fix: Split large files into 10,000-20,000 record chunks before dropping into ESC monitored folder. [src2]
• ESC thread pool exhaustion blocks all workflows: Long-running workflows consume all available threads. Fix: Monitor thread pool usage. Set max concurrent workflows in ESC admin. Break long workflows into sub-workflows. [src2]
• OAuth tokens expire mid-batch: Default ~20 min lifetime; long batches fail partway through. Fix: Check token expiry before each batch. Implement token refresh logic. [src4]

Anti-Patterns

Wrong: No error handling after .NET Reference calls

<!-- BAD - no error check; failures are silent -->
<NetReference assembly="SalesOrderSvc" method="Update" />
<NetReference assembly="SalesOrderSvc" method="GetByID" />
<!-- If Update fails, GetByID runs on stale data -->

Correct: Choice element after every .NET Reference

<!-- GOOD - error check after every BO call -->
<NetReference assembly="SalesOrderSvc" method="Update" />
<Choice condition="callContext.ExceptionMessage != ''">
  <True>
    <Poster type="email" to="[email protected]"
            subject="ESC Error: SalesOrder Update failed"
            body="{callContext.ExceptionMessage}" />
    <Stop />
  </True>
  <False>
    <NetReference assembly="SalesOrderSvc" method="GetByID" />
  </False>
</Choice>

Wrong: Using interactive user account for ESC

// BAD - ESC runs as "JSmith" who also uses Epicor desktop client
// When JSmith switches to Plant B, ESC writes data to Plant B instead of Plant A
Service Account: JSmith (also logs in interactively)

Correct: Dedicated non-interactive service account

// GOOD - dedicated account with locked context
Service Account: ESC_SvcAcct
  - Never used for interactive login
  - Default Plant: Plant A (locked)
  - Default Company: Company01 (locked)
  - Security: Only BO permissions needed for workflows

Wrong: Loading entire large file in single ESC workflow

// BAD - 500,000-row CSV into ESC file channel
// ESC converts entire file to XML in memory -> OutOfMemoryException
Input: customers_full_export.csv (500,000 rows, 200 MB)

Correct: Pre-split files into manageable chunks

# GOOD - split large file into 10,000-row chunks
split -l 10000 --additional-suffix=.csv customers_full_export.csv chunk_
for f in chunk_*.csv; do
    cp "$f" /epicor/esc/incoming/
    sleep 30  # Allow ESC to process each chunk
done

Common Pitfalls

• Not testing workflows after Epicor upgrades: Even minor version bumps introduce new required fields that break XML mappings. Fix: Run every ESC workflow against the upgraded pilot environment before go-live. [src7]
• Ignoring ESC Workflow Monitor logs: Failures accumulate silently. Fix: Set up daily checks of Workflow Monitor. Configure email alerts for failed workflows. [src1]
• Hardcoding server paths in file channels: Absolute paths break during server migration. Fix: Use UNC paths and configure them as ESC parameters. [src2]
• Not implementing idempotency: Reprocessing a failed file creates duplicate records. Fix: Check for existing records via GetByID or GetList before creating. Use external reference IDs as unique keys. [src3]
• Skipping Conversion Map for CSV files: CSV directly in ESC workflows causes parsing errors. Fix: Always add a Conversion Map as the first activity for non-XML inputs. [src2]
• Over-relying on ESC for high-volume real-time: ESC is optimized for batch, not >1,000 TPS. Fix: Use REST API v2 directly with queuing for high-volume real-time. Reserve ESC for orchestrated multi-step flows. [src5, src6]

Diagnostic Commands

# Check ESC Windows service status
sc query "EpicorServiceConnect" | findstr STATE

# View ESC service logs (Windows Event Viewer)
wevtutil qe Application /q:"*[System[Provider[@Name='EpicorServiceConnect']]]" /c:20 /f:text

# Test REST API connectivity and authentication
curl -s -X GET \
  "https://epicor-server/ERP_Instance/api/v2/odata/Ice.BO.UserFileSvc/UserFiles?\$top=1" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -H "Accept: application/json" | jq .

# Check IIS AppPool status
%systemroot%\system32\inetsrv\appcmd.exe list apppool "EpicorAppPool" /text:state

# Monitor IIS worker process memory
tasklist /fi "imagename eq w3wp.exe" /v

# Check MSMQ queue depth (if using MSMQ channel)
powershell "Get-MsmqQueue -Name 'EpicorESC*' | Select QueueName, MessageCount"

Version History & Compatibility

Deprecation Policy

Epicor follows a rolling support model: current release and two prior releases are actively supported. Service Connect continues in Kinetic, though Data Fabric (2023.2+) represents the strategic direction for cloud-native integrations. No announced deprecation date for Service Connect. [src1]

When to Use / When Not to Use

Important Caveats

• Service Connect is a mature but aging technology. Epicor's strategic direction for cloud-native integration is Data Fabric (Apache Kafka), introduced in Kinetic 2023.2. Evaluate Data Fabric before committing to ESC for new cloud/SaaS projects. [src1]
• ESC documentation is primarily on EpicWeb (requires active support contract). Public documentation is limited compared to competing ERP platforms. [src2]
• Rate limiting and performance tuning are entirely the customer's responsibility. Unlike Salesforce or D365, Epicor has no platform-enforced limits. [src5]
• Cloud SaaS deployments may have restricted or no access to Service Connect. Verify ESC availability before planning integrations on SaaS. [src1]
• Confidence score (0.78) reflects limited public documentation. Verify critical limits against your specific Epicor version via EpicWeb.