Shop Floor Insight web services

Skip to main content

Shop Floor Insight web services

You are here:

Shop Floor Insight publishes a set of Business Central web services. The Shop Floor Insight clients use them to sign employees in, show dispatch lists, record time, output and consumption, and run server actions. Custom applications can call the same services.

This article lists each web service with a one-line summary of what it does.

This article is for developers and partners who integrate with or customize Shop Floor Insight. It is not intended for shop floor operators or other end users.

Before you build a custom interface, check whether one of the existing Shop Floor Insight interfaces already fits:

  • Web browser: the Shop Floor Insight barcode-optimized interface.
  • Windows and Android devices: Shop Floor Insight in Warehouse Insight. See Warehouse Insight Shop Floor Integration.
  • Business Central phone and tablet app: the Shop Floor Insight Phone Optimized profile, which uses the phone role center (page 23044186). See Shop Floor Native Phone Client.

Available functionality differs between interfaces, so compare them with the activities your operators need.

Note: This article describes the web services, methods and responses as they were when it was written. They can change as Shop Floor Insight is updated, so responses in your environment may differ slightly. When they differ, go by what your system returns. The OData metadata document ($metadata) lists current names and parameters.

Before you start

  • Run the Shop Floor Insight Setup Wizard. The wizard publishes the web services listed in this article.
  • To check a service, open the Business Central Web Services page and confirm the Service Name, Object Type, Object ID and Published values match the tables below.
  • Business Central licensing: a custom interface doesn’t change Microsoft’s Business Central licensing requirements, including access through web services. Business Central device licenses can cover qualifying shared shop floor devices. Confirm the right user or device licensing with your Microsoft partner. See Business Central device licensing information and Business Central licensing guidance.
  • Shop Floor Insight licensing is also required when using the Shop Floor Insight web services, even if you are not using the Shop Floor Insight scanning station apps. See licensing requirements for Insight Works apps.

How the web services are published

The Shop Floor Insight Setup Wizard downloads the web service list for the installed Shop Floor Insight release from the Insight Works configuration location.

For each entry, the wizard creates the web service if no service with that name and object type exists. If one exists but points to a different object, the wizard replaces it so the name points to the Shop Floor Insight object.

The wizard leaves a service alone when it points to an object ID of 99999 or lower. This lets a partner point a service name at their own object in the 50000 to 99999 range without the wizard reverting it.

Note: Service names are prefixed with SFI or TCM. The service names must not change.

Web services list

Page web services return records and, for some services, accept new or changed records; most are read with filters on the page fields. Codeunit web services expose procedures that perform an action, such as recording output. With OData, call a codeunit procedure with a POST request to {serviceName}_{procedureName}.

