---
# === IDENTITY ===
id: business/erp-integration/epicor-service-connect/2026
canonical_question: "What are the Epicor Service Connect workflow and integration engine capabilities?"
aliases:
  - "How does Epicor Service Connect handle workflow orchestration and data integration"
  - "Epicor ESC workflow designer adapters channels and BPM integration"
  - "What are Epicor Service Connect input channels data formats and .NET reference capabilities"
  - "How to build integrations with Epicor Service Connect workflow engine"
entity_type: erp_integration
domain: business > erp-integration > epicor-service-connect
region: global
jurisdiction: global
temporal_scope: 2022-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Epicor Kinetic (Service Connect)"
    vendor: "Epicor"
    version: "Kinetic 2024.x (Service Connect 10.2.x)"
    edition: "All editions with Service Connect license"
    deployment: "hybrid"
    api_surface: "SOAP, REST, .NET Assemblies, XML"

# === VERIFICATION ===
last_verified: 2026-03-02
confidence: 0.78
version: 1.0
first_published: 2026-03-02

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: evolving
  last_breaking_change: "2021 - Epicor ERP 10 rebranded to Kinetic; REST API v2 introduced"
  next_review: 2026-08-29
  change_sensitivity: high

# === CONSTRAINTS ===
constraints:
  - "Service Connect requires a separate license - it is not included in base Epicor Kinetic"
  - "No built-in REST API rate limiting in Epicor - must configure via IIS or reverse proxy"
  - "Service Connect runs as a Windows service - cloud SaaS deployments may have restricted access to ESC"
  - "Workflows execute synchronously by default - long-running processes can block the Service Connect service"
  - "Dedicated Service Connect user account required - sharing with interactive users causes session context issues"
  - "XML is the native internal message format - non-XML inputs (CSV, Excel) require conversion steps"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "User needs Epicor Kinetic REST API direct integration without workflow orchestration"
    use_instead: "business/erp-integration/epicor-kinetic-rest-api/2026"
  - condition: "User needs Epicor BPM customization without external integration"
    use_instead: "business/erp-integration/epicor-bpm-customization/2026"
  - condition: "User needs Epicor Data Fabric (Kafka-based cloud integration)"
    use_instead: "business/erp-integration/epicor-data-fabric/2026"

# === AGENT HINTS ===
inputs_needed:
  - key: integration_pattern
    question: "What integration pattern do you need?"
    type: choice
    options:
      - "real-time sync (individual records, <1s latency)"
      - "batch/bulk (scheduled, high volume)"
      - "event-driven (BPM-triggered workflows)"
      - "file-based (CSV/XML import/export)"
  - key: data_volume
    question: "What's your daily data volume?"
    type: choice
    options:
      - "< 1,000 records/day"
      - "1,000-100,000 records/day"
      - "> 100,000 records/day"
  - key: direction
    question: "What's the data flow direction?"
    type: choice
    options:
      - "inbound (writing to Epicor)"
      - "outbound (reading from Epicor)"
      - "bidirectional sync"

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/business/erp-integration/epicor-service-connect/2026"
suggested_citation: "Source: knowledgelib.io - AI Knowledge Library (verified 2026-03-02)"

# === RELATED UNITS ===
related_kos:
  depends_on: []
  related_to:
    - id: "business/erp-integration/epicor-kinetic-rest-api/2026"
      label: "Epicor Kinetic REST API v2 capabilities and endpoints"
  solves:
    - id: "business/erp-integration/epicor-ecommerce-integration/2026"
      label: "Epicor eCommerce integration playbook using Service Connect"
  alternative_to:
    - id: "business/erp-integration/epicor-data-fabric/2026"
      label: "Epicor Data Fabric (Kafka-based cloud-native integration, Kinetic 2023.2+)"
  often_confused_with:
    - id: "business/erp-integration/epicor-bpm-customization/2026"
      label: "Epicor BPM (in-app business logic, not the same as ESC workflow orchestration)"

