Keystone FX REST API

From KeystoneIntranet
Revision as of 12:58, 14 July 2023 by WikiAdmin (talk | contribs) (1 revision imported)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Overview

The FX REST API provides data used for dashboards. NOTE: These calls are likely to be modified. The budget data used in /KPIBUD is stored in a standalone SQLite database.

See: Keystone_REST_Server_(KServer) for more on KServer.

Example URIs:

http://127.0.0.1:8211/rest/kfxapi/v1/connection
http://127.0.0.1:8211/rest/kfxapi/v1/kpi?reportdate=2017-09-25
http://127.0.0.1:8211/rest/kfxapi/v1/kpibud?reportdate=2017-09-25

Connection Test API

ROOT: /rest/kfxapi/v1

connection

connection

tests connection with the server
{
    "kfxapi_v1": {
        "request_status": {
            "status": "200",
            "msg": "Keystone FX 2018.06 REST Server."
        }
    }
}

API v1

ROOT: /rest/kfxapi/v1

Functions

kpi

kpi
?reportdate= (Default = today)
?plantid= (Default = all) <accepts list of plants>

Returns a summary for Year to Date, Month to Date and daily quantity as well as load information.

kpibymo

kpibymo
?reportdate= (Default = today)
?plantid= (Default = all) <accepts list of plants>

Returns a summary by plant and ticket month.

kpiday

kpiday
?reportdate= (Default = today)
?begindate= (Default = start of today)

Returns summary of quantity, loads, and count of trucks and drivers.
{
	"kpiday": [
		{
			"plantno": "01",
			"periodyear": 2023,
			"periodno": 5,
			"producttype": "M",
			"ticketdate": "2023-05-08T00:00:00.000Z",
			"qtysold": 13,
			"truckdays": 1,
			"driverdays": 1,
			"loads": 1
		}
	]
}

kpimonth

kpimonth
?begindate= (Default = start of today)
?enddate= (Default = today)

Returns summary of quantity, loads, and count of trucks and drivers.

KPIBUD

kpibud
?reportdate= (Default = today)

Returns a summary for Year to Date, Month to Date quantity as well as load information.

