Getting started¶

Authenticate and access an HTTP API¶

Use the OAuth 2.0 Client Credentials grant flow to get an access token.

curl -X POST \
  'https://identity.buhlergroup.com/1514cefd-4c36-4b91-88eb-628d7866a5d8/oauth2/v2.0/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'scope=api://bdac9bc3-a144-47ee-b0d6-beebaa84de68/.default'

The server returns a JSON payload that contains the access token:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "YOUR_ACCESS_TOKEN"
}

Include the access token in the Authorization header with the Bearer prefix.

The available endpoints, their parameters, and response schemas are documented on the API Reference page. You can use the access token directly on this documentation site. Click the "Authorize" button at the top right.

For more details about the authentication, check the authentication page.

Fetch jobs done from the Maintenance API¶

The following example shows how to retrieve a list of completed jobs for a specific plant in the production environment (please find the base URL on the API Reference page):

curl -X GET \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://api.buhlergroup.com/maintenance/v1/plants/{plantId}/jobs-done?startDate=2024-01-01&endDate=2024-12-31"

The response will be in JSON format and contains a paginated list of job records:

{
    "data": [
        {
            "id": "12345",
            "plantId": "{plantId}",
            "jobTitle": "Annual overhaul",
            "doneDate": "2024-06-15",
            "dueDate": "2024-06-01",
            "activityKind": "PREVENTIVE",
            "department": "Maintenance",
            "totalTimeUsedInHours": "4.5",
            "requiredPersonCount": 2,
            "isFinal": true,
            "asset": {
                "tagNumber": "TAG-001",
                "serialNumber": "SN-001",
                "externalReference": "EXT-001"
            },
            "workOrder": {
                "id": "WO-001",
                "remark": "Completed on schedule"
            },
            "carriedOutByUser": {
                "firstname": "John",
                "lastname": "Doe",
                "username": "john.doe"
            },
            "partsUsed": []
        }
    ],
    "page": 1,
    "totalPages": 1,
    "pageSize": 100
}

Fetch jobs planned¶

The following example shows how to retrieve planned maintenance jobs for a specific plant:

curl -X GET \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://api.buhlergroup.com/maintenance/v1/plants/{plantId}/jobs-planned?startDate=2024-01-01&endDate=2024-12-31"

Optional query parameters: assetTagNumber, assetSerialNumber, assetExternalReference.

Fetch assets¶

The following example shows how to retrieve registered assets at a specific plant:

curl -X GET \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://api.buhlergroup.com/maintenance/v1/plants/{plantId}/assets"

Fetch tasks from the Maintenance API¶

The following example shows how to retrieve pending tasks for a specific plant:

curl -X GET \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://api.buhlergroup.com/maintenance/v1/plants/{plantId}/tasks?taskStatus=PENDING"

The taskStatus parameter accepts the following values: PENDING, POSTPONED, NEED_CONFIRMATION, POSTPONEMENT_NEED_APPROVAL, NEED_APPROVAL, CLOSED, NOT_CLOSED.

Create a task¶

The following example shows how to create a new maintenance task:

curl -X POST \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"taskTitle": "Replace filter", "taskDescription": "Replace the main filter unit", "activityKind": "CORRECTIVE", "assignedToRole": "Maintenance Team", "priority": "HIGH", "createdDate": "2024-06-01", "dueDate": "2024-06-15", "incidentDate": "2024-06-01", "asset": {"tagNumber": "TAG-001"}}' \
     "https://api.buhlergroup.com/maintenance/v1/plants/{plantId}/tasks"

The response will indicate the result of the operation:

{
    "status": "SUCCESS",
    "code": "SUCCESS",
    "message": null,
    "data": []
}

POST endpoints return a status of SUCCESS or ERROR. See the Errors page for details.

The activityKind, assignedToRole, and priority fields require company-specific values configured in ProPlant Office. See the Lookup Values page to learn how to retrieve them.

Apply an inventory stock level¶

The following example shows how to submit a stock level update for a spare part:

curl -X PUT \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"id": "PART-001", "quantity": 5, "unit": "PIECE", "remark": "Weekly restock", "isShort": false}' \
     "https://api.buhlergroup.com/maintenance/v1/plants/{plantId}/parts/{partId}/stock-level"

Pagination¶

All Maintenance API GET endpoints return paginated results. Use the page and pageSize query parameters to navigate through results:

page: One-based page index. Defaults to 1.
pageSize: Number of records per page. Defaults to 100.

The response always includes totalPages indicating the total number of available pages.

Further information¶

{"environments":[],"pdf-download":true}