Service name Object type Object ID What it does
SFIAbsence Page 23044233 Returns registered absences for the production scheduler and saves changes to them.
SFIDatasources1 Page 23044199 Returns the screen data sources and display templates that client screens, such as the production scheduler, use. 1
SFIGroupRtng1 Page 23044234 Returns grouped routing lines for the production scheduler and saves rescheduled start times. 1
SFIQualityInspection Codeunit 23044100 Connects Shop Floor Insight to Quality Inspector: creates and reads tests, sets test values, and finishes, reopens or retests.
TCMActivities Page 23044221 Lists the Shop Floor Insight activities an employee can record time against.
TCMAssignmentMgmt Codeunit 23044105 Assigns or unassigns production routing operations and job tasks to employees.
TCMAuthorizationType Page 23044232 Lists the authorization types used to verify employees.
TCMBarcode Codeunit 23044108 Decodes a Shop Floor Insight barcode and returns what it identifies. It only decodes; it does not clock on or off or perform any other action.
TCMBom Page 23044217 Returns production order components for a production order line, optionally limited to an operation’s routing link.
TCMClientConfig Page 23044205 Returns Shop Floor client configuration records.
TCMClientState1 Codeunit 23044244 Gets, sets, clears and copies saved state values for a shop floor client session. 1
TCMComments Page 23044222 Reads and adds Shop Floor Insight comment lines.
TCMConsumptionMgmt Codeunit 23044210 Creates, records and posts production and job consumption, and returns lot numbers and available lot quantities.
TCMCustomFieldMgmt Codeunit 23044161 Earlier quality inspection integration, kept for existing integrations. Current installs use SFIQualityInspection.
TCMDispatch Page 23044214 Returns the production dispatch list for a client configuration and employee.
TCMItemPicture Codeunit 23044243 Returns the item picture for an item or for the selected line, with an optional compressed version.
TCMJobPlanningLine Page 23044228 Returns job planning lines for job-based shop floor work.
TCMJobTask Page 23044227 Returns job tasks for the job dispatch list.
TCMLinks Codeunit 23044205 Returns the record links (attached documents and URLs) for production orders, jobs and fixed assets.
TCMLogin1 Codeunit 23044230 Signs an employee in and returns the time card number, employee name, sign-in time and client configuration. 1
TCMOutput Page 23044223 Returns production order routing line details used when recording output.
TCMOutputHistory Page 23044266 Returns posted and unposted output history for a production order and item.
TCMOutputMgmt Codeunit 23044212 Prepares and records production output, checks over-output rules, and returns item tracking and the next operation.
TCMScrap Page 23044224 Lists scrap codes.
TCMServerBarcode Page 23044138 The server action service. Takes a scan or menu action with its context and returns instructions for the client. See the server action article.
TCMServerInfo Codeunit 23044235 Returns the server date and time, language and unblocked users, and checks the caller’s access.
TCMSetup Page 23044229 Returns the Shop Floor Setup values the client needs.
TCMSimpleTimeClock Codeunit 23044213 Handles badge scans and employee authorization for the simple time clock, including authorization keys.
TCMStyles Page 23044213 Returns the display styles the client applies to rows and screens.
TCMTimeCardHeader Codeunit 23044202 Gets or creates the employee’s time card, logs out, ends the shift, closes the time card, and calculates card and weekly hours.
TCMTimeCardLine Codeunit 23044203 Clocks off a time card line.
TCMTimeCardLine Page 23044212 Reads time card lines and creates new ones.
TCMTools Page 23044220 Returns the tools assigned to a production order routing operation.
TCMWorkCenter Page 23044225 Returns Shop Floor Insight work center records.
TCMWorkInstructionsRouting Page 23044219 Returns work instructions: production order comments and comments for the selected routing operation.

1 This web service is on the roadmap to be removed or refactored. Avoid using it in new code when possible, to minimize disruption later.

TCMTimeCardLine is published from two objects, codeunit 23044203 and page 23044212. Business Central combines a page and a codeunit that are published with the same service name into one web service.

The page provides the time card line records, and the codeunit’s methods, such as ClockOff, are exposed on that same service. A codeunit method whose first parameter is a record of the page’s source table runs against a time card line from the service.

Codeunit web service methods

This section lists the public methods of each codeunit web service. Where a method has an OData version (a name that includes ODATA), only the OData version is listed. Call a method with a POST request to {serviceName}_{methodName}. Methods that return Text return it in the value property of the OData response.

SFIQualityInspection (codeunit 23044100)

Connects Shop Floor Insight to Quality Inspector. It creates and reads quality tests for the shop floor context, sets test values, and finishes, reopens or retests them.

