11 Streaming API

11.1 Intro

The Streaming API is used by third-party applications to receive notificatons regarding the creation, update, and deletion of ServiceCall and Activity.


11.2 Functional Overview

Third-party systems are notified about serviceCall and Activity webhook events via POST requests to the specified endpoint.




11.3 Configuration

11.3.1 Add Streaming Role

In order to access and configure the Streaming API, your account must be granted the STREAMING role.

To have the STREAMING role added to your account, please contact support.


11.3.2 Configure Streaming API

After an account has been assigned the Streaming role, the Streaming API can then be configured:



Setting Description
Streaming Enabled Checked or unchecked. When checked, the streaming API configuration will be enabled.
Extended Logs Enabled When checked, extended logs will be recorded for serviceCall and Activity events.
Streaming URL Here you will enter the third-party endpoint that will receive notifications for serviceCall and Activity events.
Auth Method Read-only. Currently, only basic is supported at this point.
Auth user The user authenticated by the third-party to receive notifications.
Auth password Encrypted. The password associated with the auth user that is authenticated by the third-party to receive event notifications.
Streaming Object Types Options include:
  • ServiceCall
  • Activity
Should include whole resource Object When checked, the notification will include the whole resource object, i.e. all data associated with the record. This information will display in the resourceObject section of the event history notification (see examples in section 11.3.2.1 below).
Change Date Time The date and time at which the Streaming API configuration was last changed.
Last Modified By The Admin or Superuser last responsible for changing the Streaming API configuration.

11.3.2.1 Whole Resource Object

Please note differences in payloads returned when the Should include whole resource Object setting is set to TRUE or FALSE:

Note: All example requests included in sections 11.5 and 11.6 are set to TRUE.


TRUE


The following is an example of a body payload when the Should include whole resource Object setting is set to TRUE (checked):


         {
          "eventType": "serviceCall.updated",
          "eventTypeVersion": "1.0",
          "cloudEventsVersion": "0.1",
          "source": "/api/v1/streaming",
          "eventID": "78aa9ca1-1438-4bbe-a6ed-d0fee814c98a",
          "eventTime": "2018-11-21T17:17:31.060Z",
          "contentType": "application/json",
          "extensions": {
            "traceId": "af429d2fdff2e437"
          },
          "data": {
            "resourceId": "7C0A2AC9DC054BC79AD9B08DB1C15A65",
            "resourceDtoVersion": "ServiceCall.24",
            "resourceObject": {
              "leader": null,
              "subject": "Mango CALL JULY 30 001",
              "chargeableEfforts": false,
              "project": null,
              "owners": null,
              "objectGroup": null,
              "resolution": null,
              "syncObjectKPIs": null,
              "inactive": false,
              "partOfRecurrenceSeries": null,
              "contact": null,
              "problemTypeName": null,
              "originCode": "-4",
              "id": "7C0A2AC9DC054BC79AD9B08DB1C15A65",
              "problemTypeCode": null,
              "changelog": null,
              "endDateTime": "2018-07-28T16:21:31Z",
              "priority": "LOW",
              "branches": null,
              "salesOrder": null,
              "dueDateTime": "2018-07-28T21:59:59Z",
              "salesQuotation": null,
              "udfMetaGroups": null,
              "orderReference": null,
              "responsibles": [
                "6DC4AECC05B7D9A22B044850AEC7AE3D"
              ],
              "syncStatus": "IN_CLOUD",
              "statusCode": "-4",
              "code": "350",
              "businessPartner": "BED677A7492E41C98B1D2695A7F6DBAA",
              "projectPhase": null,
              "technicians": [],
              "typeName": null,
              "chargeableMileages": false,
              "chargeableMaterials": false,
              "statusName": "Offen",
              "orderDateTime": null,
              "chargeableExpenses": false,
              "lastChanged": 1542821246824,
              "serviceContract": null,
              "createPerson": "E9F56B2F5CB64DD9B874C3C94B0C5B77",
              "externalId": "1012",
              "groups": null,
              "team": null,
              "typeCode": null,
              "createDateTime": "2018-08-02T13:53:52Z",
              "equipments": [],
              "startDateTime": "2018-07-26T18:21:31Z",
              "location": null,
              "udfValues": null,
              "lastChangedBy": "3502285145884FE48CE27D8B80BE4CD4",
              "incident": null,
              "remarks": null,
              "originName": "E-Mail"
            }
          }
        }


