API docs by Redocly

Pitram Restful Integration Services (v1)

Download OpenAPI specification:Download

Version: 1.15.0.8

Please report any documentation errors to support@micromine.com

Routes labeled with 'Updates Only available'

These routes are designed to provide 'updates only' or 'deltas' when a time is passed back. The idea is that the first query gets passed back a resultsTimeUTC. If this is then passed back to the next query, then that query will only return updates since that time. When the results are a delta, the updatesOnly flag is set to true.

When polling for updates only by using the resultsTimeUTC, you should not change any of the filter request parameters, or the results are not guaranteed to be correct.

Note: A shift change, or a change to relevant reference data (to the information supplied in the route results) may cause a full set of results to be returned (in which case the updatesOnly flag will be returned as false)

Passing array of items in the request

Some routes support the passing of an array of items via either a query string, or as a body parameter. To pass an array using Swagger, use new line as the separator inside the input field.

DrillAndBlast

Request design grades from Drill and Blast

Request design grades from the Pitram Portal Drill and Blast module. A list of locations to include must be supplied, all other parameters are optional.

  • Security Resource Id : v1/drill-and-blast/design-grades/search

  • Security Resource Action : post

  • DCWS Version: 10.0.0.147

Authorizations:
oauth2
header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Request Body schema:
required

Request parameters.

queryTime
string <date-time>

Query time. If supplied, results included are before and including this time.

includeDescriptions
boolean

Can set to false to omit descriptions. Defaults to true.

locations
Array of strings

Location to include in the results

elements
Array of strings

Elements filter. If not supplied, all elements are returned.

Responses

Request samples

Content type
{
  • "queryTime": "2019-08-24T14:15:22Z",
  • "includeDescriptions": true,
  • "locations": [
    ],
  • "elements": [
    ]
}

Response samples

Content type
{
  • "locations": [
    ],
  • "error": {
    }
}

Equipment

Gets equipment location allocation event information for either a given time or for a given time range

Use querytime to get the location at particular time. Use start/end to get all location allocations between a time range. May optionally be filtered by one or more result fields.

  • Security Resource Id : v1/equipment/allocations/locations
  • Security Resource Action : get
  • BMWS Version: 4.3.0
  • DCWS Version: 4.3.0
Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to be updated. Must be a valid equipment code that exists in Equipment Reference Data.

query Parameters
querytime
string

(Optional) If this is set, then we want a location at this time. If not set, we get the latest known location

start
string

(Optional) If supplied, must be a valid ISO 8601 string and be less then 'end'. If not supplied, the start of the current shift will be used. Cannot be used with querytime parameter

end
string

(Optional) The end time for the range of data. If not supplied, max date time will be used is now current shift), this will return an error code 'BMWS_0021'

fields
string

(Optional) A list of fields to filter on. Must be a valid field name within the result set

rosters
string

(Optional) Comma delimited list of shift roster codes to filter the results. If not supplied, the Business Model Server default roster will be used. If supplied, each comma delimited string must be a valid token in the ShiftRoster reference data group.

Responses

Response samples

Content type
{
  • "results": [
    ]
}

Creates an allocate equipment to location event

  • Security Resource Id : v1/equipment/allocations/locations
  • Security Resource Action : post
  • BMWS Version: 3.46.2
Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to be updated. Must be a valid equipment code that exists in Equipment Reference Data.

Request Body schema:
required

Allocation data

locationCode
required
string

The code of the location to allocate the equipment to. Must be a valid code in the Location reference data group

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "locationCode": "string",
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Get equipment details information (no measure supplied).

This is the same information you will see in Data Acquisitions equipment details dialog

  • Security Resource Id : v1/equipment/currentshift/details
  • Security Resource Action : get
  • BMWS Version: 4.8.0
Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The equipment to get details for. The default measure of the equipment will be used for measure info

query Parameters
cu
string

(Optional) The culture used to format strings and dates. May also use Accept-Language header.

rosters
string

(Optional) Comma delimited list of shift roster codes to filter the results. If not supplied, the Business Model Server default roster will be used.If supplied, each comma delimited string must be a valid token in the ShiftRoster reference data group.

date-time-format
string

Optional date time format

loc-attribs
string

Optional comma delimited list of location attributes This can include an "empty" element to indicate where we want the attributes in relation to the location (i.e. before or after)

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "results": [
    ]
}

Get equipment details information with measure.

This is the same information as in Data Acquisitions equipment details dialog

  • Security Resource Id : v1/equipment/currentshift/details
  • Security Resource Action : get
  • BMWS Version: 4.6.0
Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to get details for. Must be a valid equipment code that exists in Equipment Reference Data.

measureCode
required
string

The Measure code to use where measures are included in the details.

query Parameters
cu
string

(Optional) The culture used to format strings and dates. May also use Accept-Language header.

rosters
string

(Optional) Comma delimited list of shift roster codes to filter the results. If not supplied, the Business Model Server default roster will be used.If supplied, each comma delimited string must be a valid token in the ShiftRoster reference data group.

date-time-format
string

Optional date time format

loc-attribs
string

Optional comma delimited list of location attributes This can include an "empty" element to indicate where we want the attributes in relation to the location (i.e. before or after)

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "results": [
    ]
}

Get a list of equipment measures in the current shift.

Total summed measure values over the current shift, grouped into 15 minute time intervals. Note that the resource returns only equipment measures, not locations. These measures are summed measures, not cumulative measures or movements.

Updates only available in this route

  • Security Resource Id : v1/equipment/currentshift/measures/groupedbytime

  • Security Resource Action : get

  • BMWS Version: 4.6.0

Authorizations:
oauth2
path Parameters
measureCode
required
string

The measure to get results for

query Parameters
previousResultsTimeUtc
string

(Optional) Time passed back from a previous call to this route. If supplied, we can be supplied with just any updates

rosters
string

(Optional) Comma delimited list of shift roster codes to filter the results. If not supplied, the Business Model Server default roster will be used.If supplied, each comma delimited string must be a valid token in the ShiftRoster reference data group.

Responses

Response samples

Content type
{
  • "results": [
    ],
  • "currentShiftStartTime": "string",
  • "updatesOnly": true,
  • "resultsTimeUtc": "string"
}

Gets a list of equipment status type percentages.

Updates only available in this route.

Note: The results include a status type colour. To get this, the status type will need the DisplayColour attribute deployed, and then configured.

  • Security Resource Id : v1/equipment/currentshift/statustypes/percentages

  • Security Resource Action : get

  • BMWS Version: 4.6.0

Authorizations:
oauth2
query Parameters
functionsfilter
string

(Optional) A comma delimited list of of equipment functions to filter upon (e.g. hauling). Cannot be used with equipmentActiveList.

previousResultsTimeUtc
string

Time passed back from a previous call to this route. If supplied, we can be supplied with just any updates.

equipmentActiveList
string

(Optional) An active list of equipment to filter upon. Cannot be used with functionsfilter. Only available if running Pitram server (BMS) >= 11.0, otherwise it is ignored.

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "results": [
    ],
  • "updatesOnly": true,
  • "resultsTimeUtc": "string"
}

Get equipment summary information, shaped and filtered by input parameters

Note that if multiple filters are used, the results are the data common to all filters.

Updates only available in this route.

This route is designed to provide "updates only" or "deltas" when a time from the previous request is passed back via the previousResultsTimeUtc parameter. The idea is that the first query gets passed back a resultsTimeUTC.If this is then passed back to the next query, then that query will only return updates since that time. When the results are a delta, the updatesOnly flag is set to true.

  • Security Resource Id : v1/equipment/currentshift/summary

  • Security Resource Action : get

  • BMWS Version: 7.0.0

Authorizations:
oauth2
query Parameters
codes
string

(Optional) Comma delimited list of individual equipment codes to filter upon.

activelists
string

(Optional) Comma delimited list of equipment active lists to filter upon.

functions
string

(Optional) Comma delimited list of equipment functions to filter upon.

models
string

(Optional) Comma delimited list of equipment models to filter upon.

previousResultsTimeUtc
string

(Optional) The time passed back from a previous query, via the resultsTimeUtc field, and in ISO 8601 UTC format. Allows update only results.

summedMeasures
string

(Optional) A comma delimited list of the summed measures to include. You can use the @display wildcard to return the display measures configured in the reference data. If null or empty, no measures included.

measureActiveLists
string

(Optional) A comma delimited list of the measure active lists to include.

attributes
string

(Optional) List of attributes from equipment and equipment model reference groups to include in the results. Currently handle only simple attributes (all converted to a string value). Also does not currently detect dynamic attribute updates. If null or empty, no attributes included.

fields
string

(Optional) A comma delimited list of the fields to include. Valid values are location, status, statustype, statuscolour, cyclestatus, prioperator, model, function, operatinghours, statusgroup and waypoints. Note that model and function are separate to the list of attributes because a Code/Description pairing is required which attributes don't currently support.

rosters
string

(Optional) Comma delimited list of shift roster codes to filter the results. If not supplied, the Business Model Server default roster will be used. If supplied, each comma delimited string must be a valid token in the ShiftRoster reference data group.

maxWaypoints
integer <int32>

(Optional) The max number of waypoints to include per equipment.

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "resultData": [
    ],
  • "fieldDescriptions": [
    ],
  • "updatesOnly": true,
  • "resultsTime": "string"
}

Request either the equipment's cycle status at a point in time, or a list of cycle status events within a time range.

If query time is used we get a single result with cycle status at that time. This is not information about the event that set the status, so we get no roster, and the event time just reflects back whatever query time was used. The event time being set as the query time is confusing, but we need to leave so we don't break the existing behaviour.

If start and end are used, we get a list cycle status events (if any) within the start/end range.

Notes -

  • The input parameter queryTime cannot be used with the parameters start and end.
  • as stated above, if query time is used, we do NOT get an event time returned. The event time will just reflect back the query time used in the request, including an empty string if no query was set.

Token Security details:

  • Security Resource Id : v1/equipment/cyclestates
  • Security Resource Action : get

Minimum versions:

  • BMWS Version: 8.0.0.78
  • DCWS Version: 4.0.0.459
Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to be updated. Must be a valid equipment code that exists in Equipment Reference Data.

query Parameters
querytime
string

(Optional) If this is set, then we want a cycle status at this time. If not set, we get the latest Cycle status. Must be a valid ISO 8601 UTC string

start
string

(Optional) The start time for the range of data. If not supplied, start of current shift will be used. Must be a valid ISO 8601 UTC string

end
string

(Optional) The end time for the range of data. If not supplied, max date time will be used is now current shift), this will return an error code 'BMWS_0021'. Must be a valid ISO 8601 UTC string

fields
string

(Optional) Comma delimited string to filter top-level fields. Must be a valid field name within the result set.

rosters
string

(Optional) Comma delimited list of shift roster codes to filter the results. If not supplied, the Business Model Server default roster will be used.If supplied, each comma delimited string must be a valid token in the ShiftRoster reference data group.

Responses

Response samples

Content type
{
  • "results": [
    ]
}

Create an equipment cycle status event.

Updates the cycle status of a Pitram equipment item.

  • Security Resource Id : v1/equipment/cyclestates
  • Security Resource Action : post
  • BMWS Version: 3.46.2
Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to be updated. Must be a valid equipment code that exists in Equipment Reference Data.

Request Body schema:
required

Cycle status event data

statusCode
required
string

The code of the primary status to set. Must be a valid status code in the Status reference data group

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "statusCode": "string",
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Gets a list of locations defined by destinationEq in reference data.

Gets a list of locations defined by destinationEq in reference data for the given equipment token, or all locations if destinationEq has no values.

  • Security Resource Id : v1/equipment/destinations

  • Security Resource Action : get

  • BMWS Version: 4.6.0

Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to be updated. Must be a valid equipment code that exists in Equipment Reference Data.

Responses

Response samples

Content type
{
  • "results": [
    ]
}

Search for equipment primary states (events) in a time range.

Grouped by Equipment codes and then by their event times descending.

Note that If multiple filters are used, the results are the data common to all filters.

  • Security Resource Id : v1/equipment/primarystatus/summary
  • Security Resource Action : get
  • BMWS Version: 4.15.0 (without dateTimeType parameter), 4.15.1, 4.16, 7.0 (isEdited, eventKey added to response)
Authorizations:
oauth2
query Parameters
equipmentCodes
string

Equipment codes to include. Comma delimited.

primaryStates
string

Primary states to filter results by. Comma delimited.

primaryStatusCategories
string

Primary status categories to filter results by. Comma delimited.

primaryStatusTypes
string

Primary status types to filter results by. Comma delimited.

primaryStatusGroups
string

Primary status groups to filter results by. Comma delimited.

dateTimeFrom
string

Date time from to get results for.

dateTimeTo
string

Date time to to get results for.

dateTimeType
string

If equals to "serverLogged" it means dateTimeFrom and dateTimeTo look at the server logged time, while by default they look at the event creation time

Responses

Response samples

Content type
{
  • "primaryStates": [
    ]
}

Create an equipment exclusive status event

This is used for an equipment status other than a Primary status or Cycle status (for example Repair states).

  • Security Resource Id : v1/equipment/exclusivestates

  • Security Resource Action : post

  • BMWS Version: 3.46.2

Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to be updated. Must be a valid equipment code that exists in Equipment Reference Data.

Request Body schema:
required

Exclusive status event data

statusCode
required
string

The code of the status to set. Must be a valid status code in the Status reference data group

statusClassCode
required
string

The status classification code. Note that this is not a code from the Category group in ref data. For locations, this is from the Location Classification group. For equipment, the only use is for Repair states.

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "statusCode": "string",
  • "statusClassCode": "string",
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Search for Maintenance Comments for a either list or all equipment.

For the given equipment codes(or all if none are provided), the call finds all the equipment primary status change events that have occurred within the given date time range and returns the comments associated with those events.

