JOB API Queries

Purpose and Intended Audience/Use

This is intended for Shoplogix and customer Information Technology staff to review and understand the capabilities of using Shoplogix's Job API query to pull job data from Shoplogix. This data includes counts, uptime, performance, downtime and other data. Data can be rolled up on a job name basis or each individual run can be its own record.

The purpose of an API is to provide a consistent interface to the underlying data with no direct dependencies on the schema or format of that data. This provides the customer protection of their investment as any programming and data integration will not be impacted by changes made to the Shoplogix's underlying infrastructure.

This is a pull from Shoplogix's server. Using a http:// query, the customer can pull back XML or JSON data. That data can then be put into a Data Lake and then manipulated to the data per their unique integration needs. This is not an active push of data from the Shoplogix server.

The document will provide details of the syntax of the query and show detail examples of the data returned. Please note that the focus of this document is specific to job API calls. There are additional API calls to pull specific metrics based on shift and job. However, that data is usually a subset of the data shown. The job API was create to provide a simpler way to retrieve data for a job with one query. There is additional documentation for those API calls.

Future Enhancements

Enhancements for the job API are subject to review by the Shoplogix Product Team prior to escalation and the dedication of development time. Please communicate such to your Shoplogix Professional Services or Customer Success Staff.

Please note: All query results are shown using ?format=xml option.

Current Job Endpoint

GET: /Web/Api/Export/CurrentJob

Returns the current job record for each machine.

Query Parameters:

Note: parameter names and values are case insensitive.

Optional:

format: Format of the result. Valid formats are: json [Default], xml

areas: Comma separated list of Area Id’s to include in the result data. See Appendix A.

machines: Comma separated list of Machine Id’s to include in the result data. See Appendix B.

if both areas and machines are specified then machines parameter will be used and areas parameter will be ignored.

syntax: ?format=xm&area=X,Y or ?machines=XXXX, YYYY,ZZZ

XML format and just two machines

/Web/Api/Export/CurrentJob?format=xml&machines=35468ADD-3D96-F90B-B828-AB0CE011BA28, C6816448-9C21-797D-2B55-DA516CBF60D0"

XML format and all machines in areas 5 and 9

/Web/Api/Export/CurrentJob?format=xml&areas=5,9

json format and all machines

/Web/Api/Export/CurrentJob

For a machine with a currently active job - this data is returned. XML format shown

</Job>

</JobInstances>

</Machines>

MachineID = Server Identifier for the machine

MachineName = Machine label on the server

Job Name = the primary key identifer for the current job. May or may not be unique

Instance = unique identifier for the occurrence of the job.

Start / Stop = the job's start and stop times. Stop time will equal the query time as these are current records.

Filters = these are secondary keys used to identify work. Could be color, package size, customer for example

For a machine with NO current job - this data will be returned.

</Machine>

MachineID = Server Identifier for the machine

MachineName = Machine label on the server

Job Name / Instance Endpoints

As mentioned above, each job has a job identifier, which may or may not be unique, and job instance number, an unique number which identifies that run of the job. Depending upon the work identifier used, a job may or may not have multiple instances. In the queries you can do things by job name or job name and instance. Your data will determine how the data is returned to you.

Work Order Number Identifier Scenario

The job name is generated in ERP system and unique

Job: WO023432 Instance: f250ebc5ddcf46bca11cbb08aae5045c

Job: WO023433 Instance: f637af3eb75548b1b625179fe815328c

In this case, job name to instance is one:one. If you do a rollup on job name or asked for each instance for each job, you would get same results.

Mold Number Identifier Scenario

The job name is generated in ERP system and unique

Job: 3234-CR Instance: f250ebc5ddcf46bca11cbb08aae5045c

Job: 3234-CR Instance: f637af3eb75548b1b625179fe815328c

Job: 3234-CR Instance: b4a7286c943b40ad8b74b4dc7c7e2768

In this case, job name to instance could be one:many depending on the time period of the query. If you do a job name rollup, the query will summarize all three runs into one record. If you request by job name/instance, it will break out each individual run for you.

Job Name Rollup Endpoint

GET: /Web/Api/Export/Jobs/Start/{start:slxdatetime}/End/{end:slxdatetime}

Returns all job records rolled up based on the job name.

Job Name	Instance	Breakout	<JobInstance> Tag
All Job Names	All Instances	Rolled up by Job Name	Not in data

Query Parameters:

Note: parameter names and values are case insensitive. Date format can be YYYYMMDD or YYYYMMDDTHHMMSS

Optional: format: Format of the result. Valid formats are: json [Default], xml

syntax: ?format=xml

Job Name Single Endpoint

GET: /Web/Api/Export/Job/{jobName}/Start/{start:slxdatetime}/End/{end:slxdatetime}

Returns a single job record rolled up based on the job name.