FALSE


The following is an example of a body payload when the Should include whole resource Object setting is set to FALSE (unchecked):


      {
          "eventType": "serviceCall.updated",
          "eventTypeVersion": "1.0",
          "cloudEventsVersion": "0.1",
          "source": "/api/v1/streaming",
          "eventID": "3335741b-209b-4134-b2a8-27a70821be80",
          "eventTime": "2018-11-21T17:17:31.060Z",
          "contentType": "application/json",
          "extensions": {
            "traceId": "af429d2fdff2e437"
          },
          "data": {
            "resourceId": "7C0A2AC9DC054BC79AD9B08DB1C15A65",
            "resourceDtoVersion": null,
            "resourceObject": null
          }
        }

Note that when FALSE, i.e. without payload/object, it means that the “resourceDtoVersion” and “resourceObject” information is NOT included.

11.4 Third-party Notification

Third party systems are notified about events via POST requests to the specified endpoint.

11.4.1 Service Call Example with Payload

The following is an example of the notification sent to a third party in JSON-format:

Note: This request contains the whole resource object payload. See section 11.3.2.1 for details.

{
  "eventType":"serviceCall.updated",
  "eventTypeVersion":"1.0",
  "cloudEventsVersion":"0.1",
  "source":"/api/v1/streaming",
  "eventID":"fd1a0ad1-5cc3-490a-a9ab-9d8eec2f628f",
  "eventTime":"2018-11-05T10:32:17.596Z",
  "contentType":"application/json",
  "extensions":{
    "traceId":"44b4a202640d386e"
  },
  "data":{
    "resourceId":"7C0A2AC9DC054BC79AD9B08DB1C15A65",
    "resourceDtoVersion":"ServiceCall.24",
    "resourceObject":{JSON}
  }
}

11.4.2 Example Reference

Attribute Type Example value Description
eventType String
  • serviceCall.created
  • serviceCall.updated
  • serviceCall.deleted
  • activity.created
  • activity.updated
  • activity.deleted
The type of event which has occured. Often this property is used for routing, observability, policy enforcement, etc.
eventTypeVersion String 1.0 The version of the eventType. This enables the interpretation of data by eventual consumers, requires the consumer to be knowledgeable about the producer.
cloudEventsVersion String 0.1 The version of the CloudEvent specification that the event uses. This enables the interpretation of the context.
source String (URI format) /api/v1/streaming This describes the event producer. Often this will include information such as the type of the event source, the organization publishing the event, and some unique idenfitiers.
eventID String (UUID format) fd1a0ad1-5cc3-490a-a9ab-9d8eec2f628f The ID of the event. The semantics of this string are explicitly undefined to ease the implementation of producers. Enables deduplication.
eventTime String (Timestamp ISO 8601 format) 2018-11-05T10:32:17.596Z The timestamp of when the event happened. Format specified in RFC 3339 (ISO 8601).
contentType String (MediaType format) application/json Describes the data encoding format. Currently available is only application/json.
Extensions Map   This is for additional metadata. Enables a place for custom fields a producer or middleware might want to include.
Extensions.traceId String 44b4a202640d386e Unique indentifier to be able to trace flow in all systems (internal and external) in logs.
data JSON   Contains detail of event
data.resourceId String 7C0A2AC9DC054BC79AD9B08DB1C15A65 Id in FSM of the resource
data.resourceDtoVersion String ServiceCall.24 Activity.23 Version of DTO which is provided in „data.resourceObject”. Only setup if in configuration shouldContainWholeResourceObject is setup true.
data.resourceObject JSON   Whole resource Object in JSON format. Only setup if in configuration the should Inlude whole ResourceObject option is set to TRUE.

