Business Bot Plattform REST API

Die Business Bot Plattform API ist eine RESTful API und bietet programmgesteuerten Zugriff auf Entitäten der Business Bot Plattform sowie ermöglicht es Ihnen, die Business Bot Plattform einfach mit Drittanbieter-Tools zu integrieren. Die API unterstützt JSON für Anfragen und Antworten. Der Antwort-Inhaltstyp wird über den HTTP Accept Header angefordert (application/json). Alle Ressourcen sind über https erreichbar und befinden sich unter https://my.mmgw.de/bbp/rest/api/1.0/ für Public-Cloud beziehungsweise https://<TenantId>.mmgw.de/bbp/rest/api/1.0/ für Private-Cloud.

Authentifizierung

Die REST-API akzeptiert die Authentifizierung mittels Tenant Id, API Id und API Key. Standardmäßig muss sich der Client für den Zugriff auf alle Ressourcen authentifizieren. Die Tenant Id entspricht der Organisations-Id, welche die Sub-Domäne der mmgw.de URL entspricht (z.B. wenn Ihre Business Bot Plattform URL mycompany.mmgw.de ist, wäre die Organisation Id mycompany). Wenn Sie die Tenant Id nicht angeben, wird die Authentifizierung fehlschlagen.

Ausnahmebehandlung (Errors)

Die Business Bot Plattform verwendet in der Antwort HTTP-Statuscode, um den Erfolg oder Misserfolg einer API-Anfrage mitzuteilen. Codes im 1xx Bereich sind für informationelle Zwecke vorgesehen. Codes im 2xx Bereich zeigen Erfolg an, Codes im 3xx Bereich sind für Weiterleitungen reserviert, Codes im 4xx Bereich zeigen Clientfehler an (z.B. ein fehlender Parameter) und Codes im 5xx Bereich zeigen Fehler auf der Serverseite an. Im Falle eines Fehlers enthält die Antwort folgende Informationen (z.B. {"code":402,"description":"Unknown source user","status":"false"}):

Attribut Beschreibung
code Der HTTP-Statuscode
description Eine lesbare Beschreibung des Fehlers
status Genereller Erfolgsstatus der Anfrage

Folgende Übersicht zeigt die wichtigsten Fehlercodes:

Code Beschreibung
1xx - Informational
2xx - Success
200 OK
3xx - Redirection
4xx - Client Error
401 Unauthorized
402 Unknown source user
403 Unknown target user
405 Method not allowed
410 Unknown system type and system release
450 API user or API key invalid
451 API user inactive
452 API user has no license
453 API user license is expired
454 API user has exceeded the total number of messages per month
455 Queue name does not exists
456 System identifier does not exists
457 API user has limited license but requires enterprise license
5xx - Server Error
500 Internal processing error
503 The server is currently unavailable because of maintenance

API Versionierung

Wir werden eine neue Version der API freigeben, wenn wir rückwärts-inkompatible Änderungen durchführen. Wir betrachten die folgenden Änderungen als rückwärtskompatibel:

  • Hinzufügen neuer API-Ressourcen.
  • Hinzufügen neuer optionaler Anforderungsparameter zu bestehenden API-Methoden.
  • Hinzufügen neuer Eigenschaften zu bestehenden API-Antworten.
  • Ändern der Reihenfolge der Eigenschaften in bestehenden API-Antworten.

API-Ressourcen

Syntax der URL: https://<Tenant Id>.mmgw.de/bbp/rest/api/<API Version>/<Tenant Id>:<API Id>:<API Key>/<System-Integration Kennung>/<Resource>

Beispiel URL: https://jmb.mmgw.de/bbp/rest/api/1.0/jmb:u-19df358:357f215/ENOVIA-001/getUpdates

Resource: getUpdates

Diese Ressourcen-Anfrage wird von einem Client an die Business Bot Plattform gesendet, um die neusten System-Events (von der Queue) abzurufen. Die System-Events befinden sich in einer Warteschlange, die einer dedizierte System-Integration und Bot zugeordnet sind.