# === SOURCES ===
sources:
  - id: src1
    title: "Epicor Service Connect Product Page"
    author: Epicor
    url: https://www.epicor.com/en-us/products/supply-chain-management-scm/service-connect/
    type: official_docs
    published: 2025-01-15
    reliability: authoritative
  - id: src2
    title: "Epicor Service Connect Workflow Designer"
    author: Tomerlin-ERP
    url: https://tomerlin-erp.com/service-connect/
    type: technical_blog
    published: 2025-06-10
    reliability: moderate_high
  - id: src3
    title: "When thinking Epicor ERP interfaces, think error handling"
    author: Clear Business Outcome
    url: https://clearbusinessoutcome.com/thinking-epicor-erp-interfaces-think-error-handling/
    type: technical_blog
    published: 2024-09-15
    reliability: moderate_high
  - id: src4
    title: "DIY Developer Guide: Building Custom Integrations for Epicor"
    author: APIWorx
    url: https://apiworx.com/diy-developer-guide-building-custom-integrations-for-epicor/
    type: technical_blog
    published: 2025-03-20
    reliability: moderate_high
  - id: src5
    title: "Epicor REST API Rate Limiting Discussion"
    author: Epicor User Help Forum
    url: https://www.epiusers.help/t/epicor-rest-api-rate-limiting/51801
    type: community_resource
    published: 2024-07-12
    reliability: moderate
  - id: src6
    title: "Using Epicor BPMs to Trigger External Integrations"
    author: Epicforce Tech
    url: https://epicforcetech.com/using-epicor-bpms-to-trigger-external-integrations-without-full-customization/
    type: technical_blog
    published: 2025-05-18
    reliability: moderate_high
  - id: src7
    title: "Troubleshooting Service Connect"
    author: Epicor User Help Forum
    url: https://www.epiusers.help/t/troubleshooting-service-connect/53018
    type: community_resource
    published: 2024-06-20
    reliability: moderate
---