11.5 Activity Events

The following are example notifications related to the creation, update, and deletion of activity records.

Note: Third party systems are notified about events via POST requests to the specified endpoint.

11.5.1 Activity Create

11.5.1.1 Request Headers

Method Endpoint
POST Third-party endpoint
Resonse Header Example Explanation
Authorization Basic cDE3OTI4NDA5OTY6VHNhMTIzNDU= The authentication credentials for HTTP authentication.
Content-Type application/json The MIME type of the content. The request body of the Streaming API will be in application/json format.

11.5.1.2 Request Body (with Payload / Object)

Note: This request contains the whole resource object payload. See section 11.3.2.1 for details.

{
  "eventType":"activity.created",
  "eventTypeVersion":"1.0",
  "cloudEventsVersion":"0.1",
  "source":"/api/v1/streaming",
  "eventID":"fd1a0ad1-5cc3-490a-a9ab-9d8eec2f628f",
  "eventTime":"2018-11-05T10:32:17.596Z",
  "contentType":"application/json",
  "extensions":{
    "traceId":"44b4a202640d386e"
  },
  "data":{
    "resourceId":"7C0A2AC9DC054BC79AD9B08DB1C15A65",
    "resourceDtoVersion":"Activity.23",
    "resourceObject":{
        "travelTimeFromInMinutes": 30,
        "subject": "Mango tests C4C",
        "project": null,
        "owners": null,
        "type": "ASSIGNMENT",
        "businessProcessStepAssignments": [],
        "syncObjectKPIs": null,
        "number": null,
        "inactive": false,
        "contact": "F9A2DB4E9BE047348A2682D63408D176",
        "id": "A2DAAC1567F947B0B40499EA6C1E469A",
        "reminderDateTime": null,
        "changelog": null,
        "equipment": null,
        "personal": false,
        "endDateTime": "2018-09-27T11:51:43Z",
        "branches": null,
        "predecessorActivities": [],
        "dueDateTime": "2018-09-27T21:59:59Z",
        "udfMetaGroups": null,
        "topic": null,
        "responsibles": [],
        "subType": null,
        "syncStatus": "IN_CLOUD",
        "object": {
          "objectId": "386CCBA600D14B9E85D120184C11E9B6",
          "objectType": "SERVICECALL"
        },
        "status": "DRAFT",
        "checkedOut": null,
        "previousActivity": null,
        "projectOrdinal": null,
        "code": "71",
        "businessPartner": "0113FEDD7C9D4C4085567BDBBF547EF1",
        "projectPhase": null,
        "sourceActivity": null,
        "travelTimeToInMinutes": 30,
        "address": "54F3509B95F64669B60C6C8586271D2B",
        "earliestStartDateTime": "2018-09-27T09:51:43Z",
        "lastChanged": 1538041914412,
        "durationInMinutes": null,
        "activityTemplate": null,
        "createPerson": "14523B3D57424338858CB56BBF120696",
        "externalId": null,
        "groups": null,
        "team": null,
        "hazardType": null,
        "createDateTime": "2018-09-27T09:51:54Z",
        "startDateTime": "2018-09-27T09:51:43Z",
        "milestone": null,
        "executionStage": "DISPATCHING",
        "location": null,
        "udfValues": null,
        "lastChangedBy": "14523B3D57424338858CB56BBF120696",
        "remarks": null
      }
  }
}

11.5.1.3 Response

The third-party webhook endpoint will return a 200 OK status code when successful.


11.5.2 Activity Update

11.5.2.1 Request Headers

Method Endpoint
POST Third-party endpoint
Resonse Header Example Explanation
Authorization Basic cDE3OTI4NDA5OTY6VHNhMTIzNDU= The authentication credentials for HTTP authentication.
Content-Type application/json The MIME type of the content. The request body of the Streaming API will be in application/json format.

11.5.2.2 Request Body (with Payload / Object)

Note: This request contains the whole resource object payload. See section 11.3.2.1 for details.