Method Parameters Returns What it does
GetQualityInspectorTestData ptxtConfigNo, ptxtEmployeeNo, ptxtInputScreenNo, ptxtAddress, ptxtCurrentTimeCardNo, ptxtSelectedRowKey1, ptxtSelectedRowKey2, ptxtSelectedRowKey3, ptxtLotNo, ptxtSerialNo, ptxtOptionalSpecificTemplate, ptxtSpecificTestRecordId (all Text) Text (JSON) Returns the Quality Inspector test for the current shop floor context, or for a specific test record ID, as JSON (see the example below).
CreateQualityInspectorTest The same context parameters as GetQualityInspectorTestData, without ptxtSpecificTestRecordId Text (JSON) Creates a Quality Inspector test for the current shop floor context and returns it as JSON (see the example below).
SetQualityInspectorFieldValue The context parameters, ptxtTestLineRecordId, ptxtValue (all Text) Text (JSON) Sets the value of one test line and returns the updated test as JSON (see the example below).
SetCustomFieldValueODATA fieldGroup: Text, fieldCode: Text, value: Text Text (JSON) Sets the test value on one Quality Inspector test line and returns the updated test as JSON. fieldGroup is SFIQITestValue (or TCMQITestValue). fieldCode identifies the test line as TestNo||RetestNo||LineNo, optionally followed by ||TemplateCode||FieldCode. The parameter names must be used exactly as shown.
QualityScreenClosed The context parameters, ptxtTestRecordId (all Text) Text Tells Business Central that the operator closed the quality screen for a test, and raises an event extensions can use.
FinishTest The context parameters, ptxtTestRecordId (all Text) Text (JSON) Finishes the test and returns it as JSON (see the example below).
ReOpenTest The context parameters, ptxtTestRecordId (all Text) Text (JSON) Reopens a finished test and returns it as JSON (see the example below).
CreateReTest The context parameters, ptxtTestRecordId (all Text) Text (JSON) Creates a retest of the test and returns the retest as JSON (see the example below).

The test methods return the test as a JSON object with an IWXQI array, one entry per test line. Option and table lookup fields also include IWXQIJsonOptionsArray. When there is no test yet, the test-specific properties are left out. A hypothetical example:

{
  "IWXQI": [
    {
      "IWXQIFieldCode": "DIAMETER",
      "IWXQITestNo": "QI-000123",
      "IWXQIReTestNo": "0",
      "IWXQITestStatus": "0",
      "IWXQITestStatusText": "Open",
      "IWXQITestRecordId": "IWX QI Test: QI-000123,0",
      "IWXQIAssignedUserID": "",
      "SFIEmployeeNo": "EMP001",
      "IWXQILotNo": "LOT-001",
      "IWXQISerialNo": "",
      "IWXQITestLineRecordId": "IWX QI Test Line: QI-000123,0,10000",
      "IWXQIGradeCategory": "1",
      "IWXQIRowSource": "IWX QI Test Line: QI-000123,0,10000",
      "IWXQIAllowableValues": "10.0..10.5",
      "IWXQITemplateCode": "FINAL-INSP",
      "IWXQIDescription": "Final inspection",
      "IWXQIFieldType": "Decimal",
      "IWXQIFieldDescription": "Outside diameter (mm)",
      "IWXQIPromotedGrade1Description": "10.0..10.5",
      "IWXQIPromotedGrade2Description": "",
      "IWXQIPromotedGrade3Description": "",
      "IWXQITestValue": "10.2",
      "IWXQIGradeCode": "PASS"
    },
    {
      "IWXQIFieldCode": "FINISH",
      "IWXQITestNo": "QI-000123",
      "IWXQIReTestNo": "0",
      "IWXQITestStatus": "0",
      "IWXQITestStatusText": "Open",
      "IWXQITestRecordId": "IWX QI Test: QI-000123,0",
      "IWXQIAssignedUserID": "",
      "SFIEmployeeNo": "EMP001",
      "IWXQILotNo": "LOT-001",
      "IWXQISerialNo": "",
      "IWXQITestLineRecordId": "IWX QI Test Line: QI-000123,0,20000",
      "IWXQIRowSource": "IWX QI Test Line: QI-000123,0,20000",
      "IWXQIAllowableValues": "Smooth,Rough",
      "IWXQITemplateCode": "FINAL-INSP",
      "IWXQIDescription": "Final inspection",
      "IWXQIFieldType": "Option",
      "IWXQIFieldDescription": "Surface finish",
      "IWXQIPromotedGrade1Description": "Smooth",
      "IWXQIPromotedGrade2Description": "",
      "IWXQIPromotedGrade3Description": "",
      "IWXQIJsonOptionsArray": ["Smooth", "Rough"],
      "IWXQITestValue": "",
      "IWXQIGradeCode": ""
    }
  ]
}

TCMAssignmentMgmt (codeunit 23044105)

Assigns or unassigns production routing operations and job tasks to employees.

