How to set up (on Geotab)

These are the workflows required to implement the solution.

1. In MyGeotab, navigate to People ⇒ Users & Drivers ⇒ Add
   1. Follow the guidelines in the Service Account documentation
2. A valid sessionId is required to allow for data extraction from the target database. To obtain your sessionId from the browser, you can follow the steps outlined in the How to Retrieve a MyGeotab Session ID Geotab Community article. Alternatively, you may use a tool such as Insomnia to make an Authenticate POST request for obtaining your service account user sessionId. For more details on authentication, please review our MyGeotab SDK documentation on authentication.

How to set up (on SAP)

1. Log in to SAP Business Accelerator Hub to access all its features. You can log in using your SAP Community User, and if you don't have one, the system prompts you to enter the information needed to create one. 
2. Once you login, you can access the ‘Settings’ page where you can find the API Settings including your API key, API credentials, and account information. Discover and Explore SAP Business Accelerator Hub in more detail here.
3. You can try out APIs on SAP Business Accelerator Hub to see if they meet your requirements. Follow here.
4. The security scheme defined for an API can be Basic, OAuth 2.0, or API Key authentication depending on the choice of API. More details here.

How to set up Middleware

1. Configure the Middleware to authenticate into MyGeotab using the service account for the appropriate database. 
2. OPTIONAL: 
   It is possible to stream data from a MyGeotab database to a relational database in your environment. Integrations might choose to do this to cache data, or to repurpose data for other needs. Using this method, the Middleware would call the relevant data from the environment instead of making a Geotab API call. See the MyGeotab API Adapter documentation for more details.
3. Make a Get DVIRLog call to pull information regarding defects in an asset associated with a Device or Trailer. Use the API Runner to test below example call to get started:
   
    

api.call("Get", {

    "typeName":"DVIRLog",

    "search":{

        "fromDate": "2023-01-01T16:44:37.170Z",

        "toDate": "2023-11-02T16:44:37.170Z",

        "deviceSearch":{"id":"b33cF"}

    }

}, function(result) {

    console.log("Done: ", result);

}, function(e) {

    console.error("Failed:", e);

});

Sample response object of above API call:

-0: Object

authorityAddress: "2440 Winston Park Drive"

authorityName: "Geotab Inc"

certifyRemark: ""

-dVIRDefects: Array[3]

+0: Object

+1: Object

-2: Object

-defect: Object

id: "b3E04"

isDefectList: false

-defectRemarks: Array[1]

-0: Object

-dVIRDefect: Object

id: "ao2qw_s2Bn064eAlUIBpW-w"

dateTime: "2023-07-26T13:19:07.383Z"

id: "a7nh5nlMZM0-qPZEwrqSrKg"

+mediaFiles: Array[0]

remark: "defect 2"

-user: Object

id: "b41B4FD6A"

length: 1

id: "ao2qw_s2Bn064eAlUIBpW-w"

repairStatus: "NotRepaired"

length: 3

dateTime: "2023-07-26T13:19:10.161Z"

+defectList: Object

+defects: Array[3]

-device: Object

id: "b33CF"

-driver: Object

id: "b41B4FD6A"

driverRemark: "test defect 123"

id: "afO8U5luLCkGeAutJg8TErw"

isInspectedByDriver: true

isRejected: false

logType: "PreTrip"

version: "0000000000002800"

4. Authenticate against your SAP account and create a Maintenance Notification referencing the below POST REQUEST sample. All fields like NotificationText,MaintPriority,NotificationType,MalfunctionStartDate,AssetLocation, MaintNotifLongTextForEdit, and others should be modified in the request as per specific use-case and available configurations to store defect information. Detailed information can be found here.

For all POST operations, before you can send the notification request, you have to get a Cross-Site Request Forgery (CSRF) token. Reference here. For example:

POST <host>/sap/opu/odata/sap/API_MAINTNOTIFICATION/MaintenanceNotification X-CSRF-Token: 4kY1WdNn18CS9xfkFx7EbA==

Request body: application/json

 