{
  "eventType":"activity.updated",
  "eventTypeVersion":"1.0",
  "cloudEventsVersion":"0.1",
  "source":"/api/v1/streaming",
  "eventID":"fd1a0ad1-5cc3-490a-a9ab-9d8eec2f628f",
  "eventTime":"2018-11-05T10:32:17.596Z",
  "contentType":"application/json",
  "extensions":{
    "traceId":"44b4a202640d386e"
  },
  "data":{
    "resourceId":"7C0A2AC9DC054BC79AD9B08DB1C15A65",
    "resourceDtoVersion":"Activity.23",
    "resourceObject":{
        "travelTimeFromInMinutes": 30,
        "subject": "Mango tests C4C",
        "project": null,
        "owners": null,
        "type": "ASSIGNMENT",
        "businessProcessStepAssignments": [],
        "syncObjectKPIs": null,
        "number": null,
        "inactive": false,
        "contact": "F9A2DB4E9BE047348A2682D63408D176",
        "id": "A2DAAC1567F947B0B40499EA6C1E469A",
        "reminderDateTime": null,
        "changelog": null,
        "equipment": null,
        "personal": false,
        "endDateTime": "2018-09-27T11:51:43Z",
        "branches": null,
        "predecessorActivities": [],
        "dueDateTime": "2018-09-27T21:59:59Z",
        "udfMetaGroups": null,
        "topic": null,
        "responsibles": [],
        "subType": null,
        "syncStatus": "IN_CLOUD",
        "object": {
          "objectId": "386CCBA600D14B9E85D120184C11E9B6",
          "objectType": "SERVICECALL"
        },
        "status": "DRAFT",
        "checkedOut": null,
        "previousActivity": null,
        "projectOrdinal": null,
        "code": "71",
        "businessPartner": "0113FEDD7C9D4C4085567BDBBF547EF1",
        "projectPhase": null,
        "sourceActivity": null,
        "travelTimeToInMinutes": 30,
        "address": "54F3509B95F64669B60C6C8586271D2B",
        "earliestStartDateTime": "2018-09-27T09:51:43Z",
        "lastChanged": 1538041914412,
        "durationInMinutes": null,
        "activityTemplate": null,
        "createPerson": "14523B3D57424338858CB56BBF120696",
        "externalId": null,
        "groups": null,
        "team": null,
        "hazardType": null,
        "createDateTime": "2018-09-27T09:51:54Z",
        "startDateTime": "2018-09-27T09:51:43Z",
        "milestone": null,
        "executionStage": "DISPATCHING",
        "location": null,
        "udfValues": null,
        "lastChangedBy": "14523B3D57424338858CB56BBF120696",
        "remarks": null
      }
  }
}

11.5.2.3 Response

The third-party webhook endpoint will return a 200 OK status code when successful.


11.5.3 Activity Delete

11.5.3.1 Request Headers

Method Endpoint
POST Third-party endpoint
Resonse Header Example Explanation
Authorization Basic cDE3OTI4NDA5OTY6VHNhMTIzNDU= The authentication credentials for HTTP authentication.
Content-Type application/json The MIME type of the content. The request body of the Streaming API will be in application/json format.

11.5.3.2 Request Body

Note: For DELETE requests, the resoureDtoVersion and resourceObject fields are always NULL.

{
  "eventType":"activity.deleted",
  "eventTypeVersion":"1.0",
  "cloudEventsVersion":"0.1",
  "source":"/api/v1/streaming",
  "eventID":"fd1a0ad1-5cc3-490a-a9ab-9d8eec2f628f",
  "eventTime":"2018-11-05T10:32:17.596Z",
  "contentType":"application/json",
  "extensions":{
    "traceId":"44b4a202640d386e"
  },
  "data":{
    "resourceId":"7C0A2AC9DC054BC79AD9B08DB1C15A65",
    "resourceDtoVersion": null,
    "resourceObject": null
  }
}

11.5.3.3 Response

The third-party webhook endpoint will return a 200 OK status code when successful.