Method Parameters Returns What it does
AssignRouting pbassign: Boolean, pcodProdOrderNo: Code[20], piRoutingReferenceNo: Integer, pcodOperationNo: Code[20], pcodEmployeeNo: Code[20] None Assigns (pbassign = true) or unassigns (false) a production routing operation to an employee.
AssignJob pbassign: Boolean, pcodJobNo: Code[20], pcodJobTaskNo: Code[20], pcodEmployeeNo: Code[20] None Assigns or unassigns a job task to an employee.

TCMBarcode (codeunit 23044108)

Decodes a Shop Floor Insight barcode and returns what it identifies. It only decodes; it does not clock on or off or perform any other action.

Method Parameters Returns What it does
LookupBarcode pcodType: Code[5], ptxtMapID: Text, pbIncludeBreakCode: Boolean Code[250] Decodes a Shop Floor Insight barcode type and map ID and returns the value it identifies. It only decodes the barcode; it does not sign in, clock on or off, or perform any other action. To act on a scan, use the server action web service, TCMServerBarcode.

TCMConsumptionMgmt (codeunit 23044210)

Creates, records and posts production and job consumption, and returns lot numbers and available lot quantities.

Method Parameters Returns What it does
CreateConsumptionEntry pcodBatchName: Text, pcodTimeCardHeaderNo: Code[20], piTimeCardLineNo: Integer, pcodLocationCode: Text, pcodProdOrderNo: Text, piProdOrderLineNo: Integer, pcodItemNo: Text, pcodVariant: Text, pdQuantity: Decimal, pcodLotNumber: Text, pcodSerialNumber: Text, psDescription: Text None Creates a production consumption journal entry for a component.
RecordConsumption As CreateConsumptionEntry, plus piProdOrderCompLineNo: Integer after piProdOrderLineNo None Records production consumption for a specific production order component line.
GetLotAvailableQty pcodLocationCode: Code[10], pcodItemNo: Code[20], pcodVariantCode: Code[20], pcodLotNumber: Code[200] Decimal Returns the available quantity of a lot at a location.
getJobTemplateName None Code[10] Returns the job journal template name used for job consumption.
CreateJobConsumptionEntry pcodBatchName: Code[10], pcodTimeCardHeaderNo: Code[20], piTimeCardLineNo: Integer, pcodLocationCode: Code[10], pcodJobNo: Code[20], pcodJobTaskNo: Code[20], piType: Integer, pcodSourceNo: Code[20], pcodVariant: Code[20], pdQuantity: Decimal, pcodLotNumber: Code[200], pcodSerialNumber: Code[200], psDescription: Text[100] Boolean Creates a job journal entry for job consumption.
postJobConsumption pcodBatchName: Code[10] None Posts the job journal batch, skipping comment lines.
GetCSVOfLotNosODATA pcodProdOrderNo: Text, piProdOrderLineNo: Integer, pcodItemNo: Text Text Returns up to 50 lot numbers for the item from warehouse entries, or item ledger entries when warehouse entries give one or none. The text starts with a space and each lot is preceded by a comma. Returns No lot is available. when there are none. The production order and line parameters help identify the item. See the example below.

Example of what GetCSVOfLotNosODATA returns (hypothetical values):

 ,LOT-003,LOT-002,LOT-001

TCMItemPicture (codeunit 23044243)

Returns pictures for the shop floor screens: the item or employee picture most relevant to the selected line.

Method Parameters Returns What it does
GetPictureForSelectedLineODATA pcodConfig, pcodEmployee, pcodScreen, pcodKey1, pcodKey2, pcodKey3: Code[20], piSpecificWidth: Integer, piSpecificHeight: Integer Text Returns the most relevant picture for the selected time card line or production order line, falling back to the employee’s picture.
GetPictureForSelectedLineODATACompressed Same as GetPictureForSelectedLineODATA Text Do not use, no longer used.

TCMLinks (codeunit 23044205)

Returns the record links (attached documents and URLs) for production orders, jobs and fixed assets.