Each item result should have:

  • Equipment code
  • Date time of the equipment status change event
  • Status of the equipment event
  • Date time of the comment
  • The Comment field of the comment
  • The comment

The date time range provided in the post parameters is used on the equipment status change event's date time; it is not used as a filter on the comment's date time.

The call checks and goes into both the BMS and the Dome databases:

  • The call goes to the BMS and checks for results with the given date time range.
  • The call then goes to DOME and checks for results with the given date time range.
  • The results from BMS and DOME are combined and returned.

Token security information

  • Security Resource Id : v1/equipment/maintenancecomments
  • Security Resource Action : post

Pitram servers minimum Versions

  • BMWS Version: 4.15.0
  • DCWS Version: 4.15.0
Authorizations:
oauth2
query Parameters
start
required
string <date-time>

Start of the datetime range in ISO 8601 UTC format.

end
required
string <date-time>

End of the datetime range in ISO 8601 UTC format.

shiftRoster
string

(Optional) shift roster filter

Request Body schema:
required

Contains a List of strings used for equipment codes.

equipmentCodeList
Array of strings

List of equipment codes

Responses

Request samples

Content type
{
  • "equipmentCodeList": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Gets the measure definitions for an equipment, with the option to filter on measureTypes.

  • Security Resource Id : v1/equipment/measuredefinitions

  • Security Resource Action : get

  • BMWS Version: 4.6.0

Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The equipment to get the measure definitions for. Must be a valid equipment code that exists in Equipment Reference Data.

query Parameters
measureTypes
string

(Optional) Comma delimited list of measure types to filter on. Must be a valid measure code in the Measure reference data group

Responses

Response samples

Content type
{
  • "results": [
    ]
}

Post a batch of equipment measure events (non movements)

  • Security Resource Id : v1/equipment/measures

  • Security Resource Action : post

  • BMWS Version: 4.6.0

Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to be updated. Must be a valid equipment code that exists in Equipment Reference Data

query Parameters
useCurrentServerTime
boolean

(Optional) If this is set, then PRIS will ignore any event times passed, and use the current time for events. Also, if there is more than one event, each event will be successive 5ms subtracted from it (as we do in DA for multiple measures)

eventDateTimeUtc
string

(Optional) If this is supplied, it will be used instead of the individual date times of each measure event item. Also, if there is more than one event, each event will be successive 5ms subtracted from it (as we do in Data Acquisition for multiple measures). This is ignored if useCurrentServerTime is set. Otherwise, when neither useCurrentServerTime nor eventDateTimeUtc set, every individual measure event item must contain valid event time

Request Body schema:
required

Measure post data

clientId
required
integer <int32>

Client Id for submitting client. Must be a values obtain via v1/system/clientid

required
Array of objects (BatchMeasureItem)

Collection of event data to submit

Responses

Request samples

Content type
{
  • "clientId": 0,
  • "events": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Search for measures within the given time range and enriches them by actual data from the business model

Returns Pitram measures between (and including) two points in time. Gets the raw measure event data (i.e.measures entered into the system) for the shifts within business model (including rollover events).

The request structure and the resource authorization action are similar to the route "POST measures/search"

  • supports movements, summed, and SMU measures
  • limited by data that in business model (usually current shift plus a couple of shift before)
  • able to query rollover events and generated measures (see generateMeasure and includeRollovers parameters)
  • able to query either created events (by default) or events, that have been logged to the server, during a given time interval (see queryForServerLoggedTime parameter)
  • applies result pagination

  • Security Resource Id : v1/equipment/measures/details/search

  • Security Resource Action : post

  • BMWS Version: 7.0

Authorizations:
oauth2
Request Body schema:
required

Query data parameters

equipmentCodes
Array of strings

Optional list equipment codes to filter results on. If not set, defaults to all equipment. No individual equipment validation - if not a valid equipment code, then will be ignored

equipmentActiveLists
Array of strings

Optional list Equipment active lists to filter results on. If not set, ignored

equipmentModels
Array of strings

Optional list Equipment models to filter results on. If not set, ignored

equipmentFunctions
Array of strings

Optional list Equipment functions to filter on. If not set, ignored

measureCodes
Array of strings

Optional list measure codes to filter on. If not set, include all measures No individual measures validation - if not a valid measure code, then will be ignored

measureActiveLists
Array of strings

List measure active lists

measureTypes
Array of strings

Optional list measure types to filter results on. If not set, ignored

eventTypes
Array of strings

List of event types. E.g. 513 = Record material movement dumped against equipment, 524 = Set equipment payload

startDateTime
required
string <date-time>

Start of request range in ISO 8601 UTC format. E.g. 2020-11-19T03:43:05.142Z

endDateTime
string <date-time>

End of request range in ISO 8601 UTC format. E.g. 2020-11-19T03:43:05.142Z

includeStartDateTime
boolean

If set include start time, otherwise use '>'. Defaults to true

includeRollovers
boolean

Include rollover events. Defaults to false.

includeDescriptions
boolean

Include token descriptions. Defaults to false

dateTimeType
string

Defines how to interpret StartDateTime and EndDateTime parameters If equals to "serverLogged" it means dateTime range will look at the server logged time, while by default it looks at the events' creation time.

generateMeasures
boolean

Whether to include calculate and include generated measures in the result. Defaults to false.

Responses

Request samples

Content type
{
  • "equipmentCodes": [
    ],
  • "equipmentActiveLists": [
    ],
  • "equipmentModels": [
    ],
  • "equipmentFunctions": [
    ],
  • "measureCodes": [
    ],
  • "measureActiveLists": [
    ],
  • "measureTypes": [
    ],
  • "eventTypes": [
    ],
  • "startDateTime": "2019-08-24T14:15:22Z",
  • "endDateTime": "2019-08-24T14:15:22Z",
  • "includeStartDateTime": true,
  • "includeRollovers": true,
  • "includeDescriptions": true,
  • "dateTimeType": "string",
  • "generateMeasures": true
}

Response samples

Content type
{
  • "requestedEndTime": "2019-08-24T14:15:22Z",
  • "actualEndTime": "2019-08-24T14:15:22Z",
  • "items": [
    ],
  • "totalPageCount": 0,
  • "totalCount": 0,
  • "pageSize": 0,
  • "firstPage": "string",
  • "lastPage": "string",
  • "nextPage": "string",
  • "previousPage": "string"
}

Get material movement data, optionally filtered on measure.

  • Security Resource Id : v1/equipment/measures/movements

  • Security Resource Action : get

  • BMWS Version: 4.4.0

  • DCWS Version: 4.4.0

Gets data from either current or historic shifts.

Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code to get movement data for. Must be a valid equipment code that exists in Equipment Reference Data

query Parameters
start
string

(Optional) The start time for the range of data. If supplied, must be a valid ISO 8601 string and be less then 'end'. If not supplied, the start of the current shift will be used

end
string

(Optional) The end time for the range of data. If not supplied, max date time will be used is now current shift), this will return an error code 'BMWS_0021'

measure
Array of strings

(Optional) List of measure to filter on (pass in null not to use)

fields
string

(Optional) A list of fields to filter on. Must be a valid field name within the result set

rosters
string

(Optional) Comma delimited list of shift roster codes to filter the results. If not supplied, the Business Model Server default roster will be used.If supplied, each comma delimited string must be a valid token in the ShiftRoster reference data group.

latestEvent
string

(Optional) Whether to return only the latest event across all queried materials or to return the whole list

Responses

Response samples

Content type
{
  • "results": [
    ]
}

Create an equipment material movement event

  • Security Resource Id : v1/equipment/measures/movements
  • Security Resource Action : post
  • BMWS Version: 3.46.2
Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to be updated. Must be a valid equipment code that exists in Equipment Reference Data.

query Parameters
useCurrentServerTime
boolean

(Optional) If this is set, then PRIS will ignore any event times passed, and use the current time of the PRIS server for events.

Request Body schema:
required

Movement data

destinationCode
required
string

The code of the destination (or dump) location associated with the movement. Must be a valid code in the Location reference data group

measureCode
required
string

The code of the measure recorded – for example "TONNE". Must be a valid measure code in the Measure reference data group

measureValue
required
number <double>

Value of movement measure

materialCode
string

The amount of material moved in the movement. Must be in the range as defined in the measure definition for the measure "measureCode"

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "destinationCode": "string",
  • "measureCode": "string",
  • "measureValue": 0.1,
  • "materialCode": "string",
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Create an equipment at payload event.

Records a payload measure value (for example 20 TONNES, or 5 BCMs) against an equipment. This can be set at any time in the equipment mining cycle and is valid until a dump event occurs. If a value is set through this method then it overrides any quantities passed in with a subsequent DUMP event.

Token validation of the integration mapping will be mixed as the measure code can be configured directly as a Pitram Token depending on the integration.

  • Security Resource Id : v1/equipment/measures/payloads
  • Security Resource Action : post
  • BMWS Version: 4.3.0
Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The identifier of the equipment to be updated. Must either be a valid equipment code that exists in Equipment Reference Data or if the integration parameter is set, an identifier that maps to a valid equipment code in the integration mapping.

query Parameters
integration
string

(Optional) The name of the integration to map the tokens with

Request Body schema:
required

Measure data for the event

measureCode
required
string

The code of the measure recorded – for example "TONNE". Must be a valid measure code in the Measure reference data group

measureValue
required
number <double>

The amount of material moved in the movement. Must be in the range as defined in the measure definition for the measure "measureCode"

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "measureCode": "string",
  • "measureValue": 0.1,
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Search for equipment measure readings (events, any time range).

Returns Pitram measures between (and including) two points in time. Gets the raw measure event data (i.e.measures entered into the system) for the current shift (including rollover events) and/or historic shifts. When the generateMeasure parameter is set to true, this call may also be used to get generated measures.

If the range is large, and a large result set is expected, you may want to page using multiple calls with increasing startDateTime and endDateTime parameters.

  • Security Resource Id : v1/equipment/measures/search

  • Security Resource Action : post

  • BMWS Version: 4.10.10, 4.14.0, 4.15.1, 4.16

Authorizations:
oauth2
Request Body schema:
required

Query data parameters

equipmentCodes
Array of strings

Optional list equipment codes to filter results on. If not set, defaults to all equipment. No individual equipment validation - if not a valid equipment code, then will be ignored

equipmentActiveLists
Array of strings

Optional list Equipment active lists to filter results on. If not set, ignored

equipmentModels
Array of strings

Optional list Equipment models to filter results on. If not set, ignored

equipmentFunctions
Array of strings

Optional list Equipment functions to filter on. If not set, ignored

measureCodes
Array of strings

Optional list measure codes to filter on. If not set, include all measures No individual measures validation - if not a valid measure code, then will be ignored

measureActiveLists
Array of strings

List measure active lists

measureTypes
Array of strings

Optional list measure types to filter results on. If not set, ignored

eventTypes
Array of strings

List of event types. E.g. 513 = Record material movement dumped against equipment, 524 = Set equipment payload

startDateTime
required
string <date-time>

Start of request range in ISO 8601 UTC format. E.g. 2020-11-19T03:43:05.142Z

endDateTime
string <date-time>

End of request range in ISO 8601 UTC format. E.g. 2020-11-19T03:43:05.142Z

includeStartDateTime
boolean

If set include start time, otherwise use '>'. Defaults to true

includeRollovers
boolean

Include rollover events. Defaults to false.

includeDescriptions
boolean

Include token descriptions. Defaults to false

dateTimeType
string

Defines how to interpret StartDateTime and EndDateTime parameters If equals to "serverLogged" it means dateTime range will look at the server logged time, while by default it looks at the events' creation time.

generateMeasures
boolean

Whether to include calculate and include generated measures in the result. Defaults to false.

Responses

Request samples

Content type
{
  • "equipmentCodes": [
    ],
  • "equipmentActiveLists": [
    ],
  • "equipmentModels": [
    ],
  • "equipmentFunctions": [
    ],
  • "measureCodes": [
    ],
  • "measureActiveLists": [
    ],
  • "measureTypes": [
    ],
  • "eventTypes": [
    ],
  • "startDateTime": "2019-08-24T14:15:22Z",
  • "endDateTime": "2019-08-24T14:15:22Z",
  • "includeStartDateTime": true,
  • "includeRollovers": true,
  • "includeDescriptions": true,
  • "dateTimeType": "string",
  • "generateMeasures": true
}

Response samples

Content type
{
  • "requestedEndTime": "2019-08-24T14:15:22Z",
  • "actualEndTime": "2019-08-24T14:15:22Z",
  • "equipment": [
    ]
}

Search for equipment measures summary. Returns measures summed over the shift.

Grouped by (equipment, location, destination, primaryStatus)

  • Security Resource Id : v1/equipment/measures/summary/search

  • Security Resource Action : post

  • BMWS Version: 4.11.122

  • DCWS Version 4.11.120

Authorizations:
oauth2
Request Body schema:
required

Body for our query. Everything in here is optional

descriptions
boolean

Set to include descriptions

equipmentCodes
Array of strings

List of equipment codes (can be null)

measureCodes
Array of strings

List of measure codes (can be null)

locationCodesToExclude
Array of strings

List of source location codes to exclude(can be null)

destinationCodesToExclude
Array of strings

List of destination codes to exclude(can be null)

rosterCodes
Array of strings

Comma delimited list of roster codes (can be null)

dateTimeShift
string <date-time>

Date time within a shift we want to query the data for

dateTimeFrom
string <date-time>

Date time from range we want to find shifts and query data for

dateTimeTo
string <date-time>

Date time to range we want to find shifts and query data for

Responses

Request samples

Content type
{
  • "descriptions": true,
  • "equipmentCodes": [
    ],
  • "measureCodes": [
    ],
  • "locationCodesToExclude": [
    ],
  • "destinationCodesToExclude": [
    ],
  • "rosterCodes": [
    ],
  • "dateTimeShift": "2019-08-24T14:15:22Z",
  • "dateTimeFrom": "2019-08-24T14:15:22Z",
  • "dateTimeTo": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "measureSummaries": [
    ]
}

Creates an equipment payload event using a metric measure volume and the density of the movement.

Records a payload measure value against an equipment where the measure value is calculated from the submitted volumetric value. If the density is not submitted then the density of the material loaded for the movement cycle is used. This can be set at any time in the equipment mining cycle and is valid until a dump event occurs. If a value is set through this method then it overrides any quantities passed in with a subsequent DUMP event.

Token validation of the integration mapping will be mixed as the measure code can be configured directly as a Pitram Token depending on the integration.

  • Security Resource Id : v1/equipment/measures/volumetricpayloads
  • Security Resource Action : post
  • BMWS Version: 9.1.0
Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The identifier of the equipment to be updated. Must either be a valid equipment code that exists in Equipment Reference Data or if the integration parameter is set, an identifier that maps to a valid equipment code in the integration mapping.

query Parameters
integration
string

(Optional) The name of the integration to map the tokens with.

Request Body schema:
required

Measure data for the event

volumetricReading
required
number <double>

The volumetric reading of the material in the movement. Measured in cubic metres.

densityReading
number <double>

The density reading of the material in the movement. Measured in kilogram per cubic metre. If the density is not set then the density of the material for the movement cycle is used.

measureCode
required
string

The code of the measure to convert the volumetric reading to

sourceMeasureCode
string

The code of the measure to convert the volumetric reading from. If not set then the measure defaults to KG.

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "volumetricReading": 0.1,
  • "densityReading": 0.1,
  • "measureCode": "string",
  • "sourceMeasureCode": "string",
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Creates a list of movement events against multiple equipment.

  • Security Resource Id : v1/equipment/movements

  • Security Resource Action : post

  • BMWS Version: 8.0.0.163

Authorizations:
oauth2
query Parameters
allow-partial-updates
boolean

(Optional) If set to true (by default), then route will submit what is can and log out any failed. If false, if any one insert fails, they all failed

Request Body schema:
required

Equipment movements to be created.

clientId
required
integer <int32>

Client Id for submitting client. Must be a values obtain via v1/system/clientid

required
Array of objects (BatchTokenMovementItem)

Collection of event data to submit

Responses

Request samples

Content type
{
  • "clientId": 0,
  • "events": [
    ]
}

Response samples

Content type
{
  • "batchErrors": [
    ]
}

Gets equipment positions based on supplied (optional) filters.

If the start time passed is within the current shift, we query positions from the current shift, otherwise a historic query will be executed.

Updates only available in this route

Updates only notes - We can use pass in "prev-results-time" to only return equipment that have had updates since the last server query time. This is passed back via a previous call. For position events, the prev-results-time is essentially the same as using start time. We are not interested in older position events that may arrive at the server later than prev-results-time. Where both startTime and prev-results-time are supplied, we will return events with event time (not server logged time) equal to, or later than the maximum of these two parameters.

Also note, if descriptions are included, updates only is also disabled if there has been either an equipment reference data publish or BusinessModel Server restart since the previous result (as an equipment description could have changed).

All parameters are optional. Results are sorted by Equipment description, position event time (ascending)

Only positions with a valid HDOP and VDOP (less than or equal to 10) are included in the results.

Equipment Filters - If all missing, then defaults to all equipment, otherwise we “and” each individual.

Position data filtering - If no filters, we get all available. If multiple filters are used, the results are the tokens common to all filters.

See the response model to see available fields.

Single last known position - We want to be able to ask for just the last known position. For this we can pass no end date and max-positions = 1

  • Security Resource Id : v1/equipment/positions
  • Security Resource Action : get
  • BMWS Version: 7.0.0.46
Authorizations:
oauth2
query Parameters
start
string <date-time>

(Optional) Default = prev-results-time or if not given then start of current shift. Start date time to get position data from in ISO 8601 UTC format.

end
string <date-time>

(Optional) Default = start + 12 hours. End date time to get position data before in ISO 8601 UTC format. Will include exact end time.

prev-results-time
string <date-time>

(Optional) The time passed back from a previous query, via the resultsTimeUtc field, and in ISO 8601 UTC format. Allows to only include updated equipment.

max-positions
integer <int32>

(Optional) Default = all available positions. Maximum positions to return per equipment. Relevant for current shift only.

codes
string

(Optional) Comma delimited list of individual equipment codes to filter upon.

activelists
string

(Optional) Comma delimited list of equipment active lists to filter upon.

functions
string

(Optional) Comma delimited list of equipment functions to filter upon.

models
string

(Optional) Comma delimited list of equipment models to filter upon.

descriptions
boolean

(Optional) Default = true. If set, include equipment descriptions.

include-rollovers
boolean

(Optional) Default = true. If set, include rollover events. Relevant for historic only.

include-start-time
boolean

(Optional) Default = true. If set, include events exactly at start. Relevant for historic only.

pos-fields
string

(Optional) Default = all position fields. Comma delimited list of position fields to include in the results. See response model for available fields (case non-sensitive).

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "updatesOnly": true,
  • "resultsTimeUtc": "string",
  • "results": [
    ],
  • "fieldDescriptions": [
    ]
}