Job Name	Instance	Breakout	<JobInstance> Tag
Specificed Name	All Instances	Rolled up by Job Name	Not in data

Query Parameters:

Note: parameter names and values are case insensitive. Date format can be YYYYMMDD or YYYYMMDDTHHMMSS

Optional: format: Format of the result. Valid formats are: json [Default], xml

syntax: ?format=xml

Job Name All Instances Endpoint

GET: /Web/Api/Export/Job/{jobName}/Instances/Start/{start:slxdatetime}/End/{end:slxdatetime}

Returns all job instances matching the jobName broken out by each instance.

Job Name	Instance	Breakout	<JobInstance> Tag
Specified Name	All Instances	By Instance	In data

Query Parameters:

Note: parameter names and values are case insensitive. Date format can be YYYYMMDD or YYYYMMDDTHHMMSS

Optional: format: Format of the result. Valid formats are: json [Default], xml

syntax: ?format=xml

Job Name Single Instance Endpoint

GET: /Web/Api/Export/Job/{jobName}/instance/{jobInstance}/Start/{start:slxdatetime}/End/{end:slxdatetime}

Returns a single job record instance based on the job name / instance key provided

Job Name	Instance	Breakout	<JobInstance> Tag
Specified Name	Specified Instance	Specified Instance	In data

Query Parameters:

Note: parameter names and values are case insensitive. Date format can be YYYYMMDD or YYYYMMDDTHHMMSS

Optional: format: Format of the result. Valid formats are: json [Default], xml

syntax: ?format=xml

Job All Instances Endpoint

GET: /Web/Api/Export/Jobs/Instances/Start/{start:slxdatetime}/End/{end:slxdatetime}

Returns all job instances of all jobs broken out by each instance.

Job Name	Instance	Breakout	<JobInstance> Tag
All Jobs	All Instances	By Instance within Job	In data

Query Parameters:

Note: parameter names and values are case insensitive. Date format can be YYYYMMDD or YYYYMMDDTHHMMSS

Optional: format: Format of the result. Valid formats are: json [Default], xml

syntax: ?format=xml

Data from query

For simplicity's sake, will go through the sections one by one. For samples, see sample query section.

<Machines> Tag with machine information

MachineID = Server Identifier for the machine

MachineName = Machine label on the server

<JobNames> Tag with Job time information

Job Name = the primary key identifer for the current job. May or may not be unique

Instance = unique identifier for the occurrence of the job. Note: depending on query, may not be seen.

Start / Stop = the job's start and stop times. Stop time will equal the query time as these are current records.

Filters = these are secondary keys used to identify work. Could be color, package size, customer for example

Metrics: All metrics are for the time period of the query. This may or may not be a partial record of data.

The metrics only include the timeframe of the query. When there have been multiple instances, see <Jobs> section, those statistics are rolled up into the metrics section.

Total: = total count for the query

Scrap = scrap count for the query.

OEE = OEE with capacity time removed from the calculation (breaks/unscheduled day) .

OEEc = OEE * Capacity (explained later)

Availablity = Uptime/Scheduled time

Performance = Total / (Expected Rate * Uptime)

PerformanceC = Performance * Capacity

Quality = Good / Total

QualityC = Quality * Capacity

Capacity = Schedule Time / Total Time

OeeUptimeHours = Hours in uptime state during schedule time.

UptimeHours = Hours in uptime state both scheduled and non-scheduled.

DowntimeHours = Hours in downtown state

SetupHours = Hours in setup state (this is if Setup is configured to be different Machine State)

SpeedLossSeconds = seconds gained or lost due to variation in performance.

CycleTimeSeconds = Uptime in Seconds / Total

<Jobs>

<Job Name="Part 1357" Start="06/01/2020 12:00:00.000" End="06/11/2020 12:30:35.462" Instance="4ba6ce6ceb8d48bd9e69035d0a13c68f" Duration="48.000000000000014" PartialJobRecord="1"

ExpectedRate="180" ExpectedProduction="1000" CycleFactor="1" Filter1="Mold 7375"/>

Note: Not all files may appear depending on job record, job status and time parameters of the query.

There will be a <Jobs> record for each and every instance of the job name within the query period. There will alway be one <Jobs> record but there could be more if the query is a rollup based on the job name.

<Jobs> Job Metadata

MachineID = Server Identifier for the machine

MachineName = Machine label on the server

Job Name = the primary key identifer for the current job. May or may not be unique

Start = start time of the job. (Note this is for the job and the query timeframe)

Start = end time of the job.

Instance = unique identifier for the occurrence of the job.

Duration = the job's durationstart and stop times. Stop time will equal the query time as these are current records.

Partial JobRecord = 1 indicator the job's start or end time outside the query. If missing, complete record.

CurrentJob = 1 indicates the job is still running. If missing, not an active job.