Method Parameters Returns What it does
GetProdOrderLinksODATA pcodProdOrderNo: Code[20], pcodProdItemNo: Code[20] Text Returns the links on the released production order, followed by the links on the item. Each link is a description and a URL separated by ||, and links are also separated by ||. Only links (not notes) are returned, and file paths are converted with performFileToHTTPMapping. See the example below.
GetJobLinksODATA pcodJobNo: Code[20], pcodJobTaskNo: Code[20] Text Returns the links on the job task, in the same format as GetProdOrderLinksODATA.
performFileToHTTPMapping ptxtFileURI: Text Text Converts a file path to an HTTP link. Mappings are set up on page 23044127, Shop Floor File to HTTP URL Maps (table 23044206, Shop Floor File to HTTP Map). The first File URI that matches, in Execution Order, is replaced with its HTTP URL Mapping. See Using Links in Shop Floor Insight. See the example below.

Example of what GetProdOrderLinksODATA returns (hypothetical values):

Order traveler||https://contoso.sharepoint.com/sites/prod/RPO00123-traveler.pdf||Assembly drawing||https://documents.example.com/drawings/A100.pdf

Example of what performFileToHTTPMapping returns (hypothetical values):

File URI:          \\server\drawings\
HTTP URL Mapping:  https://documents.example.com/drawings/

Input:   \\server\drawings\A100\A100-rev2.pdf
Returns: https://documents.example.com/drawings/A100/A100-rev2.pdf

TCMOutputMgmt (codeunit 23044212)

Prepares and records production output, checks over-output rules, and returns item tracking and the next operation.

Method Parameters Returns What it does
RecordOutput ptxtConfigNo: Text, ptxtTimeCardNo: Text, piTimeCardLineNo: Integer, pdQuantity: Decimal, pdScrap: Decimal, pcodScrapCode: Text, pcodLotNumber: Text, pcodSerialNumber: Text, pcodLocationCode: Text, pcodBinCode: Text, pcodLicensePlate: Text None Records output and scrap against a production time card line, clocking on or off as the client configuration requires.
ManualRecordOutputNoTimeCardLine ptxtConfigNo: Text, ptxtTimeCardNo: Text, pcodProdOrderNo: Text, piProdOrderLineNo: Integer, pcodOperationNo: Text, then the same quantity, scrap, tracking, location, bin and license plate parameters as RecordOutput None Records output for a production order operation without a time card line, for the Manual output setting.
CheckOverOutputAllowed ptxtConfigNo: Text, pcodProdOrderNo: Code[20], piOrderLineNo: Integer, pcodOperationNo: Code[10], pdQuantity: Decimal None Errors if the client configuration doesn’t allow over-output and the quantity would exceed the expected output.
GetItemTrackingODATA pcodProdOrderNo: Code[20], piProdOrderLineNo: Integer Text (JSON) Returns whether the production order line item is serial or lot tracked. See the example below.

Example of what GetItemTrackingODATA returns (hypothetical values):

{"isjsonmultipleoutputresponse": true, "pbSerialTracked": false, "pbLotTracked": true}

TCMServerInfo (codeunit 23044235)

Returns the server date and time, language and unblocked users, and checks the caller’s access.

Method Parameters Returns What it does
GetDateTime None DateTime Returns the current Business Central date and time.
GetLanguage None Text Returns the language code of the current session.
GetUnblockedUsers None Text Returns the numbers of all employees who aren’t blocked, separated by ||. See the example below.
CheckAccess ptxtAction: Text, pcodResourceNo: Code[20], ptxtContext: Text Integer Checks whether an employee can perform an action, such as OpenQITest or ModifySchedule. Returns 0 (denied), 1 (read only) or 2 (read and write).

Example of what GetUnblockedUsers returns (hypothetical values):

EMP001||EMP002||EMP003

TCMSimpleTimeClock (codeunit 23044213)

Handles badge scans and employee authorization for the simple time clock, including authorization keys.