11.6 Service Call Events

The following are example notifications related to the creation, update, and deletion of serviceCall records.

Note: Third party systems are notified about events via POST requests.

11.6.1 Service Call Create

11.6.1.1 Request Headers

Method Endpoint
POST Third-party endpoint
Resonse Header Example Explanation
Authorization Basic cDE3OTI4NDA5OTY6VHNhMTIzNDU= The authentication credentials for HTTP authentication.
Content-Type application/json The MIME type of the content. The request body of the Streaming API will be in application/json format.

11.6.1.2 Request Body (with Payload / Object)

Note: This request contains the whole resource object payload. See section 11.3.2.1 for details.

{
  "eventType":"activity.updated",
  "eventTypeVersion":"1.0",
  "cloudEventsVersion":"0.1",
  "source":"/api/v1/streaming",
  "eventID":"fd1a0ad1-5cc3-490a-a9ab-9d8eec2f628f",
  "eventTime":"2018-11-05T10:32:17.596Z",
  "contentType":"application/json",
  "extensions":{
    "traceId":"44b4a202640d386e"
  },
  "data":{
    "resourceId":"7C0A2AC9DC054BC79AD9B08DB1C15A65",
    "resourceDtoVersion":"Activity.23",
    "resourceObject":{
        "travelTimeFromInMinutes": 30,
        "subject": "Mango tests C4C",
        "project": null,
        "owners": null,
        "type": "ASSIGNMENT",
        "businessProcessStepAssignments": [],
        "syncObjectKPIs": null,
        "number": null,
        "inactive": false,
        "contact": "F9A2DB4E9BE047348A2682D63408D176",
        "id": "A2DAAC1567F947B0B40499EA6C1E469A",
        "reminderDateTime": null,
        "changelog": null,
        "equipment": null,
        "personal": false,
        "endDateTime": "2018-09-27T11:51:43Z",
        "branches": null,
        "predecessorActivities": [],
        "dueDateTime": "2018-09-27T21:59:59Z",
        "udfMetaGroups": null,
        "topic": null,
        "responsibles": [],
        "subType": null,
        "syncStatus": "IN_CLOUD",
        "object": {
          "objectId": "386CCBA600D14B9E85D120184C11E9B6",
          "objectType": "SERVICECALL"
        },
        "status": "DRAFT",
        "checkedOut": null,
        "previousActivity": null,
        "projectOrdinal": null,
        "code": "71",
        "businessPartner": "0113FEDD7C9D4C4085567BDBBF547EF1",
        "projectPhase": null,
        "sourceActivity": null,
        "travelTimeToInMinutes": 30,
        "address": "54F3509B95F64669B60C6C8586271D2B",
        "earliestStartDateTime": "2018-09-27T09:51:43Z",
        "lastChanged": 1538041914412,
        "durationInMinutes": null,
        "activityTemplate": null,
        "createPerson": "14523B3D57424338858CB56BBF120696",
        "externalId": null,
        "groups": null,
        "team": null,
        "hazardType": null,
        "createDateTime": "2018-09-27T09:51:54Z",
        "startDateTime": "2018-09-27T09:51:43Z",
        "milestone": null,
        "executionStage": "DISPATCHING",
        "location": null,
        "udfValues": null,
        "lastChangedBy": "14523B3D57424338858CB56BBF120696",
        "remarks": null
      }
  }
}

11.6.1.3 Response

The third-party webhook endpoint will return a 200 OK status code when successful.


11.6.2 Service Call Update

11.6.2.1 Request Headers

Method Endpoint
POST Third-party endpoint
Resonse Header Example Explanation
Authorization Basic cDE3OTI4NDA5OTY6VHNhMTIzNDU= The authentication credentials for HTTP authentication.
Content-Type application/json The MIME type of the content. The request body of the Streaming API will be in application/json format.

11.6.2.2 Request Body (with Payload / Object)

Note: This request contains the whole resource object payload. See section 11.3.2.1 for details.