{

  "NotificationText": "string",

  "MaintPriority": "s",

  "NotificationType": "st",

  "ReportedByUser": "string",

  "PersonResponsible": "string",

  "MalfunctionEffect": "s",

  "MalfunctionStartDate": "/Date(1492041600000)/",

  "MalfunctionStartTime": "PT15H51M04S",

  "MalfunctionEndDate": "/Date(1492041600000)/",

  "MalfunctionEndTime": "PT15H51M04S",

  "MaintNotificationCode": "stri",

  "MaintNotificationCodeGroup": "string",

  "NotificationCreationDate": "/Date(1492041600000)/",

  "NotificationCreationTime": "PT15H51M04S",

  "RequiredStartDate": "/Date(1492041600000)/",

  "RequiredStartTime": "PT15H51M04S",

  "RequiredEndDate": "/Date(1492041600000)/",

  "RequiredEndTime": "PT15H51M04S",

  "LatestAcceptableCompletionDate": "/Date(1492041600000)/",

  "MaintenanceObjectIsDown": true,

  "MaintNotifLongTextForEdit": "string",

  "TechnicalObject": "string",

  "TechObjIsEquipOrFuncnlLoc": "string",

  "MaintenancePlanningPlant": "stri",

  "MaintenancePlannerGroup": "str",

  "PlantSection": "str",

  "AssetLocation": "string",

  "MainWorkCenterPlant": "stri",

  "MainWorkCenter": "string",

  "MaintenancePlant": "stri",

  "LocationDescription": "string",

  "MaintenanceOrder": "string",

  "MaintenanceActivityType": "str",

  "MaintObjDowntimeDurationUnit": "str",

  "MaintObjectDowntimeDuration": 3.14,

  "TaskList": "string",

  "NotificationReferenceDate": "/Date(1492041600000)/",

  "NotificationReferenceTime": "PT15H51M04S",

  "AssetRoom": "string",

  "MaintNotifExtReferenceNumber": "string",

  "MaintNotifDetectionCode": "stri",

  "MaintNotifDetectionCodeGroup": "string",

  "MaintNotifRqdEndDateTime": "/Date(1492098664000)/",

  "to_Item": {

    "results": [

      {

        "MaintenanceNotification": "string",

        "MaintenanceNotificationItem": "stri",

        "MaintNotifItemText": "string",

        "MaintNotifDamageCodeGroup": "string",

        "MaintNotificationDamageCode": "stri",

        "MaintNotifObjPrtCodeGroup": "string",

        "MaintNotifObjPrtCode": "stri",

        "to_Notif": "string",

        "to_ItemActivity": {

          "results": [

            {

              "MaintNotificationActivity": "stri",

              "MaintenanceNotification": "string",

              "MaintenanceNotificationItem": "stri",

              "MaintNotifActivitySortNumber": "stri",

              "MaintNotifActyTxt": "string",

              "MaintNotifActivityCodeGroup": "string",

              "MaintNotificationActivityCode": "stri",

              "PlannedStartDate": "/Date(1492041600000)/",

              "PlannedStartTime": "PT15H51M04S",

              "PlannedEndDate": "/Date(1492041600000)/",

              "PlannedEndTime": "PT15H51M04S",

              "to_Item": "string",

              "to_Notif": "string"

            }

          ]

        },

        "to_ItemCause": {

          "results": [

            {

              "MaintenanceNotification": "string",

              "MaintenanceNotificationItem": "stri",

              "MaintenanceNotificationCause": "stri",

              "MaintNotifCauseText": "string",

              "MaintNotifCauseCodeGroup": "string",

              "MaintNotificationCauseCode": "stri",

              "MaintNotificationRootCause": "s",

              "to_Item": "string",

              "to_Notif": "string"

            }

          ]

        }

      }

    ]

  },

  "to_Partner": {

    "results": [

      {

        "MaintenanceNotification": "string",

        "PartnerFunction": "st",

        "NotificationPartnerObjectNmbr": "string",

        "Partner": "string",

        "to_Notif": "string"

      }

    ]

  }

}

5. Validate the RESPONSE body such that the API call was successful.