Method Parameters Returns What it does
ScanBarcode ptxtBarcode: Text, var ptxtBigLabel: Text, var ptxtSmallLabel: Text, var pbClockedIn: Boolean The var parameters Clocks an employee in or out from a badge scan on a simple time clock and returns the labels to show.
ScanBarcodeWithData As ScanBarcode, plus pbtData: BigText after ptxtBarcode The var parameters Same as ScanBarcode, with extra authentication data.
AuthorizeODATA pbtData: Text, ptxtBigLabel: Text, ptxtSmallLabel: Text, pcodTimeCardNo: Code[20], pcodEmployeeNo: Code[20], piDirection: Integer Text (JSON) Authenticates an employee from authentication data (for example, facial recognition), clocks them in or out, and returns the labels, time card, employee and direction as JSON. Only pbtData and piDirection (0 automatic, 1 in, 2 out) are used as inputs; the other parameters are returned in the JSON. See the example below.
Train pcodEmployeeNo: Code[20], pbtData: BigText None Adds or updates an employee’s authentication data, such as the face model the Time Clock interface builds when an employee is trained for facial recognition. The data is passed to the handler for the authorization type. See Set Up Facial Recognition.
GetAuthKeyForEmployeeODATA pcodAuthCode: Code[20], pcodEmployeeNo: Code[20], piIdentificationKey: Integer, ptxtAlternativeKey: Text, ptxtJsonEncodedAuthModel: Text Text (JSON) Returns an employee’s authentication key and model for an authorization type. See the example below.
GetAuthKeys var pbtAuthKeys: BigText pbtAuthKeys Returns all authentication keys and models.

Example of what AuthorizeODATA returns (hypothetical values):

{
  "isjsonmultipleoutputresponse": true,
  "ptxtBigLabel": "Example Employee",
  "ptxtSmallLabel": "",
  "pcodTimeCardNo": "TC000123",
  "pcodEmployeeNo": "EMP001",
  "piDirection": "1"
}

Example of what GetAuthKeyForEmployeeODATA returns (hypothetical values):

{
  "isjsonmultipleoutputresponse": true,
  "pcodEmployeeNo": "EMP001",
  "piIdentificationKey": "1",
  "ptxtAlternativeKey": "",
  "ptxtJsonEncodedAuthModel": "(the JSON-encoded model stored for the employee)"
}

TCMTimeCardHeader (codeunit 23044202)

Gets or creates the employee’s time card, logs out, ends the shift, closes the time card, and calculates card and weekly hours.

Method Parameters Returns What it does
getaTimeCard pcodEmployeeNo: Code[20], pcodClientConfigNo: Code[20] Code[20] Returns the employee’s open time card for the current shift, or creates one.
CalcTimeCardTimeODATA pcodTimeCardHeaderNo: Code[20] Text (JSON) Returns the hours on the time card and for the week. See the example below.
clockOffLastLine pcodTimeCardNo: Code[20] None Clocks off the last time card line if it’s still open.

Example of what CalcTimeCardTimeODATA returns (hypothetical values):

{"isjsonmultipleoutputresponse": true, "pdHoursThisWeek": 32.5, "pdHoursThisCard": 6.25}

TCMTimeCardLine (codeunit 23044203)

Clocks off a time card line. This codeunit and page 23044212 are published under the same service name, so Business Central exposes them as one TCMTimeCardLine web service.

Method Parameters Returns What it does
ClockOff precTimeCardLine: Record "SFI Time Card Line", pbForceAutoCalc: Boolean None Clocks off a time card line at the current time. Its first parameter is a record of the TCMTimeCardLine page’s source table, so Business Central adds ClockOff to the combined TCMTimeCardLine web service as an operation on a time card line record. Callers identify the line through the page service rather than passing a record from outside.

The server action web service does most of the work

Most key shop floor tasks, such as scanning a badge to sign in and start a time card, or scanning a routing barcode to clock on or off, go through one service: TCMServerBarcode, the server action web service. A badge scan, a routing barcode scan, or a menu action such as ClockOn, ClockOff or EndShift is sent to this service with the employee, time card and screen context.

Shop Floor Insight decides what to do in Business Central and returns a list of instructions for the client.

The other services mainly supply data to display, such as the dispatch list, time card lines, work instructions and components, or record output and consumption.

Was this article helpful?
0 out Of 5 Stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
5
How can we improve this article?
Please submit the reason for your vote so that we can improve the article.
Need help?
Tags:

Leave A Comment

Table of Contents
Go to Top