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
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
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
http://sherri.theobald.local:8065/config/extractions/?destinationType=sqlserver
Click here to show the response body
http://sherri.theobald.local:8065/config/extractions/KNA1/parameters
Click here to show the response body
http://sherri.theobald.local:8065/config/extractions/KNA1/result-columns
Click here to show the response body
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. |
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
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.
Example
http://sherri.theobald.local:8065/abort?name=KNA1
Click here to show the response body
Get Status of an Extraction #
[protocol]://[host]:[port]/status/?name=[extraction_name]×tamp=[yyyy-MM-dd_HH:mm:ss.SSS]
Returns the status of a (running) extraction at the specified timestamp.
The timestamp corresponds to the startedAt element returned by [protocol]://[host]:[port]/config/extractions/
or [protocol]://[host]:[port]/logs/extractions/[extraction-name]
.
State | Description |
---|---|
Running | The extraction is running. |
FinishedNoErrors | The extraction is finished without errors. |
FinishedErrors | The extraction is finished, but with minimum one error. |
Example
http://sherri.theobald.local:8065/status/?name=KNA1×tamp=2024-02-05_10:23:08.025
Click here to show the response body
Get Extraction Logs #
[protocol]://[host]:[port]/logs/extractions
Returns a list of extraction runs. The result contains the following elements:
Item | Description |
---|---|
extractionName | name of the extraction |
runs | contains rowCount, duration, state, webServerLog and startedAt of extraction runs |
row count | number of extracted data records |
duration | duration of the execution |
state | status of the extraction (Running, FinishedNoErrors, FinishedErrors) |
webServerLog | timestamp of the corresponding server log |
startedAt | timestamp of the execution |
Parameters & Options
[protocol]://[host]:[port]/logs/extractions
Parameter | Description |
---|---|
?min=[yyyy-MM-dd_HH:mm:ss.SSS] |
Returns the extraction runs after the specified date and time. |
?max=[yyyy-MM-dd_HH:mm:ss.SSS] |
Returns the extraction runs before the specified date and time. |
/[extraction-name] |
Returns all extraction runs of the specified extraction. |
/[extraction-name]/[yyyy-MM-dd_HH:mm:ss.SSS] |
Returns the extraction run of the specified extraction with the specified timestamp. |
/[extraction-name]/[yyyy-MM-dd_HH:mm:ss.SSS]/log |
Returns the extraction log of the specified extraction with the specified timestamp. |
Example
http://sherri.theobald.local:8065/logs/extractions?min=2023-08-17_11:20:44.029
Click here to show the response body
http://sherri.theobald.local:8065/logs/extractions/KNA1
Click here to show the response body
http://sherri.theobald.local:8065/logs/extractions/KNA1/2024-02-05_10:20:52.344
Click here to show the response body
http://sherri.theobald.local:8065/logs/extractions/KNA1/2024-02-20_07:12:54.774/log
Click here to show the response body
Note: For information on how to interpret logs, see Logging.
Get Server Logs #
[protocol]://[host]:[port]/logs/web
Returns a list of timestamps that correspond to server logs.
Parameters & Options
[protocol]://[host]:[port]/logs/web
Parameter | Description |
---|---|
?min=[yyyy-MM-dd_HH:mm:ss.SSS] |
Returns the timestamps of server logs after the specified date and time. |
?max=[yyyy-MM-dd_HH:mm:ss.SSS] |
Returns the timestamps of server logs before the specified date and time. |
/[yyyy-MM-dd_HH:mm:ss.SSS] |
Returns the server log entries with the specified timestamp. |
Example
http://sherri.theobald.local:8065/logs/web?min=2024-02-05_12:39:29.022
Click here to show the response body
http://sherri.theobald.local:8065/logs/web/2024-02-05_12:44:44.741
Click here to show the response body
Note: For information on how to interpret logs, see Logging.