# 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 that need error handling and audit logging. [src1, src2]
- **Authentication**: Epicor REST API supports Basic Auth (base64 username:password) and OAuth 2.0 (resource owner password grant via /Token endpoint). Service Connect itself uses Epicor session credentials for .NET Reference calls. [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. It is available for both on-premise and hybrid deployments, though cloud SaaS deployments may have restricted direct ESC access. ESC is tightly coupled with Epicor's SOA architecture and calls Epicor business objects via .NET assemblies. As of Kinetic 2023.2, Epicor also offers Data Fabric (Kafka-based) as a cloud-native integration alternative, but Service Connect remains the primary integration tool for on-premise and hybrid customers. [src1, src2]

| Property | Value |
|---|---|
| **Vendor** | Epicor |
| **System** | Epicor Kinetic (Service Connect 10.2.x) |
| **API Surface** | SOAP, REST (v1/v2), .NET Assemblies, XML Web Services |
| **Current Version** | Kinetic 2024.x / ESC 10.2.700+ |
| **Editions Covered** | All Epicor Kinetic editions with Service Connect license add-on |
| **Deployment** | On-Premise / Hybrid (limited in SaaS) |
| **API Docs URL** | [Epicor REST API Help](https://{server}/{instance}/apps/resthelp/) (instance-specific) |
| **Status** | GA (actively maintained) |

## API Surfaces & Capabilities

ESC can interact with Epicor and external systems through multiple API surfaces. The primary method is .NET Reference calls to Epicor business objects, but REST and SOAP APIs provide alternative access paths. [src1, src4]

| API Surface | Protocol | Best For | Max Records/Request | Rate Limit | Real-time? | Bulk? |
|---|---|---|---|---|---|---|
| .NET Reference (BO calls) | .NET Assembly | Direct Epicor BO operations within ESC workflows | Transaction-dependent | No explicit limit (session-bound) | Yes | No |
| REST API v2 | HTTPS/JSON+OData | External integrations, mobile/web apps | Uses $top/$skip pagination (default 100) | None built-in (IIS-configured) | Yes | Via batch |
| SOAP/WCF Services | HTTPS/XML | Legacy integrations, .NET clients | 2,000+ per query | None built-in | Yes | No |
| ESC Web Service Endpoint | HTTPS/XML | Exposing ESC workflows as callable services | Per-workflow | N/A | Yes | No |
| File Channel (CSV/XML/Excel) | File system | Scheduled batch imports/exports | File size limited by memory | N/A | No | Yes |
| FTP/Email Channel | FTP/SMTP | Remote file pickup, email-triggered workflows | File/message size | N/A | No | Yes |
| MSMQ Channel | MSMQ | Reliable queued messaging | Message size (4 MB default) | Queue depth | Yes | No |

## Rate Limits & Quotas

### Per-Request Limits

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| REST API default page size | 100 records | REST API v2 OData queries | Use $top and $skip for pagination; max $top varies by BO [src4] |
| REST API request body | Server-configured | REST API POST/PATCH | IIS maxAllowedContentLength (default 28.6 MB) |
| MSMQ message size | 4 MB default | MSMQ channel | Configurable via MSMQ settings on server |
| File channel file size | Memory-bound | CSV/XML/Excel imports | Large files (>50 MB) may cause OutOfMemoryException in ESC |
| $batch subrequests | Server-configured | REST API v2 batch | IIS request limits apply |

[src4, src5]

### Rolling / Daily Limits

| Limit Type | Value | Window | Edition Differences |
|---|---|---|---|
| REST API calls | No built-in limit | N/A | Must configure via IIS Dynamic IP Restrictions or reverse proxy [src5] |
| Concurrent REST sessions | IIS AppPool worker threads | Per-AppPool | Default: 25 worker threads per AppPool; increase for high-volume integrations |
| ESC concurrent workflows | Thread pool-dependent | Per ESC service instance | Default thread pool size configurable in ESC admin; typically 5-20 concurrent workflows |
| Web Service license seats | License-dependent | Per-org | When exhausted, response times progressively degrade (doubling pattern) [src5] |

[src5]

## Authentication

Epicor Kinetic supports multiple authentication methods depending on the API surface. Service Connect workflows authenticate internally using configured Epicor session credentials. [src4]

| Flow | Use When | Token Lifetime | Refresh? | Notes |
|---|---|---|---|---|
| Basic Authentication | Simple REST API integrations, testing | Per-request (stateless) | N/A | Base64 encode username:password in Authorization header. Most common for Service Connect REST calls. [src4] |
| OAuth 2.0 (ROPC) | Production REST integrations requiring token-based auth | Configurable (default ~20 min) | Yes (via refresh token) | POST to /Token endpoint with grant_type=password. Recommended over Basic for production. [src4] |
| API Key (REST v2) | Programmatic access without user credentials | Persistent until revoked | N/A | Configured per-user in Epicor Admin Console. Available in REST API v2 only. [src4] |
| Epicor Session (.NET) | Service Connect internal BO calls | Session duration | Automatic | ESC uses configured credentials. Dedicated service account required. [src3] |
| Windows Authentication | On-premise intranet integrations | Windows session | N/A | IIS-level, SSO for domain-joined clients |

### Authentication Gotchas

- **Dedicated ESC user account is mandatory**: If the Service Connect service account is shared with an interactive user, plant/company context can change mid-workflow when the interactive user switches contexts. This causes data to be written to the wrong plant/company. Always create a dedicated, non-interactive user for ESC. [src3]
- **API Key requires REST v2**: API Key authentication is only available on REST API v2. If your Epicor instance is still on v1, you must use Basic Auth or OAuth ROPC. [src4]
- **OAuth ROPC is resource-owner password grant**: Unlike modern OAuth flows, Epicor's OAuth implementation uses the resource owner password credentials grant type, which means the integration must store username/password. This is less secure than client credentials flow used by other ERPs. [src4]

## Constraints

- **Service Connect requires a separate license** -- it is not included in the base Epicor Kinetic license. License cost varies by deployment and number of concurrent workflows. [src1]
- **No built-in API rate limiting** -- Epicor does not provide application-level rate limiting. You must implement throttling via IIS Dynamic IP Restrictions, a reverse proxy (nginx, HAProxy), or a WAF. Without this, a misbehaving integration can overwhelm the Epicor application server. [src5]
- **ESC is Windows-only** -- Service Connect runs as a Windows service (EpicorServiceConnect.exe). It cannot run natively on Linux or in most containerized environments. [src1]
- **XML is the internal message format** -- All data within ESC workflows is represented as XML. Non-XML inputs (CSV, Excel, fixed-width) must be converted to XML via conversion maps before workflow processing. This adds complexity and processing overhead. [src2]
- **Synchronous execution by default** -- ESC workflows execute synchronously. Long-running operations (large file imports, multi-step transformations) can block the ESC thread pool and delay other queued workflows. [src2]
- **BPM-to-ESC coupling is tight** -- When Epicor BPM triggers a Service Connect workflow, the pre-update business object dataset is passed directly. This means ESC workflows are version-dependent on Epicor BO schemas -- upgrades can break 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 or Windows Task Scheduler
|   |   |   |-- Event-driven --> BPM directive triggers ESC workflow [src6]
|   |   |   |-- On-demand --> Expose workflow as Web Service endpoint
|   |   |   |-- Queue-based --> MSMQ channel for reliable delivery
|   |   |-- Error handling approach?
|   |       |-- Simple notification --> Choice + Poster (email) after each .NET Reference [src3]
|   |       |-- UD table logging --> Choice + UpdateExt to UD table after each step [src3]
|   |       |-- Full reprocessing --> Log all fields to UD, track errors per record [src3]
|   |-- Direct REST API (bypass ESC)
|   |   |-- Volume < 1,000 records/day --> REST API v2 with Basic Auth or API Key [src4]
|   |   |-- Volume > 1,000 records/day --> REST API v2 with batch + throttle at IIS [src5]
|   |   |-- Need real-time notifications --> BPM + Epicor Functions + REST callout [src6]
|   |-- 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
|-- Direction?
|   |-- Inbound to Epicor --> Use UpdateExt or standard BO methods via .NET Reference
|   |-- Outbound from Epicor --> BPM trigger + ESC workflow or REST API polling
|   |-- Bidirectional --> Design conflict resolution + last-writer-wins or timestamp-based merge
```

## Quick Reference

| Workflow Element | Type | Purpose | Notes |
|---|---|---|---|
| .NET Reference | Activity | Call Epicor business object methods (GetNew, Update, GetList, etc.) | Core activity for all Epicor data operations [src2] |
| XML Mapper | Activity | Transform XML structure between source and target schemas | Drag-and-drop field mapping with functoid support [src2] |
| Choice | Control Flow | Conditional branching based on data values or error flags | Essential for error handling after every .NET Reference [src3] |
| Poster | Activity | Send email notifications, write to output channels | Used in error notification patterns [src3] |
| dbLookup | Functoid | Query external databases within XML Mapper | Uses ADO.NET; connection string must be configured [src2] |
| Conversion Map | Activity | Convert non-XML formats (CSV, Excel, fixed-width) to XML | Required for file-based imports of non-XML data |
| Scheduler | Configuration | Trigger workflows on time-based schedules | Cron-style scheduling within ESC admin |
| Human Workflow | Activity | Assign tasks to users with email notifications | For approval-based integration flows [src1] |
| Web Service Endpoint | Channel | Expose workflow as callable SOAP web service | External systems can invoke ESC workflows via WSDL |
| File Drop Channel | Channel | Monitor folder for new files, trigger workflow | Supports UNC paths, local paths; configurable polling interval |
| FTP Channel | Channel | Monitor FTP/SFTP location for new files | For EDI and partner data exchange [src1] |
| MSMQ Channel | Channel | Receive/send via Microsoft Message Queue | Reliable, transactional delivery; survives ESC restart |
| Email Channel | Channel | Process inbound emails or email attachments | For email-triggered workflows |
| COM Channel | Channel | Interact with COM-based applications | Legacy; rarely used in modern integrations |

## Step-by-Step Integration Guide

### 1. Set up dedicated Service Connect user

Create a dedicated Epicor user for Service Connect that will never be used for interactive logins. Assign appropriate security groups covering all business objects the workflows will access. Configure the ESC Windows service to run under this user's credentials or configure the user within ESC administration. [src3]

```plaintext
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 (logical folder), then configure an input channel appropriate for your data source. For file-based imports, create a File Drop channel pointing to a monitored folder. [src2]

```plaintext
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 input: Add Conversion Map activity to convert CSV to XML
```

**Verify**: Drop a test file in the monitored folder and confirm ESC picks it up (check ESC Administration > Workflow Monitor).

### 3. Add .NET Reference activities to call Epicor business objects

Drag a .NET Reference activity onto the workflow canvas. Browse to the target Epicor business object (e.g., Erp.Contracts.SalesOrderSvc) and select the method (e.g., GetNewOrderHed, Update). Map input fields from your XML to the business object dataset using the XML Mapper. [src2, src4]

```plaintext
.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 to execute 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. If an error occurred, branch to an error-handling path (email notification, UD table logging, or both). This prevents silent failures in production. [src3]

```plaintext
Error handling pattern:
1. After each .NET Reference, add Choice element
2. Condition: Check callContext.ExceptionMessage != ""
   - TRUE branch: Error occurred
     - Add Poster activity (email to admin)
     - OR: Add .NET Reference to UD table (Ice.Contracts.UD01Svc.UpdateExt)
     - Map error details: timestamp, source record ID, error message
   - FALSE branch: Continue to next step

Three error handling approaches (choose based on requirements):
A) Email-only: Choice > Poster (email) -- simplest, no audit trail
B) UD table logging: Choice > .NET Reference (UD table write) -- queryable audit trail
C) Full reprocessing: Log all input fields to UD + error details -- enables re-run
```

**Verify**: Deliberately send malformed data. Confirm error notification received and/or UD table entry created.

## Code Examples

### Python: Query Epicor via REST API v2

```python
# 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"