HTTP Methode Content Type Resource Beschreibung
POST application/json /getUpdates Abrufen von Nachrichtenevents

Request-Inhalt:

1
{"limit":100,"offset":1,"timeout":20}

Response-Inhalt (Beispieldaten ohne Ergebnisse):

1
{"status":true, "code":200, "result":[]}

Response-Inhalt (Beispieldaten mit Ergebnissen):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
	"status": true,
	"code": 200,
	"result": [{
		"updateId": 326,
		"message": {
			"reply": false,
			"messageId": 0,
			"from": {
				"id": 0,
				"firstName": "firstName",
				"lastName": "lastName",
				"userName": "john"
			},
			"to": {
				"id": 0,
				"firstName": "firstName",
				"lastName": "lastName",
				"userName": "NO_USER"
			},
			"date": 0,
			"meta": {
				"id": 0,
				"systemType": "WebUI",
				"systemRelease": "1.0",
				"eventType": "SearchRequest",
				"eventName": "Object",
				"objectId": null,
				"refObjectId": null
			},
			"text": "",
			"audio": null,
			"document": null,
			"photo": null,
			"video": null,
			"location": null,
			"replyToMessage": null,
			"voice": null,
			"data": {
				"filter": {
					"objectType": "Issue",
					"objectName": "*",
					"objectRevision": "*",
					"objectId": null,
					"limit": 5,
					"searchString": null,
					"orderBy": "DESC",
					"tsBegin": null,
					"tsEnd": null,
					"owner": null,
					"view": "issuelist"
				},
				"result": ""
			}
		}
	}]
}

Resource: sendUpdate

Diese Ressourcen-Anfrage wird von einem Client an die Business Bot Plattform gesendet, um eine Nachricht an einen mobilen Benutzer zu senden.

HTTP Methode Content Type Resource Beschreibung
POST application/json /sendUpdate Senden einer Nachricht

Request-Inhalt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
	"message": {
		"to": {
			"lastName": "lastName",
			"userName": "erika",
			"firstName": "firstName"
		},
		"data": {
			"result": "[{\"type\":\"Issue\",\"name\":\"ISS-0000001\",\"revision\":\"-\",\"owner\":\"john\",\"current\":\"Create\",\"description\":\"Missing chapter\",\"objectId\":\"60592.18415.31712.43999\"},{\"type\":\"Issue\",\"name\":\"ISS-0000002\",\"revision\":\"-\",\"owner\":\"john\",\"current\":\"Create\",\"description\":\"Missing chapter\",\"objectId\":\"60592.18415.11568.63047\"}]",
			"filter": {
				"limit": 5,
				"orderBy": "DESC",
				"objectType": "Issue"
			}
		},
		"from": {
			"lastName": "lastName",
			"userName": "john",
			"firstName": "firstName"
		},
		"meta": {
			"systemType": "ENOVIA",
			"eventName": "Object",
			"eventType": "SearchResult",
			"systemRelease": "R2015x"
		}
	},
	"updateId": "1234"
}

Response-Inhalt (Beispieldaten):

1
{"code":200,"description":"Ok","status":"true"}

API Fehlerbehandlung

HTTP Status 500: No Content To Map To Object Due To End Of Input

Wenn Sie folgenden Fehler erhalten, wurde ein leerer POST-Request an die Business Bot Plattform gesendet.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
HTTP Status 500 - org.glassfish.jersey.server.ContainerException: java.io.EOFException: No content to map to Object due to end of input

type Exception report

message org.glassfish.jersey.server.ContainerException: java.io.EOFException: No content to map to Object due to end of input

description The server encountered an internal error that prevented it from fulfilling this request.

exception

javax.servlet.ServletException: org.glassfish.jersey.server.ContainerException: java.io.EOFException: No content to map to Object due to end of input
	org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:487)
	org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223)
	org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)

