Getting Started

This section shows how to install and set up Xtract Core for the first time.

About Xtract Core

Xtract Core is a whitelabel Web API server for developing your own SAP interfaces. The Xtract Core API enables you to extract data from SAP Tables and write them to target environments.

As Xtract Core is still in its initial release, only certain SAP objects and target environments are supported. Contact the Theobald Software sales team for feature requests or feedback.

For information on which SAP systems are supported, refer to the Xtract Core Requirements.

Get Xtract Core

Contact the Theobald Software sales team to get access to a 2 month trial version of Xtract Core.

You are guaranteed to get unrestricted support by the Theobald Software support team during the evaluation phase. In case of questions or doubts, feel free to contact Theobald Software at any time:

Setup

Xtract Core provides a configurable Windows service that acts as a web server to serve incoming API calls. The service and network settings of Xtract Core can be configured using the files in the installaltion directory of Xtract Core.

Prerequisites

• Contact the Theobald Software sales team to get a 2 month trial version of Xtract Core.
• Download and install the .NET8.0 Desktop Runtime from Microsoft and install it.
• Optional: Install the THEO/READ_TABLE function module in SAP to boost the capabilities of SAP table extractions. For more information, see Knowledge Base: Function Module for Tables.

For more information on system requirements and supported SAP systems, see Knowledge Base: Requirements.

Installation

Follow the steps below to install the Xtract Core Windows service:

1. Extract all files from the XtractCore.zip archive into the directory where you want to install Xtract Core.
2. Open a command line tool with administrator rights and navigate to the installation directory.
3. Run the following command to install the Xtract Core Windows service and to create a dedicated virtual user that runs the service:

   service.exe -i --virtual-service-user 
   

4. Make sure that the Xtract Core service "SAP Connector" is running on your Windows system and that the default port 1337 is not blocked by the firewall.
   

The Xtract Core Windows service can now receive HTTP requests. For information on how to change the default settings of the Xtract Core service, refer to the service settings and network-settings.

Files in the Installation Directory

The installation directory contains the following files:

Service Settings

The name (serviceName), displayed name (displayName) and description (description) of the Windows service can be changed in the theobald.service.definition.json file.

{
    "description": "A web API for extracting data from SAP systems",
    "displayName": "SAPConnector",
    "serviceName": "SAP Connector Service",
    "servers": [
        {
            "displayName": "listener",
            "path": "listener.exe"
        }
    ]
}

Network Settings

The network settings of the web server can be changed in the listener.json file.

{
    "insecurePort": 1337,
    "securePort": 1338,
    "workerName": "worker.exe",
    "mode": "Localhost(1)" 
}

1. The property mode supports Any and Localhost.
   • Any listens on the default network interface and the loopback interface.
   • Localhost only listens on the loopback interface.

TLS Configuration

You can enable Transport Layer Security (TLS) to use secured HTTPS communication for the web server. For information on how to set up TLS with Xtract Core, refer to the Knowledge Base Article: Install an X.509 Certificate.

How to use the API

The API Reference lists all available Xtract Core endpoints. It includes descriptions of all endpoints and their parameters. The Xtract Core API uses the following parameter types:

General Workflow

The general workflow for first-time Xtract Core users includes the following steps:

Create SAP Connections

Before connecting to SAP for the first time, set up an SAP dialog user with the necessary SAP user rights.
Use the following endpoint to create a new connection to an SAP application server:

POST /v1/connections/sap/{name}

POST /v1/connections/sap/{name} HTTP/1.1
Host: localhost:1337
Content-Type: application/json
Content-Length: 109

{
"Host": "sap-erp-as05.example.com(1)",
"User": "alice",
"Password": "myPassword",
"Client": "800",
"Language": "en",
"InstanceNo": 0
}

curl -X POST \
     -H '[Content-Type: application/json]' \
     -H '[Content-Length: 142]' \
     -d '"Host": "sap-erp-as05.example.com", "User": "alice", "Password": "myPassword", "Client": "800", "Language": "en", "InstanceNo": 0' \
     'http://localhost:1337/v1/connections/sap/{name}'

fetch('http://localhost:1337/v1/connections/sap/{name}', {
  "method": "POST",
  "headers": {
    "[Content-Type": "application/json]",
    "[Content-Length": "142]"
  },
  "body": JSON.stringify("Host": "sap-erp-as05.example.com", "User": "alice", "Password": "myPassword", "Client": "800", "Language": "en", "InstanceNo": 0)"
});