Create a batch of equipment position events.

Note that a position event goes through GPS event smoothing and may not always result in an event being created and submitted.

  • Security Resource Id : v1/equipment/positions

  • Security Resource Action : post

  • BMWS Version: 4.1.0

Authorizations:
oauth2
Request Body schema:
required

The equipment position data.

clientId
required
integer <int32>

Client Id for submitting client. Must be a values obtain via v1/system/clientid

Array of objects (PositionBatchEventItem)

Collection of position event data

Responses

Request samples

Content type
{
  • "clientId": 0,
  • "events": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Create an equipment position event.

Note that a position event goes through GPS event smoothing and may not always result in an event being created and submitted.

  • Security Resource Id : v1/equipment/positions

  • Security Resource Action : post

  • BMWS Version: 4.0.0

Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to be updated. Must be a valid equipment code that exists in Equipment Reference Data.

Request Body schema:
required

The equipment position data.

x
required
number <double>

X coordinate of the position

y
required
number <double>

Y coordinate of the position

z
required
number <double>

Z coordinate of the position

positionSystem
required
string

The position system as described by the X, Y, Z.
Must be one of the following: NOT_APPLICABLE, GPS, MINEGRID

positionSource
required
string

Possible sources of position information. Source of position information. Must be one of the following: Unknown, GPS, Waypoint, Manual, ReferenceData, ExternalSystem

hasGpsFix
required
boolean

Set whether or not we have a GPS fix. Must be either true or false. Defaults to false if value is absent. If this is false, then no event is ever created, so it is best to pass true

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "x": 0.1,
  • "y": 0.1,
  • "z": 0.1,
  • "positionSystem": "string",
  • "positionSource": "string",
  • "hasGpsFix": true,
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Search for pre-start checklists.

Get information about equipment pre-start checklists within a supplied time period. If the time period is not defined (i.e. any of start or end times are not defined) then queries data for the current shift.

  • Security Resource Id : v1/equipment/prestart-checklists/search

  • Security Resource Action : post

  • BMWS Version: 5.1

Authorizations:
oauth2
Request Body schema:
required

model for querying equipment checklists

startDateTimeUtc
string <date-time>

Start of requested date range. If not supplied, the date range of the current shift is used (endDateTime will be ignored)

endDateTimeUtc
string <date-time>

Start of requested date range. If not supplied, the date range of the current shift is used (startDateTime will be ignored)

equipmentCodes
Array of strings

Collection of equipment codes to search for. If empty, looks for all defined equipment

operatorCodes
Array of strings

Collection of operator codes to search for. If empty, looks for all defined operators

rosters
Array of strings

Collection of shift rosters codes to search for. If empty, looks for all defined rosters

descriptions
boolean

Allows us to toggle whether or not to return descriptions as well as codes in the results

Responses

Request samples

Content type
{
  • "startDateTimeUtc": "2024-06-06T22:29:57.037582Z",
  • "endDateTimeUtc": "2024-06-07T02:29:57.037582Z",
  • "equipmentCodes": [
    ],
  • "operatorCodes": [
    ],
  • "rosters": [
    ],
  • "descriptions": true
}

Response samples

Content type
{
  • "results": [
    ]
}

Create an equipment primary status event, to update an equipment's primary status.

  • Security Resource Id : v1/equipment/primarystates

  • Security Resource Action : post

  • BMWS Version: 3.46.2

Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to be updated. Must be a valid equipment code that exists in Equipment Reference Data.

Request Body schema:
required

Primary status event data

statusCode
required
string

The code of the primary status to set. Must be a valid status code in the Status reference data group

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "statusCode": "string",
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Get Equipment primary status at any time during the current shift

  • Security Resource Id : v1/equipment/primarystatus

  • Security Resource Action : get

  • BMWS Version: 4.9.0.100

Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to be updated. Must be a valid equipment code that exists in Equipment Reference Data.

query Parameters
querytime
string

(Optional) Query time in ISO 8601 UTC format. If not supplied, the current primary status is returned

Responses

Response samples

Content type
{
  • "status": {
    }
}

Search for equipment states (primary and cycle states) in a time range.

  • Security Resource Id : v1/equipment/states
  • Security Resource Action : get
  • BMWS Version: 7.0.0
Authorizations:
oauth2
query Parameters
codes
string

(Optional) Comma delimited list of individual equipment codes to filter upon.

actlists
string

(Optional) Comma delimited list of equipment active lists to filter upon.

models
string

(Optional) Comma delimited list of equipment models to filter upon.

functions
string

(Optional) Comma delimited list of equipment functions to filter upon.

start
string <date-time>

(Optional) Start dateTime to get results for. Defaults to current shift start

end
string <date-time>

(Optional) End datetime to get results for. Defaults to current shift end

include-rollovers
boolean

(Optional) To include rollovers in results. Defaults to true.

include-code
boolean

(Optional) To include code in results. Defaults to true.

include-description
boolean

(Optional) To include description in results. Defaults to true.

include-primary
boolean

(Optional) To include primary states in results. Defaults to true.

include-cycle
boolean

(Optional) To include cycle states in results. Defaults to true.

roster
string

(Optional) Shift roster to use for current shift start and end times (if start/end are not supplied)

Responses

Response samples

Content type
{
  • "equipment": [
    ]
}

Creates an Equipment at a Waypoint event.

If a Waypoint has Waypoint Rules defined, these will trigger as a result of this event.

  • Security Resource Id : v1/equipment/waypoints

  • Security Resource Action : post

  • BMWS Version: 4.0.0

Authorizations:
oauth2
path Parameters
equipmentCode
required
string

The Pitram code for the equipment to be updated. Must be a valid equipment code that exists in Equipment Reference Data.

Request Body schema:
required

The equipment waypoint data.

waypointCode
required
string

The code of the waypoint to set the equipment at. Must be a valid waypoint code in the Waypoint reference data group

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "waypointCode": "string",
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Locations

Get equipment and people location allocation data

Updates only available in this route.

This route is designed to provide "updates only" or "deltas" when a time from the previous request is passed back via the previousResultsTimeUtc parameter. The idea is that the first query gets passed back a resultsTimeUTC.If this is then passed back to the next query, then that query will only return updates since that time. When the results are a delta, the updatesOnly flag is set to true.

Data filtering - If no filters, we get all available. Note that if multiple filters are used, the results are the tokens common to all filters. See the response model to see available fields.

  • Security Resource Id : v1/locations/allocations

  • Security Resource Action : get

  • BMWS Version: 10.2.0, 11.0.0

Authorizations:
oauth2
query Parameters
loc-codes
string

(Optional) Comma delimited list of individual location codes to filter upon.

loc-actlists
string

(Optional) Comma delimited list of location active lists to filter upon.

equip-codes
string

(Optional) Comma delimited list of individual equipment codes to filter upon.

equip-actlists
string

(Optional) Comma delimited list of equipment active lists to filter upon.

equip-models
string

(Optional) Comma delimited list of equipment models to filter upon.

equip-functions
string

(Optional) Comma delimited list of equipment functions to filter upon.

person-codes
string

(Optional) Comma delimited list of individual person codes to filter upon.

person-actlists
string

(Optional) Comma delimited list of person active lists to filter upon.

include-code
boolean

(Optional) To include code in results. Defaults to true.

include-description
boolean

(Optional) To include description in results. Defaults to true.

include-equip
boolean

(Optional) To include equipment in results. Defaults to true.

include-people
boolean

(Optional) To include people in results. Defaults to true.

prev-results-time
string <date-time>

(Optional) The time passed back from a previous query, via the resultsTimeUtc field, and in ISO 8601 UTC format. Allows update only results.

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "resultsTimeUtc": "2019-08-24T14:15:22Z",
  • "updatesOnly": true,
  • "locations": [
    ],
  • "fieldDescriptions": [
    ]
}

Get location details information (no measure).

  • Security Resource Id : v1/locations/currentshift/details

  • Security Resource Action : get

  • BMWS Version: 4.8.0

Authorizations:
oauth2
path Parameters
locationCode
required
string

The Pitram code for the location to get results for. Must be a valid location code that exists in Location Reference Data.

statusClassCode
required
string

Location status classification code to filter on. Must be a valid code in the LocationStatusClassification reference data group

query Parameters
cu
string

(Optional) The culture used to format strings and dates. May also use Accept-Language header.

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "resultData": [
    ],
  • "fieldDescriptions": [
    ],
  • "updatesOnly": true,
  • "resultsTime": "string"
}

Get location details information filtering by measure.

  • Security Resource Id : v1/locations/currentshift/details

  • Security Resource Action : get

  • BMWS Version: 4.8.0

Authorizations:
oauth2
path Parameters
locationCode
required
string

