JobBOSS² Integration Guide
Overview
Connect a cloud-hosted or on-premises JobBOSS² (ECI Manufacturing) instance to MachineMetrics for bidirectional work order and labor tracking synchronization.
This guide covers JobBOSS², the newer ECI Manufacturing product, where the connector uses REST APIs. Cloud installations use the ECI Integration Engine; on-premises installations use the local JobBOSS² API. If your shop runs the older on-premises JobBoss Classic (ECI JobBOSS) product, use the JobBoss Classic guide instead; it connects directly to your JobBoss SQL Server database and uses a different data model.
| Attribute | Value |
|---|---|
| Direction | Bidirectional |
| Data Flow (Inbound) | Work centers, parts, part operations, work orders, work order operations, employees, and reason codes from JobBOSS² → MachineMetrics |
| Data Flow (Outbound) | Labor tickets (time tickets) from MachineMetrics → JobBOSS² |
| Runs On | MachineMetrics Edge Device (physical or Virtual Edge) |
| Connection Method | REST API; OAuth client credentials for cloud, API key and user credentials for on-premises |
Requirements and Permissions
| Requirement | Details |
|---|---|
| MachineMetrics Edge | A physical or Virtual Edge Device to run the connector service. |
| JobBOSS² Instance | v1 or later. Cloud: access to the ECI Integration Engine. On-premises: access to the local JobBOSS² API. |
| API access | Cloud: Integration Engine credentials. On-premises: access to the local JobBOSS² API and its API key/user credentials. |
| Network Access | The Edge device must reach the API and authentication hosts for your installation and the MachineMetrics APIs. Cloud installations use ECI endpoints. On-premises installations require access to the local API hosts. If the optional on-premises SQL path is configured, the Edge device must also reach the database host and port (default TCP 1433) with a read-only SQL login; see Step 4. |
| API Credentials | Cloud: Client ID and Secret. On-premises: API key, username, and password. Enter the credentials for your authentication path in Edge Services. |
Setup
Complete the ERP-specific steps below, then follow Setup and Verification for resource mapping, operator mapping, and the go-live checks. The customer enters credentials directly in Edge Services. Never share credentials with MachineMetrics staff.
Step 1: Create API Credentials in the Integration Engine Portal
For a cloud installation, use OAuth 2.0 client credentials:
- Sign in to the ECI Integration Engine Portal.
- Create an application/integration for MachineMetrics.
- Note the generated Client ID and Client Secret.
The Client Secret is typically shown only once at creation time. Copy it before leaving the page; if it is lost, you will need to generate a new one.
For an on-premises installation, ask the ERP administrator to prepare the local API base URL and authentication host, API key, username, and password. This path signs in through /api/v1/Login. Enter ERP_API_KEY, ERP_API_USER_NAME, and ERP_API_PASSWORD in Edge Services. Do not also enter cloud OAuth credentials for this path; if both sets are populated, OAuth is selected first.
Step 2: Confirm Your JobBOSS² API Endpoints
Confirm the API and authentication host names with your ECI administrator. The examples below are for the cloud Integration Engine; on-premises installations use the hosts supplied for the local API:
| Item | Example |
|---|---|
| API host | api-jb2.ecimanufacturing.com |
| Authentication host | api-users.ecimanufacturing.com |
Step 3: Enter Connection Settings in Edge Services
| Item | Description |
|---|---|
| API Host | Cloud Integration Engine host (e.g. api-jb2.ecimanufacturing.com) or your local on-premises API host. |
| Authentication Host | Cloud authentication host (e.g. api-users.ecimanufacturing.com) or your local on-premises authentication host. |
| Client ID | Cloud: the Client ID created in Step 1. |
| Client Secret | Cloud: the Client Secret created in Step 1. |
| API key, username, password | On-premises: the credentials for /api/v1/Login. |
Step 4: Grant SQL Server Access (On-Premises SQL Path Only)
Complete this step only if JobBOSS² is hosted on your own servers and you and your SDM have agreed that the connector will read job routings directly from the JobBOSS² SQL Server database. Cloud installations and on-premises installations that use only the API skip this step.
What the Connector Reads from SQL Server
In SQL mode, the connector reads job routing rows from the OrderRouting table instead of the order-routings API resource. Those rows are the source for parts, part operations, work orders, and work order operations in MachineMetrics.
Everything else still goes through the JobBOSS² API, so the API settings from Steps 1–3 are still required:
| Data | Source |
|---|---|
| Job routings (parts, part operations, work orders, work order operations) | SQL Server: dbo.OrderRouting |
| Work centers | JobBOSS² API |
| Employees | JobBOSS² API |
| Reason codes | JobBOSS² API |
| Labor tickets (write-back) | JobBOSS² API (time-tickets) |
The connector never writes to the database.
Create a Read-Only SQL Server Login
Create a dedicated SQL Server login for MachineMetrics and grant it SELECT on one table in your JobBOSS² company database:
dbo.OrderRouting
The connector does not need INSERT, UPDATE, DELETE, or access to any other table, view, or stored procedure. Don't give this login db_owner, db_datawriter, or sysadmin.
The connector reads these OrderRouting columns. If you restrict access by column, all of them must be readable:
OrderNo, JobNo, StepNo, PartNo, Descrip, WorkCntr, Status,
SetupTime, CycleTime, CycleUnit, MachRun, NumMachForJob, UnattendOp,
SetupRate, CycleRate, BurdenRate, LaborRate, PctEff,
EstimQty, EstimStartDate, EstimEndDate, LastModDate, LastModUser
Example script (replace the database name, login name, and password):
-- Run on the SQL Server instance that hosts JobBOSS²
CREATE LOGIN mm_jobboss2_reader WITH PASSWORD = '<strong-password>';
GO
USE [<JobBOSS2 database name>];
GO
CREATE USER mm_jobboss2_reader FOR LOGIN mm_jobboss2_reader;
GRANT SELECT ON dbo.OrderRouting TO mm_jobboss2_reader;
GO
Confirm SQL Server Connectivity
| Requirement | Details |
|---|---|
| SQL Server Authentication | The connector signs in with a SQL Server username and password. Windows (Active Directory) authentication isn't supported, so the instance must allow SQL Server and Windows Authentication mode (mixed mode). |
| TCP/IP enabled | TCP/IP must be enabled for the instance in SQL Server Configuration Manager. |
| Network path | The Edge device must reach the SQL Server host on its TCP port (default 1433). Open any firewall between the Edge and the SQL Server for that port. For a named instance, use a fixed port rather than dynamic ports. |
| Stable address | Use a static IP address (or DHCP reservation), or a hostname the Edge device can resolve. If the address changes, update ERP_DATABASE_HOST in Edge Services. |
| Encryption | The connector always encrypts the connection and accepts the server's certificate, including a self-signed one. You don't need to install a CA-signed certificate. |
Enter Database Settings in Edge Services
| Item | Environment Variable | Description |
|---|---|---|
| SQL Server Host | ERP_DATABASE_HOST | IP address or hostname of the JobBOSS² SQL Server. Setting this turns on SQL mode. |
| SQL Server Port | ERP_DATABASE_PORT | TCP port of the instance (default 1433). |
| Database Name | ERP_DATABASE_NAME | The JobBOSS² company database that contains OrderRouting. |
| Username | ERP_DATABASE_USERNAME | The read-only login created above. |
| Password | ERP_DATABASE_PASSWORD | The password for that login. |
Also set ERP_MAX_ELEMENTS_LIMIT explicitly. In SQL mode it controls how many OrderRouting rows are read on each poll.
How SQL Mode Differs
- Work order status: the SQL query doesn't read the job header (
OrderDet). Each work order's status comes from the status of the job's highest-numbered routing step. - Due date: without the job header, a work order's due date falls back to the routing's estimated end date. If that is blank, the routing's last-modified date is used.
- Volume per poll: each poll reads the most recent routing rows, newest order number first, up to
ERP_MAX_ELEMENTS_LIMIT. If active jobs are missing, raise this limit.
Verifying the Integration
- Confirm that active JobBOSS² work orders appear in MachineMetrics ERP Data Studio.
- Have an operator clock into and out of a job in ShopPulse, then confirm a labor ticket is created.
- In JobBOSS², confirm the corresponding time ticket was written for that operation with the correct employee, hours, and quantities.
Confirm Labor and Time Reporting
The connector calculates setup or production hours from each ticket's start and end times and posts them to JobBOSS² as a time ticket. Confirm with your JobBOSS² administrator how completed labor and quantities should reconcile against your existing shop-floor process, so that time reporting matches your team's expectations before go-live.
Configuration Settings
| Setting | Environment Variable | Description | Default |
|---|---|---|---|
| ERP System | ERP_SYSTEM | Selects the JobBOSS² connector | JOB_BOSS |
| API URL | ERP_API_URL | Cloud Integration Engine host or local on-premises API host | Not set |
| Auth Base URL | ERP_AUTH_BASE_URL | Cloud or on-premises authentication host | Not set |
| Client ID | ERP_API_CLIENT_ID | OAuth client ID from the Integration Engine Portal | Not set |
| Client Secret | ERP_API_CLIENT_SECRET | OAuth client secret from the Integration Engine Portal | Not set |
| On-premises API key | ERP_API_KEY | Required for the local API login path | Not set |
| On-premises username | ERP_API_USER_NAME | User for the local API login path | Not set |
| On-premises password | ERP_API_PASSWORD | Password for that user | Not set |
| Optional SQL host | ERP_DATABASE_HOST | Enables the SQL path for job routings (see Step 4); configure only with your ERP administrator and SDM | Not set |
| SQL credentials | ERP_DATABASE_USERNAME, ERP_DATABASE_PASSWORD, ERP_DATABASE_NAME | Required for an installation using the optional SQL path | Not set |
| SQL port | ERP_DATABASE_PORT | Port for the optional SQL path | 1433 |
| Poll Interval | POLL_INTERVAL | How often work orders and operations are pulled from JobBOSS² | 5 min |
| Retry Labor Tickets Interval | RETRY_LABOR_TICKETS_INTERVAL | How often failed labor ticket write-backs are retried | 30 min |
| Max Elements Limit | ERP_MAX_ELEMENTS_LIMIT | Maximum records of a given type fetched per run | 40 |
| Pagination Limit | ERP_PAGINATION_LIMIT | Records fetched per page from the API | 20 |
| Retry Attempts | RETRY_ATTEMPTS | Number of times an API request is retried on failure | 3 |
The poll interval accepts human-friendly values such as 5s, 5 min, every 5 mins, or 3 days and 4 hours.
Sync Behavior
Inbound Records
Active jobs and their routings are read from the configured JobBOSS² API (order-routings) and transmitted to MachineMetrics, making work orders and operations available for operators after sync. Work centers, employees, and reason codes are pulled from their corresponding API resources.
On-premises installations can optionally read job routings from the OrderRouting SQL Server table instead of the order-routings API. In that mode, parts, part operations, work orders, and work order operations all come from SQL; everything else, including labor write-back, still uses the API. See Step 4 for the required access and How SQL Mode Differs for behavior changes.
Labor Write-Back
Outbound sync requests closed tickets only. The connector posts a time ticket back to JobBOSS² (time-tickets). The connector calculates setup or production hours from the ticket's start and end times, attaches the operator's employee code and the ticket date, and maps any recorded downtime reason to the corresponding JobBOSS² reason code.
Data Mapping
The connector maps MachineMetrics entities to JobBOSS² entities as follows:
| MachineMetrics Entity | JobBOSS² Entity | Key Field |
|---|---|---|
| Resources (machines / work centers) | WorkCntr | WorkCntr |
| Parts | OrderDet | PartNo |
| Part Operations | Routing | Routing_ID |
| Work Orders | OrderRouting | OrderRouting_ID |
| Work Order Operations | TimeTicketDet | TimeTicketDet_ID |
| Persons (employees) | EmplCode | EmplCode |
| Reasons | ReasonCode | ReasonCode |
| Labor Tickets | TimeTicketDet | TimeTicketDet_ID |
Troubleshooting
| Issue | Possible Cause | Solution |
|---|---|---|
| Work orders not appearing | Authentication failed | For cloud, verify Client ID/Secret and the authentication host. For on-premises, verify the API key, username, password, and local API host. |
| Authentication errors | Wrong API or auth host | Confirm ERP_API_URL and ERP_AUTH_BASE_URL match your JobBOSS² environment. |
| Connection errors / timeouts | Edge cannot reach the configured API, authentication, or database host | Verify access from the Edge device to the cloud or local API and authentication hosts. If SQL mode is configured, also verify the configured database host and port. |
| No data returned | Fetch limits too low | Increase ERP_MAX_ELEMENTS_LIMIT / ERP_PAGINATION_LIMIT, or confirm the jobs exist and are active in JobBOSS². |
| Labor not syncing back | Ticket not closed, or the time ticket post failed | Verify the operator clocked out; failed write-backs are retried on the RETRY_LABOR_TICKETS_INTERVAL. |
| Labor hours look wrong | Missing start/end times or ticket type | Confirm the labor ticket has both a start and end time and a setup/production type so hours can be calculated. |
| Reason not recorded | Reason code not mapped | Confirm the MachineMetrics downtime reason maps to a valid JobBOSS² reason code. |
| "SQL Server connection failed" (on-premises SQL mode) | Edge can't reach SQL Server, or the login is rejected | Confirm the host, port, and database name. Check that TCP/IP and mixed-mode authentication are enabled and that the firewall allows the Edge to reach the SQL port. Verify the login's password. |
Permission denied on OrderRouting (on-premises SQL mode) | Login lacks SELECT on the table | Grant SELECT on dbo.OrderRouting in the JobBOSS² database to the MachineMetrics login (see Step 4). |
| Work orders show the wrong status (on-premises SQL mode) | Status comes from the job's last routing step | Confirm that the final routing step's status in JobBOSS² reflects the job's state (see How SQL Mode Differs). |
FAQ
Are cloud and on-premises deployments supported? Yes. Confirm the cloud Integration Engine or local on-premises API endpoints with your ERP administrator and SDM. If job routings use the optional SQL path, also complete Step 4.
Does this guide cover ERP Driven labor import? No. This guide covers inbound job/reference data and ShopPulse labor write-back. Confirm ERP Driven labor-import support for your deployed connector before selecting that workflow.
What is written back?
The connector posts time tickets to the time-tickets API, including employee, date, setup or production hours, and mapped reason information.
Related Guides
Getting Help
Contact your Solution Delivery Manager (SDM) during onboarding or MachineMetrics Support for technical issues after onboarding. For ERP permissions and posting, work with your ERP administrator.