When this endpoint is called, the Xtract Core web server tries to establish a connection to the SAP system with the given credentials before saving the connection.

Create Azure Blob Storage Connections

To connect to a Microsoft Azure Blob Storage, generate a Shared Access Signature (SAS) token for authentication, see Microsoft Documentation: Create SAS tokens for storage containers. The following SAS permissions are required to write data to the Azure container:

• Add
• Create
• Write
• Delete
• List

Use the following endpoint to create a new connection to an Azure blob storage container:

POST /v1/connections/azureblob/{name}

POST /v1/connections/azureblob/{name} HTTP/1.1
Host: localhost:1337
Content-Type: application/json
Content-Length: 223

{
"Account": "my-account",
"Token": "sv=YYYY-MM-DD&ss=...%3D(1)",
"Container": "container"
}

curl -X POST \
     -H '[Content-Type: application/json]' \
     -H '[Content-Length: 223]' \
     -d '"Account": "my-account", "Token": "sv=YYYY-MM-DD&ss=...%3D", "Container": "container"' \
     'http://localhost:1337/v1/connections/azureblob/{name}'

fetch('http://localhost:1337/v1/connections/azureblob/{name}', {
  "method": "POST",
  "headers": {
    "[Content-Type": "application/json]",
    "[Content-Length": "223]"
  },
  "body": JSON.stringify("Account": "my-account", "Token": "sv=YYYY-MM-DD&ss=...%3D", "Container": "container")"
});

When this endpoint is called, the Xtract Core web server tries to establish a connection to Azure with the given credentials before saving the connection.

Create Table Extractions

Before creating extractions, make sure to meet the following requirements:

• A valid connection to an SAP system is available.
• The SAP user of the SAP connection has sufficient user rights, see Knowledge Base Article: SAP Authorization Objects
• A valid connection to a destination is available.
• You know the technical name of the SAP table you want to extract. You can fetch the names and descriptions of the tables in your SAP source system using the Xtract Core API.

Use the following endpoint to create a new table extraction:

POST /v1/extractions/table/{name}

POST /v1/extractions/table/{name} HTTP/1.1
Host: localhost:1337
Content-Type: application/json
Content-Length: 190

{
"Table": "MARA",
"Where": "MATNR = 000000000001",
"Source": "s4hana",
"Destination": "azure",
"Columns": ["MATNR", "MANDT"],
"ResultName": "materials",
"FunctionModule": "/THEO/READ_TABLE"
}

curl -X POST \
     -H '[Content-Type: application/json]' \
     -H '[Content-Length: 190]' \
     -d '"Table": "MARA", "Where": "MATNR = 000000000001", "Source": "s4hana", "Destination": "azure", "Columns": ["MATNR", "MANDT(1)"], "ResultName": "materials", "FunctionModule": "/THEO/READ_TABLE"' \
     'http://localhost:1337/v1/extractions/table/{name}'

fetch('http://localhost:1337/v1/extractions/table/{name}', {
  "method": "POST",
  "headers": {
    "[Content-Type": "application/json]",
    "[Content-Length": "190]"
  },
  "body": JSON.stringify("Table": "MARA", "Where": "MATNR = 000000000001", "Source": "s4hana", "Destination": "azure", "Columns": ["MATNR", "MANDT(1)"], "ResultName": "materials", "FunctionModule": "/THEO/READ_TABLE")"
});

Run Extractions

Extractions are executed on the web server. An extraction can be executed synchronously (run) or asynchronously (start). The response of an extraction run contains the following information:

Synchronous Extractions

When running extractions synchronously, the HTTP response head is returned as soon as the server receives the first data package. Use the following endpoint to run an extraction and wait for the result:

GET /run/{name} HTTP/1.1
Host: localhost:1337

curl -X GET 'http://localhost:1337/run/{name}/'

fetch('http://localhost:1337/run/{name}/', {"method": "GET"});

Asynchronous Extractions

When running extractions asynchronously, the request immediately returns the HTTP response head. Status information can be queried using the timestamp in the header. Use the following endpoint to run an extraction without waiting for the results:

GET /start/{name} HTTP/1.1
Host: localhost:1337

curl -X GET 'http://localhost:1337/start/{name}/'

fetch('http://localhost:1337/start/{name}/', {"method": "GET"});

Access Logs

Xtract Core logs all steps performed on a system in log files. The log files are located in the installation directory of Xtract Core. It is also possible to fetch logs using the Xtract Core API. For more information, refer to the API Reference.