{
  "eventType":"serviceCall.updated",
  "eventTypeVersion":"1.0",
  "cloudEventsVersion":"0.1",
  "source":"/api/v1/streaming",
  "eventID":"fd1a0ad1-5cc3-490a-a9ab-9d8eec2f628f",
  "eventTime":"2018-11-05T10:32:17.596Z",
  "contentType":"application/json",
  "extensions":{
    "traceId":"44b4a202640d386e"
  },
  "data":{
    "resourceId":"7C0A2AC9DC054BC79AD9B08DB1C15A65",
    "resourceDtoVersion":"ServiceCall.24",
    "resourceObject":{
        "leader": null,
        "subject": "Mango tests C4C",
        "chargeableEfforts": false,
        "project": null,
        "owners": null,
        "objectGroup": null,
        "resolution": null,
        "syncObjectKPIs": null,
        "inactive": false,
        "partOfRecurrenceSeries": null,
        "contact": "F9A2DB4E9BE047348A2682D63408D176",
        "problemTypeName": null,
        "originCode": "-1",
        "id": "386CCBA600D14B9E85D120184C11E9B6",
        "problemTypeCode": null,
        "changelog": null,
        "endDateTime": "2018-09-27T11:51:43Z",
        "priority": "MEDIUM",
        "branches": null,
        "salesOrder": null,
        "dueDateTime": "2018-09-27T21:59:59Z",
        "salesQuotation": null,
        "udfMetaGroups": null,
        "orderReference": null,
        "responsibles": [
          "14523B3D57424338858CB56BBF120696"
        ],
        "syncStatus": "IN_CLOUD",
        "statusCode": "-2",
        "code": "63",
        "businessPartner": "0113FEDD7C9D4C4085567BDBBF547EF1",
        "projectPhase": null,
        "technicians": [],
        "typeName": "Repair",
        "chargeableMileages": false,
        "chargeableMaterials": false,
        "statusName": "Ready to plan",
        "orderDateTime": null,
        "chargeableExpenses": false,
        "lastChanged": 1538042079964,
        "serviceContract": null,
        "createPerson": "14523B3D57424338858CB56BBF120696",
        "externalId": "MangoTestC4C",
        "groups": null,
        "team": null,
        "typeCode": "-1",
        "createDateTime": "2018-09-27T09:51:53Z",
        "equipments": [],
        "startDateTime": "2018-09-27T09:52:00Z",
        "location": null,
        "udfValues": null,
        "lastChangedBy": "14523B3D57424338858CB56BBF120696",
        "incident": null,
        "remarks": null,
        "originName": "Email"
      }
  }
}

11.6.2.3 Response

The third-party webhook endpoint will return a 200 OK status code when successful.


11.6.3 Service Call Delete

11.6.3.1 Request Headers

Method Endpoint
POST Third-party endpoint
Resonse Header Example Explanation
Authorization Basic cDE3OTI4NDA5OTY6VHNhMTIzNDU= The authentication credentials for HTTP authentication.
Content-Type application/json The MIME type of the content. The request body of the Streaming API will be in application/json format.

11.6.3.2 Request Body

Note: For DELETE requests, the resoureDtoVersion and resourceObject fields are always NULL.

{
  "eventType":"serviceCall.deleted",
  "eventTypeVersion":"1.0",
  "cloudEventsVersion":"0.1",
  "source":"/api/v1/streaming",
  "eventID":"fd1a0ad1-5cc3-490a-a9ab-9d8eec2f628f",
  "eventTime":"2018-11-05T10:32:17.596Z",
  "contentType":"application/json",
  "extensions":{
    "traceId":"44b4a202640d386e"
  },
  "data":{
    "resourceId":"7C0A2AC9DC054BC79AD9B08DB1C15A65",
    "resourceDtoVersion": null,
    "resourceObject": null
  }
}

11.6.3.3 Response

The third-party webhook endpoint will return a 200 OK status code when successful.


11.7 Streaming Errors

Streaming errors that occur with the Streaming API are listed in the Streaming Errors screen in Admin.