# Query open sales orders using OData filter
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")
elif response.status_code == 429:
    print("Rate limited - implement backoff (configured at IIS level)")
else:
    print(f"Error {response.status_code}: {response.text}")
```

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

```javascript
// Input:  Epicor server URL, credentials, order data
// Output: Created sales order number

// npm install node-fetch@2
const fetch = require("node-fetch");

const server = "https://epicor-server/ERP_Instance";
const credentials = Buffer.from("username:password").toString("base64");

async function createSalesOrder(custNum, orderLines) {
  // Step 1: Get a new order header dataset
  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 failed: ${getNewResp.status}`);
  }

  const ds = await getNewResp.json();
  // Step 2: Set customer and update
  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 failed: ${updateResp.status}`);
  }

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

createSalesOrder(1234, []).catch(console.error);
```

### cURL: Quick REST API test

```bash
# 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 .

# Expected token response:
# {
#   "access_token": "eyJ...",
#   "token_type": "bearer",
#   "expires_in": 1199
# }
```

## Data Mapping

### Field Mapping Reference

| Epicor Field | REST API Path | Type | Transform | Gotcha |
|---|---|---|---|---|
| OrderHed.OrderNum | SalesOrderSvc/SalesOrderHeds(OrderNum) | Int | Auto-assigned on create | Read-only after creation; cannot be set via API |
| OrderHed.CustNum | SalesOrderHeds.CustNum | Int | Direct | Must exist in Customer table; ESC validates on Update |
| OrderHed.OrderDate | SalesOrderHeds.OrderDate | DateTime | ISO 8601 | REST API expects "2026-03-02T00:00:00"; ESC XML uses .NET DateTime format |
| OrderDtl.PartNum | SalesOrderDtls.PartNum | String | Direct | Max 50 chars; must exist in Part table unless non-stock flag set |
| OrderDtl.OrderQty | SalesOrderDtls.OrderQty | Decimal | Direct | Decimals depend on UOM setup; integer UOMs reject fractional values |
| Customer.Name | CustomerSvc/Customers.Name | String | Direct | Max 50 chars in Epicor vs potentially longer in source systems |
| JobHead.JobNum | JobEntrySvc/JobHeads.JobNum | String | Direct | Max 14 chars; alphanumeric only; must be unique |

### Data Type Gotchas

- **DateTime format differs between REST and ESC XML**: REST API v2 uses ISO 8601 (2026-03-02T00:00:00Z), while ESC .NET Reference calls use .NET DateTime serialization format. Mismatches cause silent failures where dates default to 1900-01-01. [src4]
- **Decimal precision is UOM-dependent**: Epicor enforces decimal precision based on the Part's Unit of Measure. Sending 1.5 for a "Each" UOM (integer) causes a validation error. Always check UOM decimal places before mapping quantity fields. [src4]
- **Company/Plant context affects all BO calls**: Every .NET Reference call in ESC executes in the context of the configured company and plant. If the ESC user's context changes (due to shared login), data goes to the wrong plant. [src3]

## Error Handling & Failure Points

### Common Error Codes

| Code | Meaning | Cause | Resolution |
|---|---|---|---|
| BPM Exception | Business logic violation | BPM rule prevents the operation (e.g., credit hold, missing approval) | Check BPM directives on target BO; add pre-validation in ESC workflow before BO call [src6] |
| "This property cannot be set to a null value" | Required field missing | Upgrade changed required fields or new validation added | Compare BO dataset schema pre/post upgrade; update XML Mapper [src7] |
| "Object reference not set" | Null reference in .NET Reference | Missing parent record or incorrect dataset structure | Ensure GetNew is called before Update; verify dataset hierarchy (header before detail) |
| 401 Unauthorized | Authentication failure | Bad credentials or expired token | Verify username/password; for OAuth, acquire new token [src4] |
| 429 Too Many Requests | IIS rate limit hit | Too many concurrent API calls | Implement exponential backoff; increase IIS limits or add queuing layer [src5] |
| "Session limit reached" | License exhaustion | All Web Service license seats consumed | Scale back concurrent ESC workflows; purchase additional licenses [src5] |
| Timeout | BO method took too long | Large dataset or complex BPM processing | Increase WCF timeout in ESC config; break large operations into smaller batches |
| MSMQ full | Message queue at capacity | Consumer (ESC) not processing fast enough | Increase MSMQ storage limits; scale ESC processing threads |

[src3, src5, src7]

### Failure Points in Production

- **Epicor upgrade breaks ESC XML mappings**: When upgrading Epicor versions (e.g., 10.2.400 to 10.2.700), business object datasets gain new required fields. Existing ESC workflows that don't map these new fields fail with "null property" errors. Fix: `Before upgrading, export all workflow XML mappings. After upgrade, compare BO schemas and update mappings for new required fields. Test every workflow in a pilot environment.` [src7]
- **Shared service account causes cross-plant data corruption**: If the ESC service account is also used for interactive login, a user switching plants in the Epicor client changes the session context for ESC workflows running under the same account. Fix: `Create a dedicated, never-interactive ESC service account. Set its default plant/company in User Account Maintenance and lock it.` [src3]
- **Large CSV file imports cause OutOfMemoryException**: ESC loads entire files into memory for XML conversion. Files over 50-100 MB (depending on server RAM) can exhaust available memory. Fix: `Split large files into chunks of 10,000-20,000 records before dropping into the ESC monitored folder. Use a pre-processing script.` [src2]
- **ESC thread pool exhaustion blocks all workflows**: When multiple long-running workflows consume all available ESC threads, new incoming messages queue up indefinitely. Fix: `Monitor ESC thread pool usage. Set max concurrent workflows in ESC administration. Break long-running workflows into smaller sub-workflows.` [src2]
- **OAuth tokens expire mid-batch in REST integrations**: Default token lifetime is ~20 minutes. Long-running batch operations that cache the token will fail partway through. Fix: `Check token expiry before each batch of requests. Implement token refresh logic or re-acquire before expiry.` [src4]

## Anti-Patterns

### Wrong: No error handling after .NET Reference calls

```xml
<!-- BAD - no error check after BO call; 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

