Web API

This section contains a list of all API endpoints that are available for Xtract Universal.

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

Base URL

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.

Run Extractions

Run Extractions SynchronousRun Extractions Asynchronous

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

Runs the specified extraction.

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

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

Note

If the extraction is located inside an extraction group, the name of the extraction group is part of the extraction name. Example: The extraction "KNA1" in the extraction group "S4HANA" becomes S4HANA,KNA1.

Warning

Deprecated Endpoints:

[protocol]://[host]:[port]/?name=[extraction_name] becomes [protocol]://[host]:[port]/run/[extraction_name]
[protocol]://[host]:[port]/?name=[extraction_name]&wait=false becomes [protocol]://[host]:[port]/start/[extraction_name]

Response

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

	Response	Description
	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.
	HTTP header	Shows the timestamp of the extraction in the HTTP header e.g., X-XU-Timestamp: 2021-04-09_19:03:09.971
	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 for `[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.

Tip

You can use the UI in the "Run Extraction" menu to generate a URL for extraction runs, see Run Extractions.

Examples

http://sherri.theobald.local:8065/start/KNA1

MANDT,KUNNR,LAND1,NAME1,ORT01
800,0000000313,DE,zdemo customer zr,
800,0000001824,IN,,
800,0000001832,IN,cus 3,
800,0000001834,IN,52 CUSTOMER,
800,0000001837,IN,emax,
800,0000005002,JP,One time customer,
800,0000010009,,Einmalkunde,
800,0000011113,DE,Myers Corp.,
800,0000011114,DE,Watson & Watson,
800,0000100016,DE,Einmalkunde,
800,0000100026,DE,Reference Customer for Internet,
800,0000100236,US,,
800,0000100291,IN,RELIANCE FRESH DOMESTIC CUSTOMERS,
800,0000200000,IN,MA Reddy Customer,
800,0000200001,IN,SD Customer,
800,0000200002,IN,SMR Customer,
800,0000300050,,,
800,0000300065,GB,ComputerWorld,
800,0000300320,GB,Customer 1,
800,0000300430,DE,testcompany crm,
800,0000300735,US,OTHER MASS,
800,0000300736,US,OTHER GROCRY,
800,0000300737,US,OTHER CONVENIENCE,
800,0000300738,US,OTHER MILITARY,
800,0000300739,US,OTHER FOOD,
...

http://sherri.theobald.local:8065/start/KNA1/?cityParam=Stuttgart&companyParam=Theobald+Software

MANDT,KUNNR,LAND1,NAME1,ORT01
800,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.

Note

If the extraction is located inside an extraction group, the name of the extraction group is part of the extraction name.
Example: The extraction "KNA1" in the extraction group "S4HANA" becomes S4HANA,KNA1.

Example

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

All runs of extraction 'KNA1' aborted.

Get Status of an Extraction

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

Returns the status of a (running) extraction at the specified timestamp.

Note

If the extraction is located inside an extraction group, the name of the extraction group is part of the extraction name.
Example: The extraction "KNA1" in the extraction group "S4HANA" becomes S4HANA,KNA1.

Tip

The timestamp corresponds to the startedAt element returned by [protocol]://[host]:[port]/config/extractions/ or [protocol]://[host]:[port]/logs/extractions/[extraction-name]. If an extraction is triggered by an http request, the extraction's timestamp is returned in the field X-XU-Timestamp of the http request's response header.

Response

State	Description
Running	The extraction is running.
FinishedNoErrors	The extraction is finished without errors.
FinishedErrors	The extraction is finished, but with at least one error.

Example

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

FinishedNoErrors

Get Extraction Logs

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

Returns a list of extraction runs.

Response

The result contains the following elements:

Item	Description
extractionName	name of the extraction (if the extraction is located inside an extraction group, the name of the extraction group is part of the extraction name, e.g., the extraction "KNA1" in the extraction group "S4HANA" becomes `S4HANA,KNA1`)
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 for `[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.

Note

For information on how to interpret logs, see Logs.

Examples

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

{
"extractions": 
[
    {
        "extractionName": [
            "MEBEST"
        ],
        "runs": [
            {
                "rowCount": 53,
                "duration": "PT00H00M00.541S",
                "state": "FinishedNoErrors",
                "webServerLog": "2024-05-31_07:19:36.156",
                "startedAt": "2024-05-31_07:19:37.006"
            }
        ]
    },
    {
        "extractionName": [
            "S4HANA",
            "BSEG"
        ],
        "runs": [
            {
                "rowCount": 12036,
                "duration": "PT00H00M00.584S",
                "state": "FinishedNoErrors",
                "startedAt": "2024-06-12_08:56:28.066"
            }
        ]
    },
    {
        "extractionName": [
            "S4HANA",
            "KNA1"
        ],
        "runs": [
            {
                "rowCount": 10071,
                "duration": "PT00H00M03.753S",
                "state": "FinishedNoErrors",
                "webServerLog": "2024-04-12_11:10:59.505",
                "startedAt": "2024-04-12_11:11:57.977"
            },
            {
                "rowCount": 0,
                "duration": "PT00H00M03.068S",
                "state": "FinishedErrors",
                "webServerLog": "2024-05-31_07:20:06.041",
                "startedAt": "2024-05-31_07:20:06.840"
            }
        ]
    }
]

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

{
    "runs": [
        {
            "rowCount": 10071,
            "duration": "PT00H00M03.753S",
            "state": "FinishedNoErrors",
            "webServerLog": "2024-04-12_11:10:59.505",
            "startedAt": "2024-04-12_11:11:57.977"
        },
        {
            "rowCount": 0,
            "duration": "PT00H00M03.068S",
            "state": "FinishedErrors",
            "webServerLog": "2024-05-31_07:20:06.041",
            "startedAt": "2024-05-31_07:20:06.840"
        }
        ]
    }

http://sherri.theobald.local:8065/logs/extractions/KNA1/2024-04-12_11:11:57.977

{
    "rowCount": 10071,
    "duration": "PT00H00M03.753S",
    "state": "FinishedNoErrors",
    "webServerLog": "2024-04-12_11:10:59.505",
    "startedAt": "2024-04-12_11:11:57.977"
}

http://sherri.theobald.local:8065/logs/extractions/KNA1/2024-04-12_11:11:57.977/log

{
    "rowCount": 10071,
    "duration": "PT00H00M03.753S",
    "state": "FinishedNoErrors",
    "webServerLog": "2024-04-12_11:10:59.505",
    "startedAt": "2024-04-12_11:11:57.977",
    "logEntries": [
        {
            "timestamp": "2024-04-12_11:11:58.080",
            "logLevel": "Info",
            "source": "Table",
            "message": "Xtract Universal server version: 6.4.1.0"
        },
        {
            "timestamp": "2024-04-12_11:11:58.157",
            "logLevel": "Debug",
            "source": "Table",
            "message": "Attempting to load Theobald.Extractors.Table.TableExtractionDefinition information for extraction KNA1"
        },

        ...
        {
            "timestamp": "2024-04-12_11:12:01.728",
            "logLevel": "Debug",
            "source": "Table",
            "message": "Wrapping up extractor."
        },
        {
            "timestamp": "2024-04-12_11:12:01.730",
            "logLevel": "Info",
            "source": "Table",
            "message": "Extraction finished with status FinishedNoErrors."
        },
        {
            "timestamp": "2024-04-12_11:12:01.730",
            "logLevel": "Debug",
            "source": "Table",
            "message": "Writing run information."
        },
        {
            "timestamp": "2024-04-12_11:12:01.736",
            "logLevel": "Info",
            "source": "Table",
            "message": "Extraction run information was updated."
        }
    ]
}

Get Server Logs

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

Returns a list of timestamps that correspond to server logs.

Parameters & Options for `[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.

Note

For information on how to interpret logs, see Logs.

Examples

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

{
    "logs": 
    [
        "2024-06-18_10:19:05.500",
        "2024-06-20_12:33:11.346",
        "2024-06-20_12:59:16.603",
        "2024-06-20_13:00:47.833",
        "2024-06-20_13:01:50.974",
        "2024-06-20_13:02:10.364",
        "2024-06-20_13:02:17.521",
        "2024-06-20_13:03:08.071",
        "2024-06-20_13:03:08.819",
        "2024-06-20_13:03:59.725",
        "2024-06-20_13:15:45.630",
        "2024-06-20_13:21:43.620"
    ]
}

http://sherri.theobald.local:8065/logs/web/2024-06-20_13:21:43.620

{
    "logEntries": 
    [
        {
            "timestamp": "2024-06-20_13:21:43.707",
            "logLevel": "Info",
            "source": "WebServerHandler",
            "message": "Client [fe80::d3ac:77ba:ce0f:83b1%8]:56863"
        },
        {
            "timestamp": "2024-06-20_13:21:43.817",
            "logLevel": "Debug",
            "source": "HttpServer",
            "message": "Reading..."
        },
        {
            "timestamp": "2024-06-20_13:21:43.852",
            "logLevel": "Info",
            "source": "HttpServer",
            "message": "Processing /logs/extractions/S4HANA,KNA1."
        },

        ...

    ]
}

Get Software Version

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

Returns the software version of the Xtract Universal server installation in JSON format.

Example

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

{
  "version": "6.8.1.2"
}

Get Destination Details

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

Returns a list of all defined destinations. For a list of extractions with a specific destination, see Get Extraction Details.

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

Example

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

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.

Response

The result contains the following elements:

Item	Description
name	name of the extraction (if the extraction is located inside an extraction group, the name of the extraction group is part of the extraction name, e.g., the extraction "KNA1" in the extraction group "S4HANA" becomes `S4HANA,KNA1`)
type	extraction type
sapObject	name of the extracted SAP object
source	name of the source connection
destination	name of the target environment
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 for `[protocol]://[host]:[port]/config/extractions`

Parameter	Description
`/[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.
`/[extraction_name]/result-name`	Returns the name that is used by the extracted SAP data in the target environment. Destinations without output objects return the the HTTP status code 500.
`?destinationType=[destination]`	Returns a list of extractions that write into a specific destination.

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/

{
    "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

{
    "extractions": 
    [
        {
            "name": "BW,2LIS",
            "type": "ODP",
            "sapObject": "2LIS_11_VAITM",
            "source": "bw2",
            "destination": "sqlserver",
            "latestRun": {
                "rowCount": 59058,
                "duration": "PT00H00M30.593S",
                "state": "FinishedNoErrors",
                "webServerLog": "2024-05-22_06:44:30.412",
                "startedAt": "2024-05-22_06:44:30.855"
            },
            "created": {
                "machine": "SHERRI",
                "timestamp": "20240522T095026.285Z",
                "user": "THEOBALD\\schipka"
            },
            "lastChange": {
                "machine": "SHERRI",
                "timestamp": "20240529T102008.256Z",
                "user": "THEOBALD\\schipka"
            }
        }
    ]
}

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

{
    "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

{
    "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"
        }
    ]
}

Last update: July 17, 2024

Web API

Base URL

Examples

Run Extractions

Response

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

Examples

Abort Extraction

Example

Get Status of an Extraction

Response

Example

Get Extraction Logs

Response

Parameters & Options for [protocol]://[host]:[port]/logs/extractions

Examples

Get Server Logs

Parameters & Options for [protocol]://[host]:[port]/logs/web

Examples

Get Software Version

Example

Get Destination Details

Example

Get Extraction Details

Response

Parameters & Options for [protocol]://[host]:[port]/config/extractions

Examples

Parameters for `[protocol]://[host]:[port]/start/[extraction_name]`

Parameters & Options for `[protocol]://[host]:[port]/logs/extractions`

Parameters & Options for `[protocol]://[host]:[port]/logs/web`

Parameters & Options for `[protocol]://[host]:[port]/config/extractions`