Web-API

The following section contains information about the web API of Board Connector.

Board Connector offers a web API that allows running extractions and querying meta information and extraction logs from Board Connector through web calls. The web API returns the result as an http-json stream.

Base URL Format #

The basic URL for web calls uses the following format: [protocol]://[host or IP address]:[port]/.

Examples

Protocol	Syntax	Example
HTTP	`http://[host].[domain]:[port]`	`http://sherri.theobald.local:8065`
HTTP	`http://[host]:[port]`	`http://localhost:8065`
HTTPS	`https://[host].[domain]:[port]`	`https://sherri.theobald.local:8165` Requires a dedicated host name and X.509 certificate, see web server settings.

Note: Make sure to use the correct ports, see Server Ports.

Get Version #

[protocol]://[host]:[port]/version

Returns the software version of the Board Connector server installation in JSON format.

Example

http://sherri.theobald.local:8065/version

Click here to show the response body

{
    "version": "6.2.13.4"
}

Get Destination Details #

[protocol]://[host]:[port]/destinations

Returns a list of all defined destinations. The result contains the following elements:

Item	Description
name	name of the target connection
type	connection type
host	host name, if applicable
port	port name, if applicable
database	database name, if applicable
user	user name in the connection, if applicable
schema	schema name, if applicable
directory	directory name, if applicable

Tip: For a list of extractions with a specific destination, see Get Extraction Details.

Example

http://sherri.theobald.local:8065/destinations

Click here to show the response body

Name,Type,Host,Port,Database,User,Schema,Directory
csv,FileCSV,,,,,,"C:\Users\alice\Documents\csv\"
http-csv,CSV,,,,,,
http-json,HTTPJSON,,,,,,
json,FileJSON,,,,,,"C:\Users\alice\Documents\json"
sql-server,SQLServer,dbtest-ws2019.theobald.local,1433,alice,THEOBALD\alice,,
tableau2022,Tableau,,,,,,"C:\Users\alice\Documents\csv"

Get Extraction Details #

[protocol]://[host]:[port]/config/extractions

Returns a list of all defined extractions in JSON format. The result contains the following elements:

Item	Description
name	name of the extraction
type	extraction type
sapObject	name of the extracted SAP object
source	name of the source connection
destination	name of the target connection
latestRun	contains rowCount, duration, state and startedAt of the latest extraction run
rowCount	number of the last extracted data records
duration	duration of the last execution
state	status of the extraction (Running, FinishedNoErrors, FinishedErrors)
startedAt	timestamp of the last execution
created	contains machine, timestamp and user of when the extraction was created
machine	machine on which the extraction was created
timestamp	timestamp of the creation
user	user that created the extraction
lastChange	contains machine, timestamp and user of when the extraction was last changed
machine	machine on which the extraction was last changed
timestamp	timestamp of the last change
user	user that last changed the extraction

Parameters & Options

[protocol]://[host]:[port]/config/extractions

Parameter	Description
`?destinationType=[destination]`	Returns a list of extractions that write into a specific destination.
`/[extraction_name]/parameters`	Returns a list of runtime parameters used in the specified extraction. Every extraction has a set of Extraction, Source and Custom extraction parameters. The parameters are available in the “Run Extraction” window. .
`/[extraction_name]/result-columns`	Returns the result columns of an extraction.

The result of [protocol]://[host]:[port]/config/extractions/[extraction_name]/result-columns contains the following elements:

Item	Type	Description
name	String	column name
description	String	column description
type	String	column datatype
length	Integer	column length
isPrimaryKey	boolean	column is primary key of extraction
isEncrypted	boolean	encryption for column is active
decimalsCount	Integer	number of decimal places
referenceField	String	reference field for currency/quantity
referenceTable	String	reference table for currency/quantity

Note: Data fields that contain dates have the data type ConvertedDate if the option Date Conversion in the Destination Settings is active. If inactive, the data type is StringLengthMax with a length of 8 (Date).

Examples

http://sherri.theobald.local:8065/config/extractions/

Click here to show the response body