ExpectedRate = expected production rate in pieces per hour

ExpectedProduction = expected production rate amount

ExpectedSetup = expected setup time in hours

CycleFactor = multiplier for production count (4 cavity mold would have cycle factor = 4)

LineCycleFactor = multiplier for production count if used in Line Mode configuration

FinishedGoodsCycleFactor = multiplier for final product form

InventoryCycleFactor = multiplier incoming product form

Example: Packaging Line

Cycle Factor - Bottles InventoryCycle Factor - Fluid Ounces FinishedGoodsCycleFactor - cases

RuntimeExpected = Expected Production / Expected Rate

Scrap CycleFactor = multiplier for scrap counts

FilterX = secondary job keys

<Subjobs>

These appears if the job has components, such as a left-hand and right-part number for each production cycle.

<ScrapReasons>

Note: Scrap with no Name will be added to scrap for job record, but not shown here. Metrics Total="10549" Scrap="9" and the record below would indicate two (2) pieces of scrap with no reason assigned to them.

<ScrapReasons> Scrap reported during the time of the query

Name= Scrap Label

Group= Category associate for the scrap (may or may not exist - Operational, Paint is example of Group)

Amount=number of scrap

<States>

The name, classification, duration in hours and transitions of the job during the query time period

State Name = Label for the machine state

Classification = Performance or Availability or Capacity.

Duration=Time in hours

Occurences=Number of times transitioned into that state

<Reasons>

The name, classification, duration in hours and transitions of downtime reasons for the job during the query time period.

Note: 0 indicates the machine was in that state at the start of the query.

Reason Name = Label for downtime

Classification = Performance or Availability or Capacity.

Duration=Time in hours

Occurrences=Number of times transitioned into that state

<StateReasons>

The name, classification, duration in hours and transitions of the job during the query time period included those with no classification.

Note: 0 indicates the machine was in that state at the start of the query. The second item time has no ReasonName assigned to it. That time will show up on the <StateReasons> data with "" ReasonName and will be included in the total Idle time on the <States> data. However, it will not be in the <Reason> as Reasons data only includes data that have a ReasonName.

StateName = Machine Status

ReasonName = The downtime or setup reason name

Classification = Performance or Availability or Capacity of the ReasonName.

Duration=Time in hours

Occurences=Number of times transitioned into that state

<Comments>

Free form text added to downtime or scrap reason during the query timeframe.

Downtime Comment

Scrap Comment

MachineId = MachineId on server

Start = Start time of the hour comment was made.

End = End time of the hour comment was made..

Comment =Text entered

Duration = If associated with a downtime, the length of that downtime.

Occurences= Number of times the associate state in the hour.

Type= Machine State for the downtime

Reason = Downtime reason or scrap reason name.

Note: Currently a place holder.

Query Examples:

Machine has Job 13420. Query Timeframe from 2020/06/12 to 2020/06/15. Three runs of that job in the timeframe. So you will see three instances. The first run started before the query start time, so it is flagged as a PartialJobRecord. The second run was complete inside the time query, so no flag. The third run has an end data beyond the query timeframe. All jobs are padded out a year at start time. And there is also a CurrentJob flag indicating this job is currently running on the machine. There will be a <JobInstances></JobInstances> when Instance or Instances is used in the query.

Query to show the job with all instances rollup up. Web/Api/Export/Job/13420/Start/20200612/End/20200615?format=xml

Query to show the job with each instance as its own record. Web/Api/Export/Job/13420/instances/Start/20200612/End/20200615?format=xml

<JobInstances>

Query to show one specific instance of the job Web/Api/Export/Job/13420/instance/fe6feb84b31c466bb9e821b91f662803/Start/20200612/End/20200615?format=xml

<JobInstances>

Web/Api/Export/Job/13420/Start/20200612/End/20200615?format=xml

<Jobs>

</Jobs>

</States>

</Reasons>

</StateReasons>

</Metrics>

</Job>

</JobNames>

</Machine>

Web/Api/Export/Job/13420/Instances/Start/20200612/End/20200615?format=xml

Instance 1

<JobInstances>

<Jobs>

</Jobs>

</States>

</StateReasons>

</Metrics>

</Job>

Instance 2

<Jobs>

</Jobs>

</States>

</Reasons>

</StateReasons>

</Metrics>

</Job>

Instance 3

<Jobs>

</Jobs>

</States>

</Reasons>

</StateReasons>

</Metrics>

</Job>

</JobInstances>

</Machine>

/Web/Api/Export/Job/13420/instance/fe6feb84b31c466bb9e821b91f662803/Start/20200612/End/20200615?format=xml

<JobInstances>

<Jobs>

</Jobs>

</States>

</Reasons>

</StateReasons>

</Metrics>

</Job>

</JobInstances>

</Machine>