root cause

org.glassfish.jersey.server.ContainerException: java.io.EOFException: No content to map to Object due to end of input
	org.glassfish.jersey.servlet.internal.ResponseWriter.rethrow(ResponseWriter.java:278)
	org.glassfish.jersey.servlet.internal.ResponseWriter.failure(ResponseWriter.java:260)
	org.glassfish.jersey.server.ServerRuntime$Responder.process(ServerRuntime.java:509)
	org.glassfish.jersey.server.ServerRuntime$2.run(ServerRuntime.java:334)
	org.glassfish.jersey.internal.Errors$1.call(Errors.java:271)
	org.glassfish.jersey.internal.Errors$1.call(Errors.java:267)
	org.glassfish.jersey.internal.Errors.process(Errors.java:315)
	org.glassfish.jersey.internal.Errors.process(Errors.java:297)
	org.glassfish.jersey.internal.Errors.process(Errors.java:267)
	org.glassfish.jersey.process.internal.RequestScope.runInScope(RequestScope.java:317)
	org.glassfish.jersey.server.ServerRuntime.process(ServerRuntime.java:305)
	org.glassfish.jersey.server.ApplicationHandler.handle(ApplicationHandler.java:1154)
	org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:471)
	org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223)
	org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)

root cause

java.io.EOFException: No content to map to Object due to end of input
	org.codehaus.jackson.map.ObjectMapper._initForReading(ObjectMapper.java:2766)
	org.codehaus.jackson.map.ObjectMapper._readValue(ObjectMapper.java:2682)
	org.codehaus.jackson.map.ObjectMapper.readValue(ObjectMapper.java:1308)
	org.codehaus.jackson.jaxrs.JacksonJsonProvider.readFrom(JacksonJsonProvider.java:419)
	org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$TerminalReaderInterceptor.invokeReadFrom(ReaderInterceptorExecutor.java:256)
	org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$TerminalReaderInterceptor.aroundReadFrom(ReaderInterceptorExecutor.java:235)
	org.glassfish.jersey.message.internal.ReaderInterceptorExecutor.proceed(ReaderInterceptorExecutor.java:155)
	org.glassfish.jersey.server.internal.MappableExceptionWrapperInterceptor.aroundReadFrom(MappableExceptionWrapperInterceptor.java:74)
	org.glassfish.jersey.message.internal.ReaderInterceptorExecutor.proceed(ReaderInterceptorExecutor.java:155)
	org.glassfish.jersey.message.internal.MessageBodyFactory.readFrom(MessageBodyFactory.java:1085)
	org.glassfish.jersey.message.internal.InboundMessageContext.readEntity(InboundMessageContext.java:874)
	org.glassfish.jersey.server.ContainerRequest.readEntity(ContainerRequest.java:271)
	org.glassfish.jersey.server.internal.inject.EntityParamValueFactoryProvider$EntityValueFactory.provide(EntityParamValueFactoryProvider.java:96)
	org.glassfish.jersey.server.spi.internal.ParamValueFactoryWithSource.provide(ParamValueFactoryWithSource.java:71)
	org.glassfish.jersey.server.spi.internal.ParameterValueHelper.getParameterValues(ParameterValueHelper.java:94)
	org.glassfish.jersey.server.model.internal.JavaResourceMethodDispatcherProvider$AbstractMethodParamInvoker.getParamValues(JavaResourceMethodDispatcherProvider.java:127)
	org.glassfish.jersey.server.model.internal.JavaResourceMethodDispatcherProvider$ResponseOutInvoker.doDispatch(JavaResourceMethodDispatcherProvider.java:160)
	org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.dispatch(AbstractJavaResourceMethodDispatcher.java:99)
	org.glassfish.jersey.server.model.ResourceMethodInvoker.invoke(ResourceMethodInvoker.java:389)
	org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:347)
	org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:102)
	org.glassfish.jersey.server.ServerRuntime$2.run(ServerRuntime.java:326)
	org.glassfish.jersey.internal.Errors$1.call(Errors.java:271)
	org.glassfish.jersey.internal.Errors$1.call(Errors.java:267)
	org.glassfish.jersey.internal.Errors.process(Errors.java:315)
	org.glassfish.jersey.internal.Errors.process(Errors.java:297)
	org.glassfish.jersey.internal.Errors.process(Errors.java:267)
	org.glassfish.jersey.process.internal.RequestScope.runInScope(RequestScope.java:317)
	org.glassfish.jersey.server.ServerRuntime.process(ServerRuntime.java:305)
	org.glassfish.jersey.server.ApplicationHandler.handle(ApplicationHandler.java:1154)
	org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:471)
	org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223)