{
    "extractions": 
    [
        {
            "name": [
                "0MAT"
            ],
            "type": "DeltaQ",
            "technicalName": "0MATERIAL_ATTR",
            "source": "saperp",
            "destination": "GoogleCloudStorage",
            "latestRun": {
                "rowCount": 20275,
                "duration": "PT00H00M13.383S",
                "state": "FinishedNoErrors",
                "startedAt": "2023-08-17_11:24:07.770"
            },
            "created": {
                "machine": "TODD",
                "timestamp": "20221005T080618.544Z",
                "user": "THEOBALD\\steffan"
            },
            "lastChange": {
                "machine": "SHERRI",
                "timestamp": "20240129T131530.701Z",
                "user": "THEOBALD\\alice"
            }
        },
        {
            "name": [
                "0MATERIAL"
            ],
            "type": "DeltaQ",
            "technicalName": "0COSTCENTER_0101_HIER",
            "source": "saperp",
            "destination": "csv",
            "latestRun": {
                "rowCount": 200,
                "duration": "PT00H00M00.114S",
                "state": "FinishedNoErrors",
                "startedAt": "2023-08-17_11:31:44.029"
            },
            "created": {
                "machine": "SHERRI",
                "timestamp": "20230815T114651.045Z",
                "user": "THEOBALD\\alice"
            },
            "lastChange": {
                "machine": "SHERRI",
                "timestamp": "20230817T113328.786Z",
                "user": "THEOBALD\\alice"
            }
        }

http://sherri.theobald.local:8065/config/extractions/?destinationType=sqlserver

Click here to show the response body

{
    "extractions": 
    [
        {
            "name": [
                "bw2--UCONRFC_ATTR_F"
            ],
            "type": "ODP",
            "technicalName": "UCONRFC_ATTR$F",
            "source": "bw2",
            "destination": "sql-server",
            "created": {
                "machine": "SHERRI",
                "timestamp": "20230622T062454.495Z",
                "user": "alice"
            },
            "lastChange": {
                "machine": "SHERRI",
                "timestamp": "20230703T070609.890Z",
                "user": "THEOBALD\\alice"
            }
        },
        {
            "name": [
                "ec5--KNA1_DELTA"
            ],
            "type": "TableCDC",
            "technicalName": "KNA1_DELTA",
            "source": "ec5",
            "destination": "sql-server",
            "created": {
                "machine": "SHERRI",
                "timestamp": "20230622T051526.003Z",
                "user": "alice"
            },
            "lastChange": {
                "machine": "SHERRI",
                "timestamp": "20230703T070609.955Z",
                "user": "THEOBALD\\alice"
            }
        },
        {
            "name": [
                "HIERARCHY"
            ],
            "type": "Hierarchy",
            "technicalName": "TEST_DEP_01",
            "source": "bw2",
            "destination": "sql-server",
            "latestRun": {
                "rowCount": 13,
                "duration": "PT00H00M02.710S",
                "state": "FinishedNoErrors",
                "startedAt": "2023-07-19_06:04:04.139"
            },
            "created": {
                "machine": "SHERRI",
                "timestamp": "20230719T051513.542Z",
                "user": "THEOBALD\\alice"
            },
            "lastChange": {
                "machine": "SHERRI",
                "timestamp": "20230815T074627.575Z",
                "user": "THEOBALD\\alice"
            }
        }
    ]
}

http://sherri.theobald.local:8065/config/extractions/KNA1/parameters

Click here to show the response body

{
    "extraction": 
    [
        {
            "name": "ignoreCache",
            "description": "Ignore the result cache",
            "type": "Flag",
            "default": "False"
        },
        {
            "name": "preview",
            "description": "Enable/disable preview mode",
            "type": "Flag",
            "default": "False"
        },
        {
            "name": "source",
            "description": "Sets the name of the source",
            "type": "Text",
            "default": "ec5"
        },
        {
            "name": "destination",
            "description": "Sets the name of the destination",
            "type": "Text",
            "default": "csv"
        },
        {
            "name": "rows",
            "description": "Maximum number of rows",
            "type": "Number",
            "default": "0"
        },
        {
            "name": "whereClause",
            "description": "Where Clause",
            "type": "Text",
            "default": null
        },
        {
            "name": "packageSize",
            "description": "Package Size",
            "type": "Number",
            "default": "50000"
        }
    ],
    "source": 
    [
        {
            "name": "lang",
            "description": "Logon Language",
            "type": "Text",
            "default": "EN"
        }
    ]
}

http://sherri.theobald.local:8065/config/extractions/KNA1/result-columns

Click here to show the response body

{
    "columns": 
    [
        {
            "name": "KUNNR",
            "description": "Customer Number",
            "type": "StringLengthMax",
            "length": 10,
            "isPrimaryKey": true,
            "isEncrypted": false,
            "referenceField": "",
            "referenceTable": ""
        },
        {
            "name": "LAND1",
            "description": "Country Key",
            "type": "StringLengthMax",
            "length": 3,
            "isPrimaryKey": false,
            "isEncrypted": false,
            "referenceField": "",
            "referenceTable": ""
        },
        {
            "name": "NAME1",
            "description": "Name 1",
            "type": "StringLengthMax",
            "length": 35,
            "isPrimaryKey": false,
            "isEncrypted": false,
            "referenceField": "",
            "referenceTable": ""
        },
        {
            "name": "ORT01",
            "description": "City",
            "type": "StringLengthMax",
            "length": 35,
            "isPrimaryKey": false,
            "isEncrypted": false,
            "referenceField": "",
            "referenceTable": ""
        },
        {
            "name": "Mean_UMSAT",
            "description": "Annual sales",
            "type": "Double",
            "isPrimaryKey": false,
            "isEncrypted": false,
            "referenceField": "UWAER",
            "referenceTable": "KNA1"
        }
    ]
}

Run Extractions #

[protocol]://[host]:[port]/run/[extraction_name]

Runs the specified extraction and waits for it to finish.

[protocol]://[host]:[port]/start/[extraction_name]

Runs the specified extraction asynchronously and returns the run status immediately.

Warning! Deprecated Endpoints:
[protocol]://[host]:[port]/?name=[extraction_name] (synchronous)
[protocol]://[host]:[port]/?name=[extraction_name]&wait=false (asynchronous)

Tip: You can use the UI in the “Run Extraction” menu to generate an URL for extraction runs, see Run Extraction.

Response

The response of the web service calls contains the following information:

	Response	Description
(1)	HTTP status code	The HTTP status code 200 indicates a successful extraction call. It does not indicate a successful execution of the extraction. The HTTP status code 404 indicates that the called extraction does not exist. Detailed information can be found in the log of the web service.
(2)	HTTP header	Shows the timestamp of the extraction in the HTTP header e.g., X-XU-Timestamp: 2021-04-09_19:03:09.971
(3)	HTTP response body	The Response in the HTTP body depends on the destination type of the extraction. Depending on the destination type, the extracted data is returned in either CSV or JSON format.

Webservice Call pull

Parameters

[protocol]://[host]:[port]/start/[extraction_name]

Parameter	Description
`/&[parameter1_name]=[value]`	Runs the specified extraction and passes values to the specified extraction parameters.
`/&quiet-push=true`	Runs the specified extraction and suppresses the output of extraction logs for push destinations. This parameter has no effect on pull destinations and asynchronous extractions.

Example

http://sherri.theobald.local:8065/start/KNA1/?name1=heobald%20Software&city=Stuttgart

Click here to show the response body

KUNNR,LAND1,NAME1,ORT01
0000000779,DE,Theobald Software,Stuttgart

Abort Extraction #

[protocol]://[host]:[port]/abort?name=[extraction_name]

Aborts the specified extraction. If the abortion is successful, a confirmation message is returned in the HTTP body.

* This endpoint is marked as deprecated and will be replaced by /stop/[extraction_name] in the future. *

Example

http://sherri.theobald.local:8065/abort?name=KNA1

Click here to show the response body

All runs of extraction 'KNA1' aborted.

@@ -0,0 +1,292 @@

Status einer Extraktion abrufen #

[protocol]://[host]:[port]/status/?name=[extraction_name]&timestamp=[yyyy-MM-dd_HH:mm:ss.SSS]

Gibt den Status einer (laufenden) Extraktion zum angegebenen Zeitstempel zurück. Der Zeitstempel entspricht dem von zurückgegebenen startedAt-Element [protocol]://[host]:[port]/config/extractions/ oder [protocol]://[host]:[port]/logs/extractions/[extraction-name].

Status	Beschreibung
Running	Die Extraktion läuft.
FinishedNoErrors	Die Extraktion wurde ohne Fehler abgeschlossen.
FinishedErrors	Die Extraktion wurde abgeschlossen, weist jedoch mindestens einen Fehler auf.

Beispiel

http://sherri.theobald.local:8065/status/?name=KNA1&timestamp=2024-02-05_10:23:08.025

Click here to show the response body

FinishedNoErrors

Extraktionslogs abrufen #

[protocol]://[host]:[port]/logs/extractions

Gibt eine Liste von Extraktionsläufen zurück. Das Ergebnis enthält die folgenden Elemente:

Element	Beschreibung
extractionName	Name der Extraktion
runs	enthält rowCount, duration, state, webServerLog und startedAt der Extraktionsläufe
row count	Anzahl der extrahierten Datensätze
duration	Dauer der Ausführung
state	Status der Extraktion (Running, FinishedNoErrors, FinishedErrors)
webServerLog	Zeitstempel des entsprechenden Serverlogs
startedAt	Zeitstempel der Ausführung

Parameter & Optionen

[protocol]://[host]:[port]/logs/extractions

Parameter	Beschreibung
`?min=[yyyy-MM-dd_HH:mm:ss.SSS]`	Gibt die Extraktionsläufe nach dem angegebenen Datum und der angegebenen Uhrzeit zurück.
`?max=[yyyy-MM-dd_HH:mm:ss.SSS]`	Gibt die Extraktionsläufe vor dem angegebenen Datum und der angegebenen Uhrzeit zurück.
`/[extraction-name]`	Gibt alle Extraktionsläufe der angegebenen Extraktion zurück.
`/[extraction-name]/[yyyy-MM-dd_HH:mm:ss.SSS]`	Gibt den Extraktionslauf der angegebenen Extraktion mit dem angegebenen Zeitstempel zurück.
`/[extraction-name]/[yyyy-MM-dd_HH:mm:ss.SSS]/log`	Gibt das Extraktionslog der angegebenen Extraktion mit dem angegebenen Zeitstempel zurück.

Beispiel

http://sherri.theobald.local:8065/logs/extractions?min=2023-08-17_11:20:44.029

Click here to show the response body

{
    "extractions": 
    [
        {
            "extractionName": [
                "0MATERIAL"
            ],
            "runs": [
                {
                    "rowCount": 200,
                    "duration": "PT00H00M00.2651",
                    "state": "FinishedNoErrors",
                    "startedAt": "2023-08-17_11:31:44.029"
                }
            ]
        }
        {
            "extractionName": [
                "KNA1"
            ],
            "runs": [
                {
                    "rowCount": 0,
                    "duration": "PT00H00M01.3741",
                    "state": "FinishedErrors",
                    "webServerLog": "2024-02-05_08:13:48.132",
                    "startedAt": "2024-02-05_08:14:13.771"
                },
                {
                    "rowCount": 9995,
                    "duration": "PT00H00M00.477S",
                    "state": "FinishedNoErrors",
                    "webServerLog": "2024-02-05_10:20:51.851",
                    "startedAt": "2024-02-05_10:20:52.344"
                }
            ]
        }
    ]
}

http://sherri.theobald.local:8065/logs/extractions/KNA1

Click here to show the response body

{
    "runs": [
        {
            "rowCount": 0,
            "duration": "PT00H00M01.3741",
            "state": "FinishedErrors",
            "webServerLog": "2024-02-05_08:13:48.132",
            "startedAt": "2024-02-05_08:14:13.771"
        },
        {
            "rowCount": 9995,
            "duration": "PT00H00M00.477S",
            "state": "FinishedNoErrors",
            "webServerLog": "2024-02-05_10:20:51.851",
            "startedAt": "2024-02-05_10:20:52.344"
        }
    ]
}

http://sherri.theobald.local:8065/logs/extractions/KNA1/2024-02-05_10:20:52.344

Click here to show the response body

{
    "rowCount": 9995,
    "duration": "PT00H00M00.477S",
    "state": "FinishedNoErrors",
    "webServerLog": "2024-02-05_10:20:51.851",
    "startedAt": "2024-02-05_10:20:52.344"
}

http://sherri.theobald.local:8065/logs/extractions/KNA1/2024-02-05_10:20:52.344/log

Click here to show the response body

{
    "rowCount": 9995,
    "duration": "PT00H00M00.477S",
    "state": "FinishedNoErrors",
    "webServerLog": "2024-02-05_10:20:51.851",
    "startedAt": "2024-02-05_10:20:52.344",
    "logEntries": [
        {
            "timestamp": "2024-02-05_10:20:52.377",
            "logLevel": "Info",
            "source": "Table",
            "message": "server version: 999.999.999.691"
        },
        {
            "timestamp": "2024-02-05_10:20:52.470",
            "logLevel": "Debug",
            "source": "Table",
            "message": "Attempting to load Theobald.Extractors.Table.TableExtractionDefinition information for extraction KNA1"
        },
		
		...
		
        {
            "timestamp": "2024-02-05_10:20:53.774",
            "logLevel": "Info",
            "source": "Table",
            "message": "Extraction finished with status FinishedNoErrors."
        },
        {
            "timestamp": "2024-02-05_10:20:53.774",
            "logLevel": "Debug",
            "source": "Table",
            "message": "Writing run information."
        },
        {
            "timestamp": "2024-02-05_10:20:53.779",
            "logLevel": "Info",
            "source": "Table",
            "message": "Extraction run information was updated."
        }
    ]
}

Hinweis: Informationen zur Interpretation von Protokollen, siehe Logging.

Serverlogs abrufen #

[protocol]://[host]:[port]/logs/web

Gibt eine Liste von Zeitstempeln zurück, die den Serverlogs entsprechen.

Parameter & Optionen

[protocol]://[host]:[port]/logs/web

Parameter	Beschreibung
`?min=[yyyy-MM-dd_HH:mm:ss.SSS]`	Gibt die Zeitstempel der Serverlogs nach dem angegebenen Datum und der angegebenen Uhrzeit zurück.
`?max=[yyyy-MM-dd_HH:mm:ss.SSS]`	Gibt die Zeitstempel der Serverlogs vor dem angegebenen Datum und der angegebenen Uhrzeit zurück.
`/[yyyy-MM-dd_HH:mm:ss.SSS]`	Gibt die Serverlogeinträge mit dem angegebenen Zeitstempel zurück.

Beispiel

http://sherri.theobald.local:8065/logs/web?min=2024-02-05_12:39:29.022

Click here to show the response body

{
    "logs": 
    [
        "2024-02-05_12:44:44.741",
        "2024-02-05_13:09:11.899",
        "2024-02-07_08:52:17.487",
        "2024-02-07_08:58:14.920",
        "2024-02-07_10:44:21.652",
        "2024-02-07_10:50:58.202",
        "2024-02-07_10:54:25.552"
    ]
}

http://sherri.theobald.local:8065/logs/web/2024-02-05_12:44:44.741

Click here to show the response body

{
    "logEntries": 
    [
        {
            "timestamp": "2024-02-05_12:44:44.815",
            "logLevel": "Info",
            "source": "WebServerHandler",
            "message": "Client [fe80::d3ac:77ba:ce0f:83b1%8]:55904"
        },
        {
            "timestamp": "2024-02-05_12:44:45.012",
            "logLevel": "Debug",
            "source": "HttpServer",
            "message": "Reading..."
        },
        {
            "timestamp": "2024-02-05_12:44:45.060",
            "logLevel": "Info",
            "source": "HttpServer",
            "message": "Processing /."
        },
        {
            "timestamp": "2024-02-05_12:44:45.251",
            "logLevel": "Info",
            "source": "WebServer",
            "message": "Attempting to load server permissions."
        },
		
		...
        
        {
            "timestamp": "2024-02-05_12:44:45.808",
            "logLevel": "Debug",
            "source": "HttpServer",
            "message": "Reading..."
        }
    ]
}

Hinweis: Informationen zur Interpretation von Logs, siehe Logging.