The Pitram code for the location to get results for. Must be a valid location code that exists in Location Reference Data.

statusClassCode
required
string

Location status classification code to filter on. Must be a valid code in the LocationStatusClassification reference data group

measureCode
required
string

Measure code to be used for quantities related to the location. Must be a valid code in the Measure reference data group.

query Parameters
cu
string

(Optional) The culture used to format strings and dates. May also use Accept-Language header.

rosters
string

(Optional) Comma delimited list of shift roster codes to filter the results. If not supplied, the Business Model Server default roster will be used. If supplied, each comma delimited string must be a valid token in the ShiftRoster reference data group.

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "resultData": [
    ],
  • "fieldDescriptions": [
    ],
  • "updatesOnly": true,
  • "resultsTime": "string"
}

Gets location status information

Updates only available in this route.

Gets current status information for locations and for a provided location status class. Locations can optionally be filtered using an activelist. When in non update mode, this will only return results for locations that have set states. In update mode, if a location has any change in status, then the results will return the latest status of the location for the status class requested, regardless of whether a status of that class has changed or not.Additionally, in update mode, if the status returned is empty(the location has no status), the result WILL include this with the status information set to an empty string. A client application will need to know this in case this was a status that has now been cleared.

  • Security Resource Id : v1/locations/currentshift/states
  • Security Resource Action : get
  • BMWS Version: 4.6.0
Authorizations:
oauth2
path Parameters
statusClassCode
required
string

Location status class to filter on

query Parameters
previousResultsTimeUtc
string

(Optional) Time passed back from a previous call to this route. If supplied, we can be supplied with just any updates

activelist
string

(Optional) Active list to filter on

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "results": [
    ],
  • "updatesOnly": true,
  • "resultsTimeUtc": "string"
}

Allows a Client to submit an sensors' data including time, value and location where the sensor is installed.

  • Security Resource Id : v1/locations/depths
  • Security Resource Action : post

DWS Version: 5.0

Authorizations:
oauth2
Request Body schema:
required

sensors data

clientId
required
integer <int32>

Client Id for submitting client app

eventDateTimeUtc
required
string <date-time>

The event date time in UTC

required
Array of objects (SensorOrePass)

Collection of orepasses which contained sensors

Responses

Request samples

Content type
{
  • "clientId": 1,
  • "eventDateTimeUtc": "2024-06-07T02:29:57.053241Z",
  • "orePasses": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Get Equipment allocated to Locations

Gets Equipment that are allocated to Locations

  • Security Resource Id : v1/locations/equipment

  • Security Resource Action : get

  • BMWS Version: 11.0

Authorizations:
oauth2
query Parameters
locations
string

(Optional) Comma delimited list of individual location codes to filter on.

activelists
string

(Optional) Comma delimited list of location active lists to filter upon.

datetime
string <date-time>

(Optional) Date time to query result on. Must be in ISO 8601 UTC format.

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "results": [
    ]
}

Create and submit a location exclusive status event.

  • Security Resource Id : v1/locations/exclusivestates

  • Security Resource Action : post

  • BMWS Version: 4.6.0.99 (BMS version updated after changed binding)

Authorizations:
oauth2
path Parameters
locationCode
required
string

The Pitram code for the location to update. Must be a valid location code that exists in the location reference data group.

Request Body schema:
required

Exclusive status event data

statusCode
required
string

The code of the status to set. Must be a valid status code in the Status reference data group

statusClassCode
required
string

The status classification code. Note that this is not a code from the Category group in ref data. For locations, this is from the Location Classification group. For equipment, the only use is for Repair states.

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "statusCode": "string",
  • "statusClassCode": "string",
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Posts a list of location material events.

  • Security Resource Id : v1/locations/materials

  • Security Resource Action : post

  • BMWS Version: 8.0.0

Authorizations:
oauth2
query Parameters
allow-partial-updates
boolean

(Optional) If set to true (by default), then route will submit what is can and log out any failed. If false, if any one insert fails, they all failed

Request Body schema:
required

Location material events to be created.

clientId
required
integer <int32>

Client Id for submitting client. Must be a values obtain via v1/system/clientid

required
Array of objects (BatchTokenMaterialItem)

Collection of event data to submit

Responses

Request samples

Content type
{
  • "clientId": 0,
  • "events": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Posts a list of location measure events.

  • Security Resource Id : v1/locations/measures

  • Security Resource Action : post

  • BMWS Version: 8.0.0.156

Authorizations:
oauth2
query Parameters
allow-partial-updates
boolean

(Optional) If set to true (by default), then route will submit what is can and log out any failed. If false, if any one insert fails, they all failed

Request Body schema:
required

Location measure events to be created.

clientId
required
integer <int32>

Client Id for submitting client. Must be a values obtain via v1/system/clientid

required
Array of objects (BatchTokenMeasureItem)

Collection of event data to submit

Responses

Request samples

Content type
{
  • "clientId": 0,
  • "events": [
    ]
}

Response samples

Content type
{
  • "batchErrors": [
    ]
}

Get People allocated to Locations

Gets People that are allocated to Locations

  • Security Resource Id : v1/locations/people

  • Security Resource Action : get

  • BMWS Version: 11.0

Authorizations:
oauth2
query Parameters
locations
string

(Optional) Comma delimited list of individual location codes to filter on.

activelists
string

(Optional) Comma delimited list of location active lists to filter upon.

datetime
string <date-time>

(Optional) Date time to query result on. Must be in ISO 8601 UTC format.

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "results": [
    ]
}

Get equipment and people location waypoint data

Updates only available in this route.

This route is designed to provide "updates only" or "deltas" when a time from the previous request is passed back via the previousResultsTimeUtc parameter. The idea is that the first query gets passed back a resultsTimeUTC.If this is then passed back to the next query, then that query will only return updates since that time. When the results are a delta, the updatesOnly flag is set to true.

Data filtering - If no filters, we get all available. Note that if multiple filters are used, the results are the tokens common to all filters. See the response model to see available fields.

  • Security Resource Id : v1/locations/waypoints/current-visitors

  • Security Resource Action : get

  • BMWS Version: 8.0.0

Authorizations:
oauth2
query Parameters
wp-codes
string

(Optional) Comma delimited list of individual waypoint codes to filter upon.

wp-actlists
string

(Optional) Comma delimited list of waypoint active lists to filter upon.

equip-codes
string

(Optional) Comma delimited list of individual equipment codes to filter upon.

equip-actlists
string

(Optional) Comma delimited list of equipment active lists to filter upon.

equip-models
string

(Optional) Comma delimited list of equipment models to filter upon.

equip-functions
string

(Optional) Comma delimited list of equipment functions to filter upon.

person-codes
string

(Optional) Comma delimited list of individual person codes to filter upon.

person-actlists
string

(Optional) Comma delimited list of person active lists to filter upon.

include-code
boolean

(Optional) To include code in results. Defaults to true.

include-description
boolean

(Optional) To include description in results. Defaults to true.

include-equip
boolean

(Optional) To include equipment in results. Defaults to true.

include-people
boolean

(Optional) To include people in results. Defaults to true.

prev-results-time
string

(Optional) The time passed back from a previous query, via the resultsTimeUtc field, and in ISO 8601 UTC format. Allows update only results.

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "resultsTimeUtc": "2019-08-24T14:15:22Z",
  • "updatesOnly": true,
  • "waypoints": [
    ],
  • "fieldDescriptions": [
    ]
}

MaterialsManagement

Get elemental grades locations active-lists

Gets the location active lists that have a location with elemental grades

  • Security Resource Id : v1/materials-management/geology-toolkit/active-lists
  • Security Resource Action : Get

DWS Version: 8.0

Authorizations:
oauth2
query Parameters
latest-el-grades-date-time
required
string <date-time>

Return elemental grades imported at or before this time.

Responses

Response samples

Content type
{
  • "locationActiveLists": [
    ],
  • "referenceDataVersion": 0,
  • "latestElementalGradeDateTime": "2019-08-24T14:15:22Z"
}

Get elemental grades

Gets latest elemental grades on each unique (location, rocktype, element)

  • Security Resource Id : v1/materials-management/geology-toolkit/elemental-grades
  • Security Resource Action : Get

DomeWS Version: 8.0

Authorizations:
oauth2

Responses

Response samples

Content type
{
  • "elementalGrades": [
    ]
}

Add Geology Toolkit Observations

Add Observations for Geological Toolkit. Allows for batch.

  • Security Resource Id : v1/materials-management/geology-toolkit/observations
  • Security Resource Action : Post

DomeWS Version: 8.0

Authorizations:
oauth2
query Parameters
allow-partial-updates
boolean

(Optional) If set to true (default=true), then route will submit what it can and log out any failed. If false, if any one insert fails, they all failed

Request Body schema:
required

List of the object model that contains the data we need to add Observations and calculated values

required
Array of objects (Observation)

List of the object model that contains the data we need to add Observations and calculated values

Responses

Request samples

Content type
{
  • "observations": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Set grades information.

Post grade information to the Dome Production GradeControlGrade table.

  • Security Resource Id : v1/materials-management/grades

  • Security Resource Action : post

  • BMWS Version: 4.11.0

Authorizations:
oauth2
query Parameters
allow-partial-updates
boolean

(Optional) If set to true (by default), then route will submit what is can and log out any failed, if false, if any one insert fails, they all failed

Request Body schema:
required

Grades information to update

required
Array of objects (GradeItem)

Grades data

Responses

Request samples

Content type
{
  • "grades": [
    ]
}

Response samples

Content type
{
  • "allowPartialUpdate": true,
  • "gradeOperations": [
    ]
}

Get grades information. Return the latest record for each location/grade

GET grade information for a supplied time period that can be used to populate the Dome Production GradeControlGrade table

  • Security Resource Id : v1/materials-management/grades

  • Security Resource Action : post

  • BMWS Version: 4.11.0

Authorizations:
oauth2
Request Body schema:
required

model for querying grades

queryTime
string <date-time>

(Optional) specific point of time - will be used to retrieve the actual location grade at that particular time. Formatted as UTC ISO 8601

elements
string

(Optional) Comma delimited list of elements to filter on

locations
string

(Optional) Comma delimited list of locations to filter on

mineRegions
string

(Optional) Comma delimited list of mine regions to filter on

descriptions
boolean

Allows us to toggle whether or not to return descriptions as well as codes in the results

Responses

Request samples

Content type
{
  • "queryTime": "2019-08-24T14:15:22Z",
  • "elements": "string",
  • "locations": "string",
  • "mineRegions": "string",
  • "descriptions": true
}

Response samples

Content type
{
  • "results": [
    ]
}

Set grade targets information.

  • Security Resource Id : v1/materials-management/grades/targets
  • Security Resource Action : post

DomeWS Version: 4.15.1, 4.16

Authorizations:
oauth2
query Parameters
allow-partial-updates
boolean

(Optional) If set to true (by default), then route will submit what is can and log out any failed. If false, if any one insert fails, they all failed

Request Body schema:
required

Grade targets information to update

required
Array of objects (GradeTargetItem)

List of Grades data

Responses

Request samples

Content type
{
  • "targets": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Get movements information along with grades data.

Allows to get total material quantity when groupBy parameter is set to the one of the following valid values: "destination,material,elements"

  • Security Resource Id : v1/materials-management/movements/grades
  • Security Resource Action : post

DWS Version: 4.14.0

Authorizations:
oauth2
Request Body schema:
required

model for querying movements along grades

fromTime
string <date-time>

Start point of time interval

toTime
string <date-time>

End point of time interval

shiftRoster
string

Shift roster code

elements
string

Comma delimited list of elements to filter on

sources
string

Comma delimited list of source locations to filter on

destinations
string

Comma delimited list of destination locations to filter on

groupBy
string

List of properties to group by

Responses

Request samples

Content type
{
  • "fromTime": "2019-08-24T14:15:22Z",
  • "toTime": "2019-08-24T14:15:22Z",
  • "shiftRoster": "string",
  • "elements": "string",
  • "sources": "string",
  • "destinations": "string",
  • "groupBy": "string"
}

Response samples

Content type
{
  • "results": [
    ]
}

Get material stocks information which can be grouped by layers.

Get information about stocks for on a given moment of time. Stockpile levels (i.e. grouping stocks by location, material, roster and grades) can also be requested by providing model.groupBy parameter

  • Security Resource Id : v1/materials-management/stocks
  • Security Resource Action : post

DomeWS Version: 5.0

Authorizations:
oauth2
Request Body schema:
required

model for querying stocks

dateTimeUtc
string <date-time>

(Optional) specific point of time.If not provided the current server time will be used to retrieve stocks

locationCodes
Array of strings

(Optional) Collection of location codes to search for

rosterCodes
Array of strings

(Optional) Collection of roster codes to search for

materialCodes
Array of strings

(Optional) Collection of material codes to search for

groupBy
string

(Optional)Type of grouping

descriptions
boolean

(Optional)Allows us to toggle whether or not to return descriptions as well as codes in the results

Responses

Request samples

Content type
{
  • "dateTimeUtc": "2024-06-07T02:29:57.0812407Z",
  • "locationCodes": [
    ],
  • "rosterCodes": [
    ],
  • "materialCodes": [
    ],
  • "groupBy": "level",
  • "descriptions": true
}

Response samples

Content type
{
  • "results": [
    ]
}

Add locations surveys.

Partial update not supported.

  • Security Resource Id : v1/materials-management/surveys/locations
  • Security Resource Action : post

DomeWS Version: 7.0.5

Authorizations:
oauth2
query Parameters
useCurrentServerTime
boolean

(Optional) If this is set, time of submission passed will be ignored, and the current server will be used.

Request Body schema:
required

Contains locations surveys to submit

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of submission in ISO 8601 UTC format. Must not be greater than the current time

required
Array of objects (NewLocationSurveysModel)

List of locations. Each location may have multiple surveys

Responses

Request samples

Content type
{
  • "clientId": 0,
  • "eventDateTimeUtc": "2024-06-07T02:29:57.0832402Z",
  • "surveys": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

People

Create and submit an Allocate a person to an equipment or location event

  • Security Resource Id : v1/people/allocate
  • Security Resource Action : post
Authorizations:
oauth2
path Parameters
personCode
required
string

The Pitram code for the person to create the event against. Must be a valid person code that exists in Person Reference Data.

Request Body schema:
required

Object containing properties of the allocation

role
required
string

The Person role

allowOpQualOverride
boolean

If the allocation does not pass any operator qualification, but we allow this to be overridden, if this is true, then we will create the allocation

allocObjectType
required
string

Type of the resource that the person will be allocated to. Must be either EQUIPMENT or LOCATION

allocObjectCode
required
string

Code of the resource the person will be allocated to. Codes could belong to a location or an equipment

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "role": "string",
  • "allowOpQualOverride": true,
  • "allocObjectType": "string",
  • "allocObjectCode": "string",
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "tempOperatorCode": "string"
}

Get allocation events of people to an equipment or location event. For current shift only.

  • Security Resource Id : v1/people/allocations

  • Security Resource Action : get

  • BMWS Version: 8.0.0

Authorizations:
oauth2
query Parameters
person-codes
string

(Optional) Comma delimited list of individual person codes to filter upon.

person-actlists
string

(Optional) Comma delimited list of person active lists to filter upon.

max-waypoints
integer <int32>

(Optional) The max number of waypoints to include per person.

allocation-type-filter
string

(Optional) The allocation type to specify. Eg. Equipment or Location

include-code
boolean

(Optional) To include code in results. Defaults to true.

include-description
boolean

(Optional) To include description in results. Defaults to true.

prev-results-time
string

(Optional) The time passed back from a previous query, via the resultsTimeUtc field, and in ISO 8601 UTC format. Allows update only results.

Responses

Response samples

Content type
{
  • "resultsTimeUtc": "2019-08-24T14:15:22Z",
  • "updatesOnly": true,
  • "personAllocationList": [
    ]
}

Get person details information.

  • Security Resource Id : v1/people/currentshift/details

  • Security Resource Action : get

  • BMWS Version: 4.8.0

Authorizations:
oauth2
path Parameters
personCode
required
string

The Pitram code for the person to get results for. Must be a valid person code that exists in Person Reference Data.

query Parameters
cu
string

(Optional) The culture used to format strings and dates. May also use Accept-Language header.

rosters
string

(Optional) comma delimited list of rosters. If supplied, each comma delimited string must be a valid token in the ShiftRoster reference data group.

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "resultData": [
    ],
  • "fieldDescriptions": [
    ],
  • "updatesOnly": true,
  • "resultsTime": "string"
}

Gets operator summary information

Updates only available in this route.

Retrieves person allocation summary information, which includes the person, allocation, and operating duration relative to the length of shift.

Note: Only people currently allocated to equipment as Primary Operators are returned. Secondary operators or primary operators allocated to locations are not included. Operators allocated and then de-allocated to equipment in the current shift are not included.

  • Security Resource Id : "v1/people/currentshift/operatorsummary

  • Security Resource Action : get

  • BMWS Version: 4.6.0

Authorizations:
oauth2
query Parameters
previousResultsTimeUtc
string

(Optional) Time passed back from a previous call to this route. If supplied, we can be supplied with just any updates.

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "results": [
    ],
  • "updatesOnly": true,
  • "resultsTimeUtc": "string"
}