HTTP Status 415: Unsupported Media Type

Wenn Sie folgenden Fehler erhalten, entspricht der vom Business Bot Platform erwartete Content-Type nicht application/json.

1
2
3
4
5
6
7
8
HTTP Status 415 - Unsupported Media Type

type Status report

message Unsupported Media Type

description The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.
Apache Tomcat/8.0.38

HTTP Status 500: org.json.JSONException: Expected a ‘,’ or ‘}’ at 724 [character 1 line 37]

Wenn Sie folgenden Fehler erhalten, ist der Request Content fehlerhaft, in diesem Beispiel ist der JSON-Inhalt nicht valide.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
HTTP Status 500 - org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37]

type Exception report

message org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37]

description The server encountered an internal error that prevented it from fulfilling this request.

exception

javax.servlet.ServletException: org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37]
	org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:487)
	org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223)
	org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)

root cause

org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37]
	org.json.JSONTokener.syntaxError(JSONTokener.java:433)
	org.json.JSONObject.<init>(JSONObject.java:232)
	org.json.JSONObject.<init>(JSONObject.java:324)
	de.citunius.bbp.adk.services.WebService.isValidRawMessage(WebService.java:348)
	de.citunius.bbp.adk.services.WebService.sendMessageRequest(WebService.java:391)
	sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
	sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
	java.lang.reflect.Method.invoke(Unknown Source)
	org.glassfish.jersey.server.model.internal.ResourceMethodInvocationHandlerFactory$1.invoke(ResourceMethodInvocationHandlerFactory.java:81)
	org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher$1.run(AbstractJavaResourceMethodDispatcher.java:144)
	org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.invoke(AbstractJavaResourceMethodDispatcher.java:161)
	org.glassfish.jersey.server.model.internal.JavaResourceMethodDispatcherProvider$ResponseOutInvoker.doDispatch(JavaResourceMethodDispatcherProvider.java:160)
	org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.dispatch(AbstractJavaResourceMethodDispatcher.java:99)
	org.glassfish.jersey.server.model.ResourceMethodInvoker.invoke(ResourceMethodInvoker.java:389)
	org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:347)
	org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:102)
	org.glassfish.jersey.server.ServerRuntime$2.run(ServerRuntime.java:326)
	org.glassfish.jersey.internal.Errors$1.call(Errors.java:271)
	org.glassfish.jersey.internal.Errors$1.call(Errors.java:267)
	org.glassfish.jersey.internal.Errors.process(Errors.java:315)
	org.glassfish.jersey.internal.Errors.process(Errors.java:297)
	org.glassfish.jersey.internal.Errors.process(Errors.java:267)
	org.glassfish.jersey.process.internal.RequestScope.runInScope(RequestScope.java:317)
	org.glassfish.jersey.server.ServerRuntime.process(ServerRuntime.java:305)
	org.glassfish.jersey.server.ApplicationHandler.handle(ApplicationHandler.java:1154)
	org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:471)
	org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336)
	org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223)
	org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)

note The full stack trace of the root cause is available in the Apache Tomcat/8.0.38 logs.
Apache Tomcat/8.0.38