Unlike KPI these values need to be processed to determine the correct YTD, MTD and Current Day budgets. The "workdays" section of the return values provide the additional required values.

  • 'Day:' Multiply Monthly value by workdaytratio
  • 'Month:' Multiply Monthly value by workmonthration
  • 'Year:' Add Yearly value to caclulated month value. (Yearly values include up to, but not the current month).
{
{
    "kpibud": [
        {
            "ymd": "Y",
            "plantno": "10",
            "qtysold": 124211,
            "driverdays": 4211,
            "loads": 12100
        },
 ...
        {
            "ymd": "M",
            "plantno": "16",
            "qtysold": 4102,
            "driverdays": 189,
            "loads": 418
        },
...
    "workdays": [
        {
            "workdayofmonth": 21,
            "workdaysthismonth": 25,
            "workdayratio": 0.04,
            "workmonthratio": 0.84,
            "reportdate": "2017-09-25T00:00:00.000Z"
        }
    ]
}


Budget Table

Keystone includes a budget table called ARTSLSBUD with the following fields:

  • PERIOD_YEAR
  • PERIOD_NO
  • PLANT_NO
  • PRODUCT_TYPE
  • QTY_SOLD
  • SALES
  • TRUCKDAYS
  • DRIVERDAYS
  • LOADS

KSSLSBUD

ksslsbud

Returns raw data from the Keystone sales budget table
{
    "ksslsbud": [
        {
            "plantno": "01",
            "periodyear": 2019,
            "periodno": 1,
            "producttype": "M",
            "qtysold": 1100,
            "truckday": 20,
            "driverdays": 20,
            "loads": 110
        },
        {
            "plantno": "01",
            "periodyear": 2019,
            "periodno": 2,
            "producttype": "M",
            "qtysold": 1200,
            "truckday": 21,
            "driverdays": 21,
            "loads": 120
        },
        {
            "plantno": "01",
            "periodyear": 2019,
            "periodno": 3,
            "producttype": "M",
            "qtysold": 1300,
            "truckday": 22,
            "driverdays": 22,
            "loads": 130
        },
        {
            "plantno": "02",
            "periodyear": 2019,
            "periodno": 1,
            "producttype": "M",
            "qtysold": 500,
            "truckday": 10,
            "driverdays": 10,
            "loads": 50
        },
        {
            "plantno": "02",
            "periodyear": 2019,
            "periodno": 2,
            "producttype": "M",
            "qtysold": 510,
            "truckday": 11,
            "driverdays": 11,
            "loads": 51
        },
        {
            "plantno": "02",
            "periodyear": 2019,
            "periodno": 3,
            "producttype": "M",
            "qtysold": 520,
            "truckday": 12,
            "driverdays": 12,
            "loads": 52
        }
    ]
}

KSSLSBUD (post)

ksslsbud

Post Budget to the Keystone sales budget table. Structure matches the GET.

tickettimes

tickettimes
?begindate= (Default = today)
?enddate= (Default = today)

Returns time information for each ticket.

dispatchtime

dispatchtime
?begindate= (Default = today)
?enddate= (Default = today)
?plantid= (Default = all) <accepts list of plants as of 3.6.1>

Returns multiple summarizations of dispatch time analysis for FX style dispatch time dashboards.
http://127.0.0.1:8211/rest/kfxapi/v1/dispatchtime?begindate=2017-09-25&enddate=2017-09-25&plantid=01,02


ontimebystatus
(dispatchtime)

Based on a threshold (currently 5 minutes) - returns the count of early, ontime and late in each status. When the actual time is missing the status will not be counted, therefore the total may be more than the sum of the 3 individual counts.

  • plantno
  • statusname
  • statusno
  • early Count of early loads
  • ontime Count of on time loads
  • late Count of late loads
  • total Count of all loads
timeinstatuscounts
(dispatchtime)

Based on a threshold (currently 5 minutes) - returns the count of loads the are quicker or take longer or take the expected time for a status. When either of the 2 actual times is missing the status will not be counted, therefore the total may be more than the sum of the 3 individual counts.

  • plantno
  • statusname
  • statusno
  • quicker Count of loads that are quicker than expected
  • normal Count of loads that take the expected time
  • longer Count of loads that take longer than expected
  • total Count of all loads
timeinstatusminutes
(dispatchtime)

Returns the average time per minute for each status. When either of the 2 actual times is missing the status will not be counted, therefore the total may be more than the loads used in the calculation.

  • plantno
  • statusname
  • statusno
  • totalminutes Sum of all minutes in this status
  • loads Count of all loads
  • minutesperload Average minutes in status per load
  • targetminutesperload Average minutes in status per load
  • total Count of all loads


   "timeinstatusminutes": [
        {
            "plantno": "11",
            "statusname": "Batch",
            "statusno": 1,
            "totalminutes": 2044,
            "targetminutes": 168,
            "loads": 89,
            "minutesperload": 11.97,
            "targetminutesperload": 9.89,
            "totalloads": 89
        },
        {
            "plantno": "11",
            "statusname": "Plant Wash",
            "statusno": 2,
            "totalminutes": 1109,
            "targetminutes": 445,
            "loads": 87,
            "minutesperload": 12.75,
            "targetminutesperload": 5,
            "totalloads": 89
        },
...
dloadsyardsbyhour
(dispatchtime)

Returns an hourly count of loads and summary of yards. Currently this does not adjust for the number of days included in the range (subject to change) 

    "loadsyardsbyhour": [
        {
            "plantno": "11",
            "batchhour": 6,
            "loads": 6,
            "yards": 64
        },
        {
            "plantno": "11",
            "batchhour": 7,
            "loads": 7,
            "yards": 70
        },
...

materialrequiredbyhour

materialrequiredbyhour
?reportdate= (Default = today)
?plantid= (Default = all) <accepts list of plants as of 3.6.1>

Sample call: http://127.0.0.1:8211/rest/kfxapi/v1/materialrequiredbyhour?reportdate=2017-09-25&plantid=11

  • required Amount required for the whole day.
  • requiredremain Amount required for unshipped loads. A load is considered shipped once it reaches status 2 which triggers when batch weights were received.

sample response: 

{
matreqsum: [
{
plantno: "11",
hour: 5,
ingtype: "Cement",
required: 6721,
requiredremain: 0,
unit: "LB",
ingredient: "CMX1"
},
{
plantno: "11",
hour: 6,
ingtype: "Cement",
required: 20163,
requiredremain: 0,
unit: "LB",
ingredient: "CMX1"
},...
],
matreqday: [
{
plantno: "11",
ingtype: "Cement",
required: 6721,
requiredremain: 0,
unit: "LB",
ingredient: "CMX1"
}
]
}

batchvariation

batchvariation
?begindate= (Default = beginning of today)
?enddate= (Default = end of today)
?plantid= (Default = all) <accepts list of plants> 

{
	"batchvariation":[
		{
			"plantno":"01",
			"targetweightsum":1133,
			"actualweightsum":1135,
			"targetweightperld":566,
			"actualweightperld":567,
			"ingredtype":"C",
			"ingredid":"CEM-1",
			"weightums":"LB",
			"loadsize":1,
			"loads":2,
			"varpct":0.176522508263588
		}
	]
}
Returns variation between targetweight and actualweight for a given batch.

trucksbystatus

added 3.6.1

trucksbystatus
?begindate= (Default = beginning of today)
?enddate= (Default = end of today)
?plantid= (Default = all) <accepts list of plants>

Sample call: http://127.0.0.1:8211/rest/kfxapi/v1/trucksbystatus?begindate=2017-09-25&enddate=2017-09-25&plantid=01,02

  • inservice The number of clocked-in trucks
  • atplant The number of trucks that have not shipped yet or have returned to the plant

sample response: 

{
    "trucksbystatus": [
        {
            "plantno": "01",
            "inservice": 3,
            "ticketed": 1,
            "loaded": 0,
            "tojob": 0,
            "onjob": 0,
            "pouring": 0,
            "jobwash": 0,
            "returning": 0,
            "atplant": 2
        },
        {
            "plantno": "02",
            "inservice": 5,
            "ticketed": 0,
            "loaded": 0,
            "tojob": 0,
            "onjob": 0,
            "pouring": 0,
            "jobwash": 0,
            "returning": 0,
            "atplant": 5
        }
    ]
}

trucksinstatus

added 3.6.99.69

trucksinstatus
?begindate= (Default = beginning of today)
?enddate= (Default = end of today)
?plantid= (Default = all) <accepts list of plants>
?status=#

Sample call: http://127.0.0.1:8211/rest/kfxapi/v1/trucksinstatus?PlantId=01,02,03,04,05&Status=7

  • projtime The projected on-job time (status between 1 and 3) or projected at-plant time (status between 4 and 7)
  • timeinstatus The number of minutes the truck has been in the requested status
  • timeremaining The number of minutes the truck has remaining in the requested status (can be negative which indicates that the truck is late)

sample response: 

{
    "trucksinstatus": [
        {
            "truckno": "201",
            "plantno": "02",
            "projtime": "2021-10-11T15:00:18.000Z",
            "timeinstatus": 4,
            "timeremaining": 5
        }
    ]
}

battol

battol
?BeginDT= (Default = beginning of today)
?EndDT= (Default = end of today) 

{
	"battol":[
		{
			"plantno":"01",
			"ingtype":"A",
			"ingtypedesc":"Aggregate",
			"blwtol":0,
			"intol":12,
			"abvtol":4,
			"loaddate":"2023-03-01T00:00:00.000Z"
		}
	]
}
Returns Batch Tolerance.
Retrieved from "http://in.compucrete.com/index.php?title=Keystone_FX_REST_API&oldid=364"