Create and submit a Deallocate a person from an equipment or location

  • Security Resource Id : v1/people/deallocate
  • Security Resource Action : post
Authorizations:
oauth2
path Parameters
personCode
required
string

Code of the person to deallocate. Must be a valid person code that exists in Pitram Reference Data.

Request Body schema:
required

Object containing properties of the deallocation

allocObjectType
required
string

Type of the resource that the person will be allocated to. Must be either EQUIPMENT or LOCATION.

allocObjectCode
required
string

Code of the resource the person will be allocated to. Must be a valid equipment/location code that exists in Pitram Reference Data

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "allocObjectType": "string",
  • "allocObjectCode": "string",
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Create and submit a person position event.

Note that a position event goes through GPS event smoothing and may not always result in an event being created and submitted.

  • Security Resource Id : v1/people/positions

  • Security Resource Action : post

  • BMWS Version: 4.0.0

Authorizations:
oauth2
path Parameters
personCode
required
string

The Pitram code for the person to created the event against. Must be a valid person code that exists in Person Reference Data.

Request Body schema:
required

The person position data.

x
required
number <double>

X coordinate of the position

y
required
number <double>

Y coordinate of the position

z
required
number <double>

Z coordinate of the position

positionSystem
required
string

The position system as described by the X, Y, Z.
Must be one of the following: NOT_APPLICABLE, GPS, MINEGRID

positionSource
required
string

Possible sources of position information. Source of position information. Must be one of the following: Unknown, GPS, Waypoint, Manual, ReferenceData, ExternalSystem

hasGpsFix
required
boolean

Set whether or not we have a GPS fix. Must be either true or false. Defaults to false if value is absent. If this is false, then no event is ever created, so it is best to pass true

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "x": 0.1,
  • "y": 0.1,
  • "z": 0.1,
  • "positionSystem": "string",
  • "positionSource": "string",
  • "hasGpsFix": true,
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Gets people positions based on supplied (optional) filters.

If the start time passed is within the current shift, we query positions from the current shift, otherwise a historic query will be executed.

Updates only available in this route

Updates only notes - We can use pass in "prev-results-time" to only return equipment that have had updates since the last server query time. This is passed back via a previous call. For position events, the prev-results-time is essentially the same as using start time. We are not interested in older position events that may arrive at the server later than prev-results-time. Where both startTime and prev-results-time are supplied, we will return events with event time (not server logged time) equal to, or later than the maximum of these two parameters.

Only positions with a valid HDOP and VDOP (less than or equal to 10) are included in the results.

Also note, if descriptions are included, updates only is also disabled if there has been either an person reference data publish or BusinessModel Server restart since the previous result (as an person description could have changed).

All parameters are optional. Results are sorted by person description, position event time (ascending)

person Filters - If all missing, then defaults to all people. Note that if multiple filters are used, the results are the data common to all filters.

Position data filtering - If no filters, we get all available. If we have filters, the results from each are combined together. See the response model to see available fields.

Single last known position - We want to be able to ask for just the last known position. For this we can pass no end date and max-positions = 1

  • Security Resource Id : v1/people/positions
  • Security Resource Action : get
  • BMWS Version: 7.0.0.46
Authorizations:
oauth2
query Parameters
start
string <date-time>

(Optional) Default = Current shift start. Start date time to get position data from in ISO 8601 UTC format.

end
string <date-time>

(Optional) Default: if start time is in current shift, max value, if start time causes a historic query, this is start time + 12 hours. End date time to get position data before in ISO 8601 UTC format. Will include exact end time.

prev-results-time
string <date-time>

(Optional) The time passed back from a previous query, via the resultsTimeUtc field, and in ISO 8601 UTC format. Allows to only include updated person.

max-positions
integer <int32>

(Optional) Default = all available positions. Maximum positions to return per person. Relevant for current shift only.

codes
string

(Optional) Comma delimited list of individual person codes to filter upon.

activelists
string

(Optional) Comma delimited list of person active lists to filter upon.

crews
string

(Optional) list of person crews to filter upon.

employers
string

(Optional) list of person employers to filter upon.

departments
string

(Optional) list of person departments to filter upon.

descriptions
boolean

(Optional) Default = true. If set, include people descriptions.

include-rollovers
boolean

(Optional) Default = true. If set, include rollover events. Relevant for historic only.

include-start-time
boolean

(Optional) Default = true. If set, include events exactly at start. Relevant for historic only.

pos-fields
string

(Optional) Default = all position fields. Comma delimited list of position fields to include in the results. See response model for available fields (case non-sensitive).

Responses

Response samples

Content type
{
  • "updatesOnly": true,
  • "resultsTimeUtc": "string",
  • "results": [
    ],
  • "fieldDescriptions": [
    ]
}

Create and submit a batch of person at position events.

Note that a position event goes through GPS event smoothing and may not always result in an event being created and submitted.

  • Security Resource Id : v1/people/positions

  • Security Resource Action : post

  • BMWS Version: 4.0.0

Authorizations:
oauth2
Request Body schema:
required

The person position data.

clientId
required
integer <int32>

Client Id for submitting client. Must be a values obtain via v1/system/clientid

Array of objects (PositionBatchEventItem)

Collection of position event data

Responses

Request samples