```xml
<!-- GOOD - error check after every BO call -->
<NetReference assembly="SalesOrderSvc" method="Update" />
<Choice condition="callContext.ExceptionMessage != ''">
  <True>
    <Poster type="email" to="admin@company.com"
            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 service

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

### Correct: Dedicated non-interactive service account

```plaintext
// 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

```plaintext
// BAD - dropping 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)
Channel: File Drop -> Single workflow processes all rows
```

### Correct: Pre-split files into manageable chunks

```bash
# GOOD - split large file into 10,000-row chunks before ESC processing
split -l 10000 --additional-suffix=.csv customers_full_export.csv chunk_
# Move chunks to ESC monitored folder with delay between each
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**: Epicor version upgrades change BO dataset schemas. Even minor version bumps (e.g., 10.2.600 to 10.2.700) can introduce new required fields that break existing XML mappings. Fix: `Build an upgrade testing checklist. Run every ESC workflow against the upgraded pilot environment before go-live.` [src7]
- **Ignoring ESC Workflow Monitor logs**: ESC provides detailed transaction logs in the Workflow Monitor, but many teams never check them. Failures accumulate silently. Fix: `Set up a daily check of the ESC Workflow Monitor. Configure email alerts for failed workflows via the Poster activity.` [src1]
- **Hardcoding server paths in file channels**: Using absolute paths like C:\EpicorData\Incoming breaks when migrating to a new server. Fix: `Use UNC paths (\\server\share\incoming\) and configure them as ESC parameters that can be updated without modifying workflows.` [src2]
- **Not implementing idempotency**: If ESC processes a file but fails partway through, reprocessing the file creates duplicate records. Fix: `Check for existing records (GetByID or GetList) before creating new ones. Use external reference IDs as unique keys.` [src3]
- **Skipping the Conversion Map for CSV files**: Attempting to process CSV directly in ESC workflows without converting to XML first causes parsing errors. Fix: `Always create a Conversion Map (CSV-to-XML) as the first activity for non-XML input files.` [src2]
- **Over-relying on ESC for high-volume real-time integration**: ESC is optimized for batch/workflow processing, not high-throughput real-time API calls. For >1,000 transactions/minute, ESC becomes a bottleneck. Fix: `Use REST API v2 directly with proper queuing (Azure Service Bus, RabbitMQ) for high-volume real-time scenarios. Reserve ESC for orchestrated, multi-step transformations.` [src5, src6]

## Diagnostic Commands

```bash
# 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 for Epicor
%systemroot%\system32\inetsrv\appcmd.exe list apppool "EpicorAppPool" /text:state

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

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