Content type
{
  • "clientId": 0,
  • "events": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Create and submit a person at waypoint event.

  • Security Resource Id : v1/people/waypoints

  • Security Resource Action : post

  • BMWS Version: 4.0.0

Authorizations:
oauth2
path Parameters
personCode
required
string

The Pitram code for the person to create the event against. Must be a valid person code that exists in Person Reference Data.

Request Body schema:
required

The person waypoint data.

waypointCode
required
string

The code of the waypoint to set the equipment at. Must be a valid waypoint code in the Waypoint reference data group

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "waypointCode": "string",
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Reports

Create a job that allows a client to run a report and get back a set of data.

This version will run synchronously, so it waits for the report to finish and return the data.

  • Security Resource Id : v1/reports/run
  • Security Resource Action : post
  • Portal Web Version : 4.9
Authorizations:
oauth2
path Parameters
reportName
required
string

The name of the report being generated in the Pitram Portal Reporting service. Must be a valid report configured in the Pitram Portal Reporting service. If the report name contains white spaces, these must be replaced with %20. e.g. Location Measures should be passed as Location%20Measures.

Request Body schema:
required

The data model containing report parameter details. Must not be empty.

siteName
required
string

The name of the site to which the user belongs. Must be a valid site name in the Pitram Portal.

Array of objects (ReportParameterModel)

A list of report parameters. This list must not be empty. See Report Parameter

Array of objects (ReportSummaryLevelModel)

A list of object/attributes that define the summary levels for the report. This list must not be empty. See Report Summary Level Model

Responses

Request samples

Content type
{
  • "siteName": "QAVM15",
  • "reportParameterModels": [
    ],
  • "reportSummaryLevelModels": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Creates a run job to allow a client to run a report

Once the job is create, it will run asynchronously and this returns straight away (with no data)

Example parameter values

Object: Period, Attribute: Month, Value is 201703 (instead of Mar-2017)

Object: Period, Attribute: Week, Value is 2014 12 (instead of 2014 Week 14)

The date code can be found in the view: PITRAMReporting.dbo.V_SHIFTLOG

Object: Period, Attribute: Macro, Value is LAST 120 DAYS. This must be English regardless of the current language in the system.User can find the English name in the table PITRAMReporting.dbo.PERIODMACROS.

If the site is using multiple shift rosters, the Value is LAST 120 DAYS(P). The P is the roster code of the target shift roster which can be found via the Reference Edit service in the Pitram Portal.

  • Security Resource Id : v1/reports/run

  • Security Resource Action : post

  • Portal Web Version : 4.8

Authorizations:
oauth2
path Parameters
reportName
required
string

The name of the report to be generated in the Pitram Portal Reporting service. Must be a valid report configured in the Pitram Portal Reporting service. If the report name contains white spaces, these must be replaced with %20. e.g. Location Measures should be passed as Location%20Measures.

Request Body schema:
required

The report model.

domain
required
string

The domain name of the user. Must be a valid domain name or use localhost for local user

userName
required
string

The user name of the user. Must be a valid user name in the Pitram Portal

password
required
string

The password of the user. Must be a valid password for the user

siteName
required
string

The name of the site to which the user belongs. Must be a valid site name in the Pitram Portal

fileName
required
string

The output file name of the report. Must be a valid file name accepted by the Windows OS, with file extension

fileFormat
required
string

The output file format of the report. Must be one of the follow formats. (Word, PDF, Excel, ExcelData, CSV, XML, TAB)

fileLocation
required
string

The output location of the report. Must be a valid location in the target system. e.g. c:\outputPath\MyReports

orientation
required
string

The output orientation of the report. Either Portrait or Landscape.

cultureName
string

Gets or sets the name of the culture.

Array of objects (ReportParameterModel)

A list of report parameters. This list must not be empty. See Report Parameter Model

Array of objects (ReportSummaryLevelModel)

A list of object/attributes that define the summary levels for the report. This list must not be empty. See Report Summary Level Model

Responses

Request samples

Content type
{
  • "domain": "localhost",
  • "userName": "testuser",
  • "password": "test",
  • "siteName": "QAVM14",
  • "fileName": "FileNameA.pdf",
  • "fileFormat": "PDF",
  • "fileLocation": "c=\\temp\\PrisTest",
  • "orientation": "Portrait",
  • "reportParameterModels": [
    ],
  • "reportSummaryLevelModels": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

ShiftPlansV1

Get all tasks for a given shift plan.

The request can ask for duration including either historic and/or current shift. However, only current shift result will include any actuals information.

Deltas notes:

As of the versions mentioned below in the history notes, this route can now return deltas. As per other routes, to get delta information, include in the resultsTime from a previous request to the prev-results-time parameter. As always, deltas are not always possible, depending on what else has happened between this call and prev-results-time (e.g. reference data publishing, a shift changes etc).

If the query parameter prop-times=true is included, then each task returned will also include a propertyEventTimes list. This will list the event times of any events updating a task. Note these are only added for task update events, so for a new task, it will NOT include the times for all properties (as these will all just be equal to lastModificationTime). A new task will sometimes submit a task update event under the hood, so sometimes we may have property updates for these.

  • Security Resource Id : v1/shiftplansv1

  • Security Resource Action : get

  • BMWS Version 4.10.1.313

History

4.14.0.47 added multi location support

PRIS 1.13.0.2, BMS 10.0.x added support deltas and property update information

Authorizations:
oauth2
path Parameters
planId
required
integer <int32>

The Id of the shift plan the tasks belongs to.

query Parameters
start
string

(Optional) Start time for the plan result set.

end
string

(Optional) End time for the plan result set.

roster
string

(Optional) Shift Roster code.

bshift
string

(Optional) Number of shifts to look backward for the plan result set.

fshift
string

(Optional) Number of shifts to look forward for the plan result set.

sysinfo
string

(Optional) Comma delimited list of system information we want included in the results.
Current options: refdataupdates, servertime

prev-results-time
string <date-time>

Optional time of ref data and delta results of previous call.

prop-times
boolean

(Optional) If true, results will include the event times of each property updated.

Responses

Response samples

Content type
{
  • "updatesOnly": true,
  • "resultsTime": "2019-08-24T14:15:22Z",
  • "deletedTasks": [
    ],
  • "shifts": [
    ],
  • "systemInfo": {
    },
  • "tasks": [
    ]
}

Create a new Shift planner task.

Although all fields are marked as optional, they are not all actually optional. As there are many inter-field validations, we cannot determine which are required and which are optional until we get to the back end server, so they are just all marked as optional, but may still fail validation if not present.

  • Security Resource Id : v1/shiftplansv1

  • Security Resource Action : post

  • BMWS Version 4.10.0.1

History 4.14.0.47 added multi location support

Authorizations:
oauth2
path Parameters
planId
required
integer <int32>

The Id of the shift plan the task belongs to.

Request Body schema:
required

An object of shift plan values containing the properties to set on the new task

clientId
integer <int32>

Pitram Client Id

externalTaskId
string

A local taskId we map back to the actual taskId created by the server. An external app may use this to map a task it created back to that task being sent back as part of server GET results.

locationCode
required
string

Location code

expectedStartTime
required
string <date-time>

The expected start time for the task. Note that if we have using CalculateDuration, this is used to determined which shift the task should be against. Formatted to ISO 8601 UTC date format YYYY-MM-DDThh:mm:ss[.mmm]Z (e.g. 2012-03-29T10:05:45-06:00Z)

expectedDuration
string

Expected duration formatted as a ISO 8601 duration format.

Note that this is required, EXCEPT when CalculateDuration is set, in which case the server will determine the duration. In this case this property will not be used, and will be ignored if supplied.

ISO 8601 Durations are expressed using the following format, where (n) is replaced by the value for each of the date and time elements that follow the (n):

P(n)Y(n)M(n)DT(n)H(n)M(n)S

Where:

P is the duration designator(referred to as "period"), and is always placed at the beginning of the duration. Y is the year designator that follows the value for the number of years. M is the month designator that follows the value for the number of months. W is the week designator that follows the value for the number of weeks. D is the day designator that follows the value for the number of days. T is the time designator that precedes the time components. H is the hour designator that follows the value for the number of hours. M is the minute designator that follows the value for the number of minutes. S is the second designator that follows the value for the number of seconds. For example:

P3Y6M4DT12H30M5S

Represents a duration of three years, six months, four days, twelve hours, thirty minutes, and five seconds.

ref: https://www.digi.com/resources/documentation/digidocs/90001437-13/reference/r_iso_8601_duration_format.htm

plannedTaskType
string

Task type. Valid values are

  • equipment
  • location
eventTime
string <date-time>

Time of this task add/update Formatted to ISO 8601 UTC date format YYYY-MM-DDThh:mm:ss[.mmm]Z (e.g. 2012-03-29T10:05:45-06:00Z)

locationStatusCode
string

Location status code (only used for location task types)

locationStatusClassificationCode
string

Location status classification code (only used for location task types)

quantity
number <double>

The target value

materialCode
string

Material code (only used for movement tasks)

measureCode
string

Measure code

destinationCode
string

Destination code. Now superseded by DestinationCodeList

destinationCodeList
Array of strings

List of Destination codes. (only used for movement tasks)

description
string

Task description (if manually set)

priority
string

Task priority. Valid values are

  • High
  • Medium
  • Low
Array of objects (TaskStatusChange)

Task status changes

Array of objects (TaskPersonAllocationPostModel)

Task person allocations (primary and secondary)

Array of objects (TaskNote)

List of task notes. If updating a task, then this list just contains edits to be applied to the existing notes.

displayColour
string

Display colour as hex string (if manually set)

alarmThreshold
integer <int32>

Alarm threshold that a task's scheduled vs actuals ratio must break before raising an alarm.

equipmentCode
string

Equipment code

equipmentStatus
string

Equipment target status code (only used for equipment tasks)

calculateDuration
boolean

Set to tell server to calculate the task duration. When this is set, the ExpectedStartTime is used to determined which shift the task should be against, and the expectedDuration property is not required (and if supplied, will be ignored).

productivity
number <double>

Used with the CalculateDuration to auto calculate a task duration. We calculate duration by dividing target amount of (for example) buckets by productivity

isMultipleLocationTask
boolean

Set if task is allows multiple locations

completeOnStatusChange
boolean

Automatic completion of a task when changing status (location status for location tasks and equipment status for equipment tasks)

completeOnLocationChange
boolean

Automatic completion of a task when changing location (only used for equipment tasks)

Responses

Request samples

Content type
{
  • "clientId": 123,
  • "externalTaskId": "ID_12345",
  • "locationCode": "LOCATION1",
  • "expectedStartTime": "2024-06-07T02:29:57.1445074Z",
  • "expectedDuration": "PT1H30M",
  • "plannedTaskType": "equipment",
  • "eventTime": "2024-06-07T02:29:57.1445074Z",
  • "locationStatusCode": "BLAST",
  • "locationStatusClassificationCode": "LOC_CLASS1",
  • "quantity": 850,
  • "materialCode": "ORE",
  • "measureCode": "TONNE",
  • "destinationCode": "",
  • "destinationCodeList": [
    ],
  • "description": "Truck1 operating at Location A",
  • "priority": "Medium",
  • "statusChanges": [
    ],
  • "personnelAllocations": [
    ],
  • "taskNotes": [
    ],
  • "displayColour": "#e7a700",
  • "alarmThreshold": 0,
  • "equipmentCode": "DT001",
  • "equipmentStatus": "OPER",
  • "calculateDuration": false,
  • "productivity": 10.5,
  • "isMultipleLocationTask": false,
  • "completeOnStatusChange": false,
  • "completeOnLocationChange": false
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Get the details of a single shift plan task

This will currently only search the current shift.

  • Security Resource Id : v1/shiftplansv1

  • Security Resource Action : get

  • BMWS Version 4.10.1.313

History 4.14.0.47 added multi location support

Authorizations:
oauth2
path Parameters
planId
required
integer <int32>

The Id of the shift plan the task belongs to.

taskId
required
string

The id of the task

Responses

Response samples

Content type
{
  • "result": {
    }
}

Delete a single shift plan task

  • Security Resource Id : v1/shiftplansv1

  • Security Resource Action : delete

  • BMWS Version 4.10.0.1

Authorizations:
oauth2
path Parameters
planId
required
integer <int32>

The Id of the shift plan the task belongs to.

taskId
required
string

the id of the task

query Parameters
clientId
integer <int32>

(Optional, but recommended) Client id to use for the event created

eventTime
string <date-time>

(Optional) If not set, current time is used

Responses

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Update an existing shift plan task.

  • Security Resource Id : v1/shiftplansv1

  • Security Resource Action : patch

  • BMWS Version 4.10.0.1

History 4.14.0.47 added multi location support

Authorizations:
oauth2
path Parameters
planId
required
integer <int32>

The Id of the shift plan the task belongs to.

taskId
required
string

The id of the task to be updated

Request Body schema:
required

an object of shift plan values containing the changes to apply for the task

clientId
integer <int32>

Pitram Client Id

plannedTaskType
string

Task type. Valid values are

  • equipment
  • location
eventTime
string <date-time>

Time of this task add/update Formatted to ISO 8601 UTC date format YYYY-MM-DDThh:mm:ss[.mmm]Z (e.g. 2012-03-29T10:05:45-06:00Z)

locationCode
string

Location code

locationStatusCode
string

Location status code (only used for location task types)

locationStatusClassificationCode
string

Location status classification code (only used for location task types)

quantity
number <double>

The target value

materialCode
string

Material code (only used for movement tasks)

measureCode
string

Measure code

destinationCode
string

Destination code. Now superseded by DestinationCodeList

destinationCodeList
Array of strings

List of Destination codes. (only used for movement tasks)

description
string

Task description (if manually set)

priority
string

Task priority. Valid values are

  • High
  • Medium
  • Low
Array of objects (TaskStatusChangePatch)

Task status changes

expectedStartTime
string <date-time>

The expected start time Formatted to ISO 8601 UTC date format YYYY-MM-DDThh:mm:ss[.mmm]Z (e.g. 2012-03-29T10:05:45-06:00Z)

expectedDuration
string

Expected duration formatted as a ISO 8601 duration format ISO 8601 Durations are expressed using the following format, where (n) is replaced by the value for each of the date and time elements that follow the (n):

P(n)Y(n)M(n)DT(n)H(n)M(n)S

Where:

P is the duration designator(referred to as "period"), and is always placed at the beginning of the duration. Y is the year designator that follows the value for the number of years. M is the month designator that follows the value for the number of months. W is the week designator that follows the value for the number of weeks. D is the day designator that follows the value for the number of days. T is the time designator that precedes the time components. H is the hour designator that follows the value for the number of hours. M is the minute designator that follows the value for the number of minutes. S is the second designator that follows the value for the number of seconds. For example:

P3Y6M4DT12H30M5S

Represents a duration of three years, six months, four days, twelve hours, thirty minutes, and five seconds.

ref: https://www.digi.com/resources/documentation/digidocs/90001437-13/reference/r_iso_8601_duration_format.htm

Array of objects (TaskPersonAllocationPostModel)

Task person allocations (primary and secondary)

Array of objects (TaskNotePatch)

List of task notes. If updating a task, then this list just contains edits to be applied to the existing notes.

displayColour
string

Display colour as hex string (if manually set)

alarmThreshold
integer <int32>

Alarm threshold that a task's scheduled vs actuals ratio must break before raising an alarm.

equipmentCode
string

Equipment code

equipmentStatus
string

Equipment target status code (only used for equipment tasks)

calculateDuration
boolean

Set to tell server to calculate the task duration. When this is set, the ExpectedStartTime is used to determined which shift the task should be against, and the expectedDuration property is not required (and if supplied, will be ignored).

productivity
number <double>

Used with the CalculateDuration to auto calculate a task duration. We calculate duration by dividing target amount of (for example) buckets by productivity

isMultipleLocationTask
boolean

Set if task is allows multiple locations

completeOnStatusChange
boolean

Automatic completion of a task when changing status (location status for location tasks and equipment status for equipment tasks)

completeOnLocationChange
boolean

Automatic completion of a task when changing location (only used for equipment tasks)

Responses

Request samples

Content type
{
  • "clientId": 123,
  • "plannedTaskType": "equipment",
  • "eventTime": "2024-06-07T02:29:57.155507Z",
  • "locationCode": "LOCATION1",
  • "locationStatusCode": "BLAST",
  • "locationStatusClassificationCode": "LOC_CLASS1",
  • "quantity": 850,
  • "materialCode": "ORE",
  • "measureCode": "TONNE",
  • "destinationCode": "",
  • "destinationCodeList": [
    ],
  • "description": "Truck1 operating at Location A",
  • "priority": "Medium",
  • "statusChanges": [
    ],
  • "expectedStartTime": "2024-06-07T02:29:57.155507Z",
  • "expectedDuration": "PT1H30M",
  • "personnelAllocations": [
    ],
  • "taskNotes": [
    ],
  • "displayColour": "#e7a700",
  • "alarmThreshold": 0,
  • "equipmentCode": "DT001",
  • "equipmentStatus": "OPER",
  • "calculateDuration": false,
  • "productivity": 10.5,
  • "isMultipleLocationTask": false,
  • "completeOnStatusChange": false,
  • "completeOnLocationChange": false
}

Surveying

Set haul distance information.

POST haul distances to the Pitram Reporting DISTANCE table. See: GET Haul Distances for Time Period

  • Security Resource Id : v1/surveying/haul-distances

  • Security Resource Action : post

  • BMWS Version: 4.11.0

Authorizations:
oauth2
query Parameters
allow-partial-updates
boolean

(Optional) If set to true (by default), then route will submit what is can and log out any failed, if false, if any one insert fails, they all failed

Request Body schema:
required

Haul-distances to add/update

required
Array of objects (HaulDistanceItem)

Collection of haul distance items

Responses

Request samples

Content type
{
  • "distances": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Search for haul distance information for a supplied time period.

GET haul distance information for a supplied time period that can be used to populate the Pitram Reporting DISTANCE table. See: POST Haul Distances (above).

  1. If no start/end time passed in model for filtering, return the latest results for each source/destination;
  2. If start and end time are used, the query will simply return the records within the interval as stored in the database. It will not try to return the most recent distances prior to that period.

  • Security Resource Id : v1/surveying/haul-distances

  • Security Resource Action : get

  • BMWS Version: 4.11.0

Authorizations:
oauth2
Request Body schema:
required

model for querying haul-distances

queryTime
string <date-time>

(Optional) The most recent haul distances prior to this time will be returned, based on the effectivedatetime.

sources
string

(Optional) Comma delimited list of source locations to filter on

destinations
string

(Optional) Comma delimited list of destinations to filter on

start
string <date-time>

(Optional) The start time to filter effectivedatetime

end
string <date-time>

(Optional) The end time of effectivedatetime

descriptions
boolean

Allows us to toggle whether or not to return descriptions as well as codes in the results

Responses

Request samples

Content type
{
  • "queryTime": "2019-08-24T14:15:22Z",
  • "sources": "string",
  • "destinations": "string",
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "descriptions": true
}

Response samples

Content type
{
  • "results": [
    ]
}

System

Gets a client Id that can be used to post Pitram events. This newer client Id route can handle passing special characters.

Using this route is preferable over the other legacy clientId route, as passing the data as query parameters allows for better special character support.

Gets an Id that has been allocated by the Pitram system. Whenever Pitram events are generated via PRIS, the client Id of the submitting consumer is always recorded with each event.

This route passes the parameters as query parameters rather than part of the URL, so it can handle special characters such as /, as long as the query parameters are encoded. Prefer this route over the other older version.

Note that a unique client Id is keyed on machineName and appName, but not userName. However we still require userName for logging purposes.

  • Security Resource Id : v1/system/clientid

  • Security Resource Action : get

  • BMWS Version: 3.46.2

Authorizations:
oauth2
query Parameters
username
required
string

Username of the requesting client

machineName
required
string

Machine name of the requesting client

appName
required
string

An identifier for the requesting application, to help identify which application is assigned against a particular client id

Responses

Response samples

Content type
{
  • "clientId": 0
}

Gets a client Id that can be used to post Pitram events.

Using the other clientId route is preferable over this legacy clientId route, as the other passes the data as query parameters, which allows for better special character support.

Gets an Id that has been allocated by the Pitram system. Whenever Pitram events are generated via PRIS, the client Id of the submitting consumer is always recorded with each event.

Note that a unique client Id is keyed on machineName and appName, but not userName. However we still require userName for logging purposes.

  • Security Resource Id : v1/system/clientid

  • Security Resource Action : get

  • BMWS Version: 3.46.2

Authorizations:
oauth2
path Parameters
userName
required
string

Username of the requesting client

machineName
required
string

Machine name of the requesting client

appName
required
string

An identifier for the requesting application, to help identify which application is assigned against a particular client id

Responses

Response samples

Content type
{
  • "clientId": 0
}

Submits weighbridge data.

Submit a list of Weighbridge data models. Each item is put through the external item weighbridge validator. Depending on the item, the validator may either create a movement event or create an external item that can then be corrected via the weighbridge panel in Data Acquisition.

  • Security Resource Id : v1/system/externalevents/submitwbdata

  • Security Resource Action : post

  • BMWS Version: 4.15.0

Authorizations:
oauth2
Request Body schema:
required

The list containing Weighbridge data models.

clientId
integer <int32>

Client Id for submitting client

Array of objects (WeighBridgeDataModel)

List of WeighBridgeDataModels

Responses

Request samples

Content type
{
  • "clientId": 0,
  • "weighBridgeDataModels": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Submits the unmapped entity event.

  • Security Resource Id : v1/system/externalevents/unmappedentity

  • Security Resource Action : post

  • BMWS Version: 4.10.0

Authorizations:
oauth2
Request Body schema:
required

The unmapped entity data model.

entityId
required
string

Gets or sets the entity system identifier.

entityDescription
required
string

Gets or sets the entity description.

entityType
required
string

Gets or sets the type of the entity. This will be a valid Pitram entity type (e.g. equipment, person, waypoint)

entityMappingAttributeId
required
string

This is the name of the mapping attribute used in reference data for this entity mapping (e.g. ThirdPartyId1, ThirdPartyId2 etc)

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "entityId": "string",
  • "entityDescription": "string",
  • "entityType": "string",
  • "entityMappingAttributeId": "string",
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Submits the unmapped MST data event.

Records unmapped MST position event data for Equipment or Personnel. This request is usually used instead of the request Post Equipment at Position and the request Post Person at Position, in the case of missing mappings between MST and the Pitram Reference Data.

Note that you can now use the more generic request POST Unmapped Entities at system/externalevents/unmappedentity

  • Security Resource Id : v1/system/referencedata/referencegroups/version

  • Security Resource Action : post

  • BMWS Version: 4.0.0

Authorizations:
oauth2
Request Body schema:
required

The unmapped MST data model.

positionId
required
string

Gets or sets the position identifier.

mstEventDateTimeUtc
required
string

Gets or sets the string representation of the MST event time (UTC).

entityUnmapped
required
boolean

Gets or sets a value indicating whether [entity unmapped].

nearLocationUnmapped
required
boolean

Gets or sets a value indicating whether [near location unmapped].

farLocationUnmapped
required
boolean

Gets or sets a value indicating whether [far location unmapped].

entityId
required
string

Gets or sets the entity system identifier.

entityDescription
required
string

Gets or sets the entity description.

entityType
required
string

Gets or sets the type of the entity.

nearLocationId
required
string

Gets or sets the nearest location (waypoint) system identifier.

nearLocationDescription
required
string

Gets or sets the nearest waypoint description.

farLocationId
string

Gets or sets the location (waypoint) system identifier.

farLocationDescription
string

Gets or sets the second nearest waypoint description.

pathPercentage
integer <int32>

Gets or sets The percentage the entity is located at, along the path between the nearest and second-nearest Locations.

clientId
required
integer <int32>

Client Id for submitting client. Obtain via v1/system/clientid

eventDateTimeUtc
required
string <date-time>

Time of the Pitram event in ISO 8601 UTC, format. Must not be greater than the current time

roster
string

Shift roster code of the event to be created. If not supplied, the default shift roster of the Business Model Server will be used. If supplied, must be a valid token in the ShiftRoster reference data group.

Responses

Request samples

Content type
{
  • "positionId": "string",
  • "mstEventDateTimeUtc": "string",
  • "entityUnmapped": true,
  • "nearLocationUnmapped": true,
  • "farLocationUnmapped": true,
  • "entityId": "string",
  • "entityDescription": "string",
  • "entityType": "string",
  • "nearLocationId": "string",
  • "nearLocationDescription": "string",
  • "farLocationId": "string",
  • "farLocationDescription": "string",
  • "pathPercentage": 0,
  • "clientId": 0,
  • "eventDateTimeUtc": "2019-08-24T14:15:22Z",
  • "roster": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Submits the general services log message.

  • Security Resource Id : v1/system/logging/gslog

  • Security Resource Action : post

  • BMWS Version: 4.3.0

Authorizations:
oauth2
Request Body schema:
required

The general services batch log message data model.

clientId
required
integer <int32>

Client Id for submitting client

required
Array of objects (GeneralServicesLogMessageDataModel)

Data Model for logging message by using General Services.

Responses

Request samples

Content type
{
  • "clientId": 0,
  • "messages": [
    ]
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Log message for diagnostics (e.g. Mobile device)

Allow a remote application (e.g. mobile app) to submit it's logging to PRIS. All this does is trace out so we can then use a tool like debug view to view the logging live (may need to enable kernel tracing)

No BMS or Connector dependencies

Request Body schema:
required

The log data

level
string

The level

message
string

The log message

Responses

Request samples

Content type
{
  • "level": "string",
  • "message": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Retrieve active list contents from Portal reference data.

The optional actlist query parameter was added after there were problems using some active list names with some characters in the URL, even when URL encoded. Using the actlist query parameter is now the recommended approach, but need to support backwards compatibility so this route can still be used without it.

  • Security Resource Id : v1/system/referencedata/referencegroups/activelists

  • Security Resource Action : get

  • DCWS Version: 3.46.2

Authorizations:
oauth2
path Parameters
activelistOrGroupName
required
string

If actlist is supplied as a query parameter, this is the reference group name. If actlist not is supplied as a query parameter then this hold the active list name

query Parameters
actlist
string

(Optional) Name of active list to get contents from. This MUST be URL encoded

Responses

Response samples

Content type
{
  • "resultData": [
    ],
  • "fieldDescriptions": [
    ],
  • "updatesOnly": true,
  • "resultsTime": "string"
}

Retrieve active list contents from BMS reference data

Recommended to use the version with actlist as a query parameter

  • Security Resource Id : v1/system/referencedata/referencegroups/activelists

  • Security Resource Action : get

  • BMWS Version: 4.6.0

Authorizations:
oauth2
path Parameters
activelistname
required
string

Name of active list to get contents from

dataTokenGroup
required
string

Name of reference group the active list belongs to

Responses

Response samples

Content type
{
  • "resultData": [
    ],
  • "fieldDescriptions": [
    ],
  • "updatesOnly": true,
  • "resultsTime": "string"
}

Retrieves the current major version.

  • Security Resource Id : v1/system/referencedata/majorversion

  • Security Resource Action : get

  • BMWS Version: 8.0.0

Authorizations:
oauth2

Responses

Response samples

Content type
{
  • "majorVersion": 0
}

Gets the token codes by attribute values.

The method allows to define which server should be queried. There are 2 servers supported: DOME and BMS.

  • Security Resource Id : v1/system/referencedata/referencegroups

  • Security Resource Action : get

  • BMWS Version: 3.46.2

  • DCWS Version: 3.46.2

Authorizations:
oauth2
path Parameters
referenceGroupName
required
string

Name of the reference group.

query Parameters
searchAttribute
string

(Optional) The search attribute. This string mimic a JSON object which contains attribute name and values. The attribute is supported only for DOME. Example: {Name:"Model",Values:["TRUCKMODEL01", "TRUCKMODEL02"]}

server
string

(Optional) Defines the server to query. It can be either DOME or BMS. The default server (if value not set) is DOME.

Responses

Response samples

Content type
{
  • "tokenCodeAttributeValueModels": [
    ]
}

Get active lists for a ref data group.

  • Security Resource Id : v1/system/referencedata/referencegroups/activelists

  • Security Resource Action : get

  • BMWS Version: 4.6.0

Authorizations:
oauth2
path Parameters
referenceGroupName
required
string

Reference group name to get active list for

Responses

Response samples

Content type
{
  • "resultData": [
    ],
  • "fieldDescriptions": [
    ],
  • "updatesOnly": true,
  • "resultsTime": "string"
}

Retrieve attribute definitions for a reference group.

  • Security Resource Id : v1/system/referencedata/referencegroups/attributes-definitions

  • Security Resource Action : get

  • BMWS Version: 8.0.0

Authorizations:
oauth2
path Parameters
referenceGroupName
required
string

Reference group

query Parameters
cu
string

(Optional) Culture to use for the attribute display name

Responses

Response samples

Content type
{
  • "version": "string",
  • "attributeDefinitions": [
    ]
}

Retrieve tokens with requested attribute values.

Returns a list of token objects, where each object has a field matching the requested attribute. Note that all attribute values, including numeric, are returned as strings.

  • Security Resource Id : v1/system/referencedata/referencegroups/attributes

  • Security Resource Action : get

  • BMWS Version: 8.0.0

Authorizations:
oauth2
path Parameters
referenceGroupName
required
string

Reference group

query Parameters
attributes
string

(Optional) Comma delimited string of attributes to get. If missing, return all attributes.

filter
string

(Optional) JSON formatted list of attribute key value pairs to filter the results upon. For this call, we consider code and description as an attribute, so may use this to filter upon them. Example value: [{'code': 'DT001'}, {'IsTrain': 1}] If missing, no filtering.

search-hierarchy
boolean

(Optional) Whether to look up for attributes through business objects hierarchy. If set to False, the default values for the attributes won't be used, i.e will return only attributes that is set for a given token explicitly. Set to True by default.

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Get a single attribute value for a token

Get an attribute value from reference data for a single token. See referencedata/referencegroups/{referencegroupname}/attributes for a more comprehensive request.

  • Security Resource Id : v1/system/referencedata/referencegroups/attributes

  • Security Resource Action : get

  • DCWS Version: 3.46.2

Authorizations:
oauth2
path Parameters
referenceGroupName
required
string

Reference group

tokenCode
required
string

Reference data token code

attributeName
required
string

Attribute to get value of

Responses

Response samples

Content type
{
  • "attributeValue": "string"
}

Get a list of reference group tokens.

  • Security Resource Id : v1/system/referencedata/referencegroups/tokens

  • Security Resource Action : get

  • BMWS Version: 4.6.0

Authorizations:
oauth2
path Parameters
referenceGroupName
required
string

Name of reference group

query Parameters
filterAttribute
string

(Optional) Single json object {attribute name, attribute code}, as a string, attribute filter

header Parameters
Accept-Language
string
Default:

(Optional) Culture code for localisation of results.

Responses

Response samples

Content type
{
  • "referenceGroupVersion": 0,
  • "results": [
    ]
}

Delete reference group tokens.

Existing tokens are removed using a DELETE call:

  • If a token to be deleted does not exist, an error is returned

Validation fails if:

  • the transaction with the given key does not exist.
  • the transaction with the given key is not open.
  • the reference group is not linked to the transaction defined by the TransactionKey.
  • the reference group does not exist in reference data.

Note: By default the deleted token are not recoverable. i.e. calling Create or Update will not restore the token in the reference data. If the deleted tokens are to be restored, the flag ReferenceData must be included in the DOMEConfiguration table of the DomeProduction database:

ServiceName Sectionname Attribute Description
ReferenceData Import RestoreDeletedToken true

Token security

  • Security Resource Id : v1/system/referencedata/referencegroups/tokens
  • Security Resource Action : delete

Minimum versions

  • DCWS Version 4.10.0.195
Authorizations:
oauth2
path Parameters
referenceGroupName
required
string

Reference Group Name

query Parameters
codes
required
string

A comma delimited list of token codes to be deleted. Note: We do not use commas in token codes so it is safe to use it as a separator. However, in other scenarios we may want to use values with commas. In that case !2c will be used as a substitution for commas (,). E.g. string,with,commas will be represented as string!2cwith!2ccommas

transactionKey
required
string

Transaction under which the current request will be processed

userName
string

(Optional) User initiating the request

machineName
string

(Optional) Machine name where request was initiated

Responses

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Create or update reference group tokens.

Add or update reference data tokens.

Note: Create Reference Data Tokens (PATCH) and Update Reference Data Tokens (PATCH) use the same resource URL and also have the same implementation.

  • If a token attribute value is provided, the existing value will be overwritten
  • If a token attribute value is not provided, the existing value will stay unchanged
  • If a token attribute value is set to empty string (“”), the existing value will be cleared

Validation fails if:

  • the transaction with the given key does not exist.
  • the transaction with the given key is not open.
  • the reference group is not linked to the transaction defined by the TransactionKey.
  • the reference group does not exist in reference data.

Token Validation fails if:

  • any token code is empty
  • any token code contains any of the following invalid characters ,></'"|~`!@%^&*+=
  • a token code exceeds maximum length (20 characters).
  • a token abbreviation or description contains invalid characters. Invalid characters are @"<>?'""^`·~！@#￥%……&*+={【}】、|：‘“；《，》’。？/＊＆％＃＠".
  • a token description for a new token is empty.
  • a token description for a new token is not unique.
  • a token description exceeds maximum length (50 characters)
  • a token abbreviation for a new token is empty.
  • a token abbreviation for a new token is not unique.
  • a token abbreviation exceeds maximum length (50 characters)
  • reference data attributes for the given token are not defined in reference data.
  • a token is added and removed to/from the same active list at the same time.
  • a token is added to an invalid active list.
  • a token is removed from an invalid active list.
  • a token uses an invalid reference data attribute value which should represent a token from an associated reference group

Token Security

  • Security Resource Id : v1/system/referencedata/referencegroups/tokens
  • Security Resource Action : patch

Minimum versions

  • DCWS Version 4.10.0.195
Authorizations:
oauth2
path Parameters
referenceGroupName
required
string

Reference Group Name

Request Body schema:
required

The reference data token post model.

Array of objects (ReferenceDataTokenRawModel)

List of reference data tokens.

transactionKey
required
string

The transaction key used for reference data operations.

userName
string

The username of the user associated with the transaction

machineName
string

An identifier for the machine associated with the transaction

Responses

Request samples

Content type
{
  • "referenceDataTokens": [
    ],
  • "transactionKey": "string",
  • "userName": "string",
  • "machineName": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Retrieve reference group minor published version.

  • Security Resource Id : v1/system/referencedata/referencegroups/version

  • Security Resource Action : get

  • BMWS Version: 3.46.2

  • DCWS Version: 3.46.2

Authorizations:
oauth2
path Parameters
referenceGroupName
required
string

Name of the reference group.

query Parameters
server
string

(Optional) Defines the server to query. It can be either DOME or BMS. The default server (if value not set) is BMS.

Responses

Response samples

Content type
{
  • "referenceGroupName": "string",
  • "minorVersionNumber": 0
}

Retrieve reference group minor published version for multiple groups.

This action allows to define which server should be queried.

Note: Currently the request has been implemented only for BMS.

  • Security Resource Id : v1/system/referencedata/referencegroups/version

  • Security Resource Action : get

  • BMWS Version: 3.46.2

Authorizations:
oauth2
query Parameters
searchAttribute
string

(Optional) List of reference groups to include in the results, formatted like the following: searchattribute={"values":["Location","Equipment","Person"]}. If empty, returns versions for all existing reference groups

server
string

(Optional) Defines the server to query. Currently only BMS supported (default)

allow-missing
boolean

(Optional) Defaults to false. If set to true, we will still return results if there are missing reference groups. The missing groups will have -1 set for their version.

Responses

Response samples

Content type
{
  • "results": [
    ]
}

End reference data transaction

Ends a reference data transaction (sets its status to 'Closed'). The operation is checking in and publishing the reference groups associated with the transaction.

Note: Publishing can be a time-consuming operation. This call may take longer than other calls to complete (30 seconds or more).

Validation fails if :

  • the transaction with the given key does not exist.
  • the transaction with the given key is not open.

Token security

  • Security Resource Id : v1/system/referencedata/transactions/end
  • Security Resource Action : post

Minimum versions

  • DCWS Version 4.10.0.195
Authorizations:
oauth2
Request Body schema:
required

The reference data transaction header.

transactionKey
required
string

The transaction key used for reference data operations.

userName
string

The username of the user associated with the transaction

machineName
string

An identifier for the machine associated with the transaction

Responses

Request samples

Content type
{
  • "transactionKey": "string",
  • "userName": "string",
  • "machineName": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Rollback reference data transaction

Rolls back a reference data transaction (sets its status to 'Cancelled'). The operation undoes the check out for the reference groups associated with the transaction.

Validation fails if:

  • the transaction with the given key does not exist.

  • the transaction with the given key is not open.

  • Security Resource Id : v1/system/referencedata/transactions/rollback

  • Security Resource Action : post

  • DCWS Version 4.10.0.195

Authorizations:
oauth2
Request Body schema:
required

The reference data transaction header.

transactionKey
required
string

The transaction key used for reference data operations.

userName
string

The username of the user associated with the transaction

machineName
string

An identifier for the machine associated with the transaction

Responses

Request samples

Content type
{
  • "transactionKey": "string",
  • "userName": "string",
  • "machineName": "string"
}

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Get the list of reference data transactions filtered by parameters

No validation, as all parameters are optional.

  • Security Resource Id : v1/system/referencedata/transactions/open/search

  • Security Resource Action : post

  • DCWS Version 4.11.0.0

Authorizations:
oauth2
Request Body schema:
required

The reference data transaction model for filtering

referenceGroups
Array of strings

List of reference group names

userName
string

Gets or sets the name of the user linked to the transaction

machineName
string

Gets or sets the name of the machine initiating the transaction

transactionStatus
integer <int32>
Enum: 0 1 2 3

The transaction status to filter results on 0 = None (The 'unknown' status) 1 = Open (The 'open' transaction status) 2 = Closed (The 'closed' transaction status) 3 = Cancelled (The 'cancelled' transaction status (rollback))

Responses

Request samples

Content type
{
  • "referenceGroups": [
    ],
  • "userName": "string",
  • "machineName": "string",
  • "transactionStatus": 0
}

Response samples

Content type
{
  • "transactions": [
    ]
}

Start reference data transaction.

Starts a reference data transaction (sets its status to 'Open'). The operation also checks out the listed reference groups and associates them with the transaction.

Returns a transaction key

Validation fails if:

  • the list of reference groups is empty

  • the list of reference groups does not contain an existing active reference group.An error with the code 400 is returned.

  • any of the reference groups are already present in another open transaction

  • any of the reference groups are already checked out (e.g.by another PRIS client)

  • Security Resource Id : v1/system/referencedata/transactions/start

  • Security Resource Action : post

  • DCWS Version 4.10.0.195

Authorizations:
oauth2
Request Body schema:
required

The reference data transaction start model.

referenceGroups
required
Array of strings

Non-empty list of reference group names

userName
string

Gets or sets the name of the user linked to the transaction

machineName
string

Gets or sets the name of the machine initiating the transaction

Responses

Request samples

Content type
{
  • "referenceGroups": [
    ],
  • "userName": "string",
  • "machineName": "string"
}

Response samples

Content type
"string"

**Testing route only!** - to examine security claims.

Example of PRIS communicating with dome WCF service to get credentials. Warning: Just an example for testing purposed only, as we don't want to pass the password via the URL (it is passed in plain text not encrypted). The payload is encrypted, just the URL is not, e.g.: "HTTP 704 GET /PrisDev/v1/system/authenticateandgetclaims/auser/apass HTTP/1.1 " This overload is for when no domain is supplied (which is the usual case).

path Parameters
username
required
string

Login username

password
required
string

Password for username

query Parameters
applicationName
string

(Optional) Application name to filter claims

machineName
string

(Optional) Machine (device) name

Responses

Response samples

Content type
"string"

**Testing route only!** - to examine security claims.

Example of PRIS communicating with dome back end service to get credentials. Warning: Just an example for testing purposed only, as we don't want to pass the password via the URL (it is passed in plain text not encrypted). The payload is encrypted, just the URL is not, e.g.: "HTTP 704 GET /PrisDev/v1/system/authenticateandgetclaims/auser/apass HTTP/1.1 "

path Parameters
domain
required
string

Optional Domain

username
required
string

Login username

password
required
string

Password for username

query Parameters
applicationName
string

(Optional) Application name to filter claims

machineName
string

(Optional) Machine (device) name

Responses

Response samples

Content type
"string"

Parameterless test route to get identity.

No BMS or Connector dependencies

  • Security Resource Id : v1/system/security/identity

  • Security Resource Action : get

  • BMWS Version: 3.46.2

Responses

Response samples

Content type
{
  • "user": "string",
  • "authenticationType": "string"
}

Testing route - PRIS communicating to Portal COnnect WCF.

PRIS communicating with Portal Connector WCF service to refresh credentials.

path Parameters
username
required
string

Responses

Response samples

Content type
"string"

Request a security token using either a username/password, or a refresh token

Run this request to create a JWT (Json Web Token) that will contain the claims required to run the other secured PRIS routes.If using username/password, grant type must be set to password. If using a refresh token, grant_type must be set to refresh_token

Note - the body contains a string that is formatted as x-www-form-urlencoded and must be URL encoded

Example1 POST body for username/password - with the x-www-form-urlencoded formatting

grant_type=password&username=myusername&password=my_password&client_id=pitramconnect&device_id=MyPC

Example2 POST body for refresh token - with the x-www-form-urlencoded formatting

grant_type=refresh_token&refresh_token=7f371e5ff20940a5841f21fa4175335f&client_id=pitramconnect&device_id=MyPC

Also note

  • In production this should be over https as the password is in plain text

  • The client_id field may be confusing for us, as we use the term client id for Pitram connections. Client_id is also a standard term in OAuth2 token based security, and is used to identify a client application.

  • The access_token holds the JWT. This has all our claims encoded and is supplied in the header of every request to PRIS

  • If there is a problem with a refersh_token (e.g. not found), the returned error message is not very helpful (invalid_grant). To get more information refer to the PRIS logs.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string

Needs to be set as either password or refresh_token

username
string

Required if using password grant_type

Username as set on Pitram Portal

password
string

Required if using password grant_type

Password as set on Pitram Portal

refresh_token
string

Required if using refresh_token grant_type

Refresh token returned from last token request

client_id
required
string

Application name (to filter claims upon)

device_id
required
string
Default: "MM0001172"

Machine/device name

Responses

Get a list of existing refresh tokens

This may be used by an administrator when a device is lost, or when the security refresh token for a device has been compromised. In this scenario, the refresh token can be removed, which will invalidate any device login.

This allows an administrator to view PRIS security refresh tokens.Refresh tokens are only relevant when PRIS has been configured to use token-based security.

Note not all fields of results are returned No BMS or Connector dependencies

  • Security Resource Id : v1/system/security/token/refreshtokens
  • Security Resource Action : get
Authorizations:
oauth2

Responses

Response samples

Content type
[
  • {
    }
]

Delete refresh token(s).

Allows an administrator to delete a security refresh token.

Selected by either subject (user), or subject/deviceId pair If just subject is supplied, then all tokens for this subject are deleted (can also supply "All" for deviceId to delete all tokens). If subject and device Id are supplied, then we select the token to delete on this pair. No BMS or Connector dependencies.

  • Security Resource Id : v1/system/security/token/refreshtokens
  • Security Resource Action : delete
Authorizations:
oauth2
path Parameters
subject
required
string

(Optional) Subject to delete. Can contain !2F for / and !5C for \ for subjects with domains.

deviceId
required
string

(Optional) DeviceId to delete. Can be the string "null" for null entries, "All" for all entries, "EMPTY_STRING" for the empty string "" entries.

Responses

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Preview deleting refresh token(s).

Selected by either subject (user), or subject/deviceId pair. Perform a dry run without performing the delete, but returning the number of matched tokens that would have been deleted. This makes it easier to manually test all the code paths.

If just subject is supplied, then all tokens for this subject are deleted (can also supply "All" for deviceId to delete all tokens). If subject and device Id are supplied, then we select the token to delete on this pair.

No BMS or Connector dependencies.

  • Security Resource Id : v1/system/security/token/refreshtokens/preview
  • Security Resource Action : delete
Authorizations:
oauth2
path Parameters
subject
required
string

(Optional) Subject to delete. Can contain !2F for / and !5C for \ for subjects with domains.

deviceId
required
string

(Optional) DeviceId to delete. Can be the string "null" for null entries, "All" for all entries, "EMPTY_STRING" for the empty string "" entries.

Responses

Response samples

Content type
{
  • "code": "string",
  • "message": "string"
}

Gets the current server time.

This may be useful if a consuming application needs to adjust a local device time to be in sync with Pitram server time before submitting any data that contains date/time information.

No other server dependencies.

Responses

Response samples

Content type
{
  • "dateTime": "2019-08-24T14:15:22Z",
  • "utcOffset": "string"
}

Gets the current deployed versions of PRIS, BMS, and Dome connector.

  • Security Resource Id : v1/system/serverversions

  • Security Resource Action : get

  • BMWS Version: 4.8.0.56

  • DCWS Version

Authorizations:
oauth2

Responses

Response samples

Content type
{
  • "prisVersion": "string",
  • "bmsVersion": "string",
  • "domeConnectorVersion": "string"
}

Get current shift information.

Optional query parameter - roster

  • Security Resource Id : v1/system/shifts/current

  • Security Resource Action : get

  • BMWS Version: 4.6.0

Authorizations:
oauth2
query Parameters
roster
string

(Optional) Shift roster code. If not supplied, gets the current shift for the default roster

Responses

Response samples

Content type
{
  • "shiftStartDateTimeUtc": "string",
  • "scheduledShiftEndDateTimeUtc": "string"
}