# Verify ESC can reach Epicor application server
curl -s -X GET "https://epicor-server/ERP_Instance/api/v2/odata/\$metadata" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" -o /dev/null -w "%{http_code}"
```

## Version History & Compatibility

| Version | Release Date | Status | Breaking Changes | Migration Notes |
|---|---|---|---|---|
| Kinetic 2024.1 | 2024-03 | Current | None for ESC | Field Service Management added; ESC unchanged |
| Kinetic 2023.2 | 2023-09 | Supported | Data Fabric introduced (new integration option) | Data Fabric is Kafka-based alternative; ESC still supported |
| Kinetic 2022.2 | 2022-09 | Supported | REST API v2 enhancements | v2 adds API Key auth; OData improvements |
| ERP 10.2.700 | 2021-06 | Supported (legacy) | Rebranded to Kinetic; first cloud-ready version | ESC workflows from 10.2.x are forward-compatible |
| ERP 10.2.500 | 2020-03 | EOL | Service Connect installation changes | New installer; existing ESC configs migrate automatically |
| ERP 10.2.400 | 2019-06 | EOL | BO dataset schema changes | Review all XML mappings; new required fields on several BOs [src7] |

[src1, src7]

### Deprecation Policy

Epicor follows a rolling support model where the current release and two prior releases are actively supported. Service Connect has been a core component since Epicor 9 and continues to be supported in Kinetic, though Epicor Data Fabric (introduced in 2023.2) represents the strategic direction for cloud-native integrations. There is no announced deprecation date for Service Connect. [src1]

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Multi-step data transformation with conditional logic and error handling | Simple CRUD operations on single business objects | Epicor REST API v2 direct calls |
| Scheduled file-based imports (CSV, Excel, XML from partners/EDI) | High-volume real-time streaming (>1,000 TPS) | Epicor Data Fabric (Kafka) or direct REST + message queue |
| BPM-triggered outbound integrations requiring data enrichment | Simple BPM email notifications or field calculations | Epicor BPM directives (no ESC needed) |
| Legacy SOAP/COM integrations with older partner systems | Modern microservices architecture with REST APIs | REST API v2 + iPaaS (MuleSoft, Boomi, Workato) |
| Reliable message-based integration via MSMQ | Cloud-to-cloud SaaS integrations | iPaaS platform or Epicor Data Fabric |

## Important Caveats

- Service Connect is a mature but aging technology. Epicor's strategic direction for cloud-native integration is Data Fabric (Apache Kafka via Confluent Cloud), introduced in Kinetic 2023.2. New projects should evaluate Data Fabric before committing to ESC, especially for cloud/SaaS deployments. [src1]
- ESC documentation is primarily available through EpicWeb (Epicor's customer portal), which requires an 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 which have platform-enforced limits, Epicor leaves this to IIS and infrastructure configuration. This is both a flexibility advantage and a risk. [src5]
- Cloud SaaS deployments of Epicor Kinetic may have restricted or no access to Service Connect, as ESC requires direct server access. Verify ESC availability with Epicor before planning integrations on SaaS deployments. [src1]
- The confidence score for this card (0.78) reflects that Epicor's Service Connect documentation is less publicly accessible than competing ERPs. Some technical details are based on community resources and partner documentation rather than official vendor docs. Verify critical limits against your specific Epicor version via EpicWeb.

## Related Units

- [Epicor Kinetic REST API v2 capabilities and endpoints](/business/erp-integration/epicor-kinetic-rest-api/2026)
- [Epicor eCommerce integration playbook](/business/erp-integration/epicor-ecommerce-integration/2026)
- [Epicor Data Fabric (Kafka-based cloud-native integration)](/business/erp-integration/epicor-data-fabric/2026)
- [Epicor BPM customization](/business/erp-integration/epicor-bpm-customization/2026)