diff --git a/openmetadata-docs/content/v1.5.x/connectors/database/sap-erp/index.md b/openmetadata-docs/content/v1.5.x/connectors/database/sap-erp/index.md new file mode 100644 index 000000000000..13d1129b77b1 --- /dev/null +++ b/openmetadata-docs/content/v1.5.x/connectors/database/sap-erp/index.md @@ -0,0 +1,67 @@ +--- +title: SAP ERP +slug: /connectors/database/sap-erp +--- + +{% connectorDetailsHeader +name="SAP ERP" +stage="PROD" +platform="OpenMetadata" +availableFeatures=["Metadata", "dbt"] +unavailableFeatures=["Query Usage", "Stored Procedures", "Owners", "Tags","Data Profiler", "Data Quality", "View Lineage", "View Column-level Lineage"] +/ %} + + +In this section, we provide guides and references to use the SAP ERP connector. + +Configure and schedule SAP ERP metadata workflow from the OpenMetadata UI: + +- [Requirements](#requirements) +- [Metadata Ingestion](#metadata-ingestion) +- [dbt Integration](/connectors/ingestion/workflows/dbt) + +{% partial file="/v1.5/connectors/ingestion-modes-tiles.md" variables={yamlPath: "/connectors/database/sap-erp/yaml"} /%} + +## Requirements + +To ingest the SAP ERP metadata, CDS Views and OData services need to be setup to efficiently expose SAP data. To achieve this, data must be exposed via RESTful interfaces. +Follow the guide [here](/connectors/database/sap-erp/setup-sap-apis) to setup the APIs. + +## Metadata Ingestion + +{% partial + file="/v1.5/connectors/metadata-ingestion-ui.md" + variables={ + connector: "SAP ERP", + selectServicePath: "/images/v1.5/connectors/sap-erp/select-service.png", + addNewServicePath: "/images/v1.5/connectors/sap-erp/add-new-service.png", + serviceConnectionPath: "/images/v1.5/connectors/sap-erp/service-connection.png", +} +/%} + +{% stepsContainer %} +{% extraContent parentTagName="stepsContainer" %} + +#### Connection Details + +- **Host and Port**: This parameter specifies the host and port of the SAP ERP instance. This should be specified as a string in the format `https://hostname.com`. +- **API Key**: Api Key to authenticate the SAP ERP Apis. +- **database**: Optional name to give to the database in OpenMetadata. If left blank, we will use `default` as the database name. +- **databaseSchema**: Optional name to give to the database schema in OpenMetadata. If left blank, we will use `default` as the database schema name. +- **paginationLimit**: Pagination limit used while querying the SAP ERP APIs for fetching the entities. + +{% partial file="/v1.5/connectors/database/advanced-configuration.md" /%} + +{% /extraContent %} + +{% partial file="/v1.5/connectors/test-connection.md" /%} + +{% partial file="/v1.5/connectors/database/configure-ingestion.md" /%} + +{% partial file="/v1.5/connectors/ingestion-schedule-and-deploy.md" /%} + +{% /stepsContainer %} + +{% partial file="/v1.5/connectors/troubleshooting.md" /%} + +{% partial file="/v1.5/connectors/database/related.md" /%} diff --git a/openmetadata-docs/content/v1.5.x/connectors/database/sap-erp/setup-sap-apis.md b/openmetadata-docs/content/v1.5.x/connectors/database/sap-erp/setup-sap-apis.md new file mode 100644 index 000000000000..19b17292cb39 --- /dev/null +++ b/openmetadata-docs/content/v1.5.x/connectors/database/sap-erp/setup-sap-apis.md @@ -0,0 +1,147 @@ +--- +title: Setup SAP ERP APIs +slug: /connectors/database/sap-erp/setup-sap-apis +--- +# Setup SAP ERP APIs + +In this section, we provide guides and references to use setup the SAP ERP APIs needed for the connector. + +This document details the integration of Open Metadata with SAP systems, emphasizing the use of CDS Views and OData services to efficiently expose SAP data. To achieve this, data must be exposed via RESTful interfaces. Key concepts include: + +- **SAP Gateway**: A software component that bridges RFC and RESTful interfaces. +- **RAP (Restful Application Programming)**: A coding framework designed to expose services via RESTful interfaces. +- **CDS (Core Data Services)**: A layer that describes data objects and annotates them with desired functionalities, which are converted into code upon activation. +- **OData V2 or V4**: A RESTful standard that simplifies interaction with database backends. + + +## Steps +### 1. ABAP Development Tools (ADT) +Using the Eclipse based [ABAP Development Tools (ADT)](https://tools.hana.ondemand.com/#abap) the Restful interfaces are built. + +### 2. CDS Views +After creating a new ABAP Project for the connected SAP system, a new Data Definition object is to be created. + +{% image +src="/images/v1.5/connectors/sap-erp/data-definition-object.png" +alt="Data Definition Object" +caption="Create data definition object" /%} + +- Create the first view that gets the table metadata +```sql +@AbapCatalog.sqlViewName: 'ZZ_I_DDIC_TAB_CDS' +@AbapCatalog.compiler.compareFilter: true +@AbapCatalog.preserveKey: true +@AccessControl.authorizationCheck: #CHECK +@EndUserText.label: 'Open Metadata Tables' +define view ZZ_I_DDIC_TAB_CDS as select from dd02l l +left outer join dd02t t on + (l.tabname = t.tabname and l.as4local = t.as4local and l.as4vers = t.as4vers and t.ddlanguage = 'E') +{ +key l.tabname, +key l.as4local, +key l.as4vers, + @ObjectModel.readOnly: true + 'E' as LANG, + @ObjectModel.readOnly: true + l.tabclass, + @ObjectModel.readOnly: true + l.sqltab, + @ObjectModel.readOnly: true + l.applclass, + @ObjectModel.readOnly: true + l.authclass, + @ObjectModel.readOnly: true + l.as4date, + @ObjectModel.readOnly: true + l.as4time, + @ObjectModel.readOnly: true + l.masterlang, + @ObjectModel.readOnly: true + t.ddtext +} +``` + +- Then create the second view for table columns +```sql +@AbapCatalog.sqlViewName: 'ZZ_I_DDIC_COL_CDS_V' +@AbapCatalog.compiler.compareFilter: true +@AbapCatalog.preserveKey: true +@AccessControl.authorizationCheck: #CHECK +@EndUserText.label: 'Open Metadata Column' +define view ZZ_I_DDIC_COL_CDS as select from dd03l l +left outer join dd03t t on + (l.tabname = t.tabname and l.fieldname = t.fieldname and l.as4local = t.as4local and t.ddlanguage = 'E') +{ +key l.tabname, +key l.fieldname, +key l.as4local, +key l.as4vers, +key l.position as POS, + @ObjectModel.readOnly: true + 'E' as LANG, + @ObjectModel.readOnly: true + l.keyflag, + @ObjectModel.readOnly: true + l.mandatory, + @ObjectModel.readOnly: true + l.checktable, + @ObjectModel.readOnly: true + l.inttype, + @ObjectModel.readOnly: true + l.intlen, + @ObjectModel.readOnly: true + l.reftable, + @ObjectModel.readOnly: true + l.precfield, + @ObjectModel.readOnly: true + l.reffield, + @ObjectModel.readOnly: true + l.notnull, + @ObjectModel.readOnly: true + l.datatype, + @ObjectModel.readOnly: true + l.leng, + @ObjectModel.readOnly: true + l.decimals, + @ObjectModel.readOnly: true + l.domname, + @ObjectModel.readOnly: true + l.comptype, + @ObjectModel.readOnly: true + l.reftype, + @ObjectModel.readOnly: true + t.ddtext +} +where l.as4local = 'A' +``` +### 3. SAP Gateway +Using the transaction `/nsegw` in SAPGUI, open the configuration screen for the SAP Gateway and create a new project with default project type. + +{% image +src="/images/v1.5/connectors/sap-erp/create-project.png" +alt="Create Project" +caption="Create Project" /%} + +Create a reference to the CDS views under Data Model and import the views. This is all that is needed to configure the OData details thanks to the CDS view annotations. + +{% image +src="/images/v1.5/connectors/sap-erp/add-reference.png" +alt="Add Reference" +caption="Add Reference" /%} + +The final step is to expose the generated code as OData service. This is the Register step. + +{% image +src="/images/v1.5/connectors/sap-erp/register-odata-service.png" +alt="Register odata Service" +caption="Register odata Service" /%} + +In the next screen click on Add Service and add the service as new OData endpoint. The service alias is the location where the SAP Gateway is installed. + +{% image +src="/images/v1.5/connectors/sap-erp/add-service-as-endpoint.png" +alt="Add Service As Endpoint" +caption="Add Service As Endpoint" /%} + + + diff --git a/openmetadata-docs/content/v1.5.x/connectors/database/sap-erp/yaml.md b/openmetadata-docs/content/v1.5.x/connectors/database/sap-erp/yaml.md new file mode 100644 index 000000000000..46d703d5a6dd --- /dev/null +++ b/openmetadata-docs/content/v1.5.x/connectors/database/sap-erp/yaml.md @@ -0,0 +1,198 @@ +--- +title: Run the SAP ERP Connector Externally +slug: /connectors/database/sap-erp/yaml +--- + +{% connectorDetailsHeader +name="SAP ERP" +stage="PROD" +platform="OpenMetadata" +availableFeatures=["Metadata", "dbt"] +unavailableFeatures=["Query Usage", "Stored Procedures", "Owners", "Tags","Data Profiler", "Data Quality", "View Lineage", "View Column-level Lineage"] +/ %} + +In this section, we provide guides and references to use the SAP ERP connector. + +Configure and schedule SAP ERP metadata workflow externally: + +- [Requirements](#requirements) +- [Metadata Ingestion](#metadata-ingestion) +- [dbt Integration](#dbt-integration) + +{% partial file="/v1.5/connectors/external-ingestion-deployment.md" /%} + +## Requirements + +{%inlineCallout icon="description" bold="OpenMetadata 1.1 or later" href="/deployment"%} +To deploy OpenMetadata, check the Deployment guides. +{%/inlineCallout%} + +To ingest the SAP ERP metadata, CDS Views and OData services need to be setup to efficiently expose SAP data. To achieve this, data must be exposed via RESTful interfaces. +Follow the guide [here](/connectors/database/sap-erp/setup-sap-apis) to setup the APIs. + + +### Python Requirements + +{% partial file="/v1.5/connectors/python-requirements.md" /%} + +To run the SAP ERP ingestion, you will need to install: + +```bash +pip3 install "openmetadata-ingestion[sap-erp]" +``` + +## Metadata Ingestion + +All connectors are defined as JSON Schemas. +[Here](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-spec/src/main/resources/json/schema/entity/services/connections/database/sapErpConnection.json) +you can find the structure to create a connection to SAP ERP. + +In order to create and run a Metadata Ingestion workflow, we will follow +the steps to create a YAML configuration able to connect to the source, +process the Entities if needed, and reach the OpenMetadata server. + +The workflow is modeled around the following +[JSON Schema](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-spec/src/main/resources/json/schema/metadataIngestion/workflow.json) + +### 1. Define the YAML Config + +This is a sample config for SAP ERP: + +{% codePreview %} + +{% codeInfoContainer %} + +#### Source Configuration - Service Connection + +{% codeInfo srNumber=1 %} + +**hostPort**: Host and port of the SAP ERP service. This specifies the host and port of the SAP ERP instance. It should be specified as a string in the format `https://hostname.com`. + +{% /codeInfo %} + +{% codeInfo srNumber=2 %} + +**apiKey**: Api Key to authenticate the SAP ERP Apis + +{% /codeInfo %} + +{% codeInfo srNumber=3 %} + +**databaseName**: In OpenMetadata, the Database Service hierarchy works as follows: +`Database Service > Database > Schema > Table` +In the case of SAP ERP, we won't have a Database as such. If you'd like to see your data in a database named something other than `default`, you can specify the name in this field. + +{% /codeInfo %} + +{% codeInfo srNumber=4 %} + +**databaseSchema**: In OpenMetadata, the Database Service hierarchy works as follows: +`Database Service > Database > Schema > Table` +In the case of SAP ERP, we won't have a Database Schema as such. If you'd like to see your data in a database schema named something other than `default`, you can specify the name in this field. + +{% /codeInfo %} + +{% codeInfo srNumber=5 %} + +**paginationLimit**: Pagination limit used while querying the SAP ERP API for fetching the entities. + +{% /codeInfo %} + +{% partial file="/v1.5/connectors/yaml/database/source-config-def.md" /%} + +{% partial file="/v1.5/connectors/yaml/ingestion-sink-def.md" /%} + +{% partial file="/v1.5/connectors/yaml/workflow-config-def.md" /%} + +#### Advanced Configuration + +{% codeInfo srNumber=7 %} + +**Connection Options (Optional)**: Enter the details for any additional connection options that can be sent to database during the connection. These details must be added as Key-Value pairs. + +{% /codeInfo %} + +{% codeInfo srNumber=8 %} + +**Connection Arguments (Optional)**: Enter the details for any additional connection arguments such as security or protocol configs that can be sent to database during the connection. These details must be added as Key-Value pairs. + +- In case you are using Single-Sign-On (SSO) for authentication, add the `authenticator` details in the Connection Arguments as a Key-Value pair as follows: `"authenticator" : "sso_login_url"` + +{% /codeInfo %} + +{% /codeInfoContainer %} + +{% codeBlock fileName="filename.yaml" %} + +```yaml {% isCodeBlock=true %} +source: + type: SapErp + serviceName: + serviceConnection: + config: + type: SapErp +``` +```yaml {% srNumber=1 %} + hostPort: https://localhost.com +``` +```yaml {% srNumber=2 %} + apiKey: api_key +``` +```yaml {% srNumber=3 %} + databaseName: databaseName +``` +```yaml {% srNumber=4 %} + databaseSchema: databaseSchema +``` +```yaml {% srNumber=5 %} + paginationLimit: 100 +``` +```yaml {% srNumber=9 %} + # sslConfig: + # caCertificate: "path/to/ca/certificate" + # sslMode: disable #allow prefer require verify-ca verify-full +``` +```yaml {% srNumber=6 %} + # connectionOptions: + # key: value +``` +```yaml {% srNumber=7 %} + # connectionArguments: + # key: value +``` + +{% partial file="/v1.5/connectors/yaml/database/source-config.md" /%} + +{% partial file="/v1.5/connectors/yaml/ingestion-sink.md" /%} + +{% partial file="/v1.5/connectors/yaml/workflow-config.md" /%} + +{% /codeBlock %} + +{% /codePreview %} + +{% partial file="/v1.5/connectors/yaml/ingestion-cli.md" /%} + +## Securing SAP ERP Connection with SSL in OpenMetadata + +To configure SSL for secure connections between OpenMetadata and a Redshift database, Redshift offers various SSL modes, each providing different levels of connection security. + +When running the ingestion process externally, specify the SSL mode to be used for the Redshift connection, such as `prefer`, `verify-ca`, `allow`, and others. Once you've chosen the SSL mode, provide the CA certificate for SSL validation (`caCertificate`). Only the CA certificate is required for SSL validation in Redshift. + +```yaml + sslMode: disable #allow prefer require verify-ca verify-full + sslConfig: + caCertificate: "/path/to/ca/certificate" +``` + +## dbt Integration + +{% tilesContainer %} + +{% tile + icon="mediation" + title="dbt Integration" + description="Learn more about how to ingest dbt models' definitions and their lineage." + link="/connectors/ingestion/workflows/dbt" /%} + +{% /tilesContainer %} diff --git a/openmetadata-docs/content/v1.5.x/menu.md b/openmetadata-docs/content/v1.5.x/menu.md index 0086549e9a9b..9446600b31cd 100644 --- a/openmetadata-docs/content/v1.5.x/menu.md +++ b/openmetadata-docs/content/v1.5.x/menu.md @@ -358,6 +358,12 @@ site_menu: url: /connectors/database/sap-hana - category: Connectors / Database / SAP Hana / Run Externally url: /connectors/database/sap-hana/yaml + - category: Connectors / Database / SAP ERP + url: /connectors/database/sap-erp + - category: Connectors / Database / SAP ERP / Run Externally + url: /connectors/database/sap-erp/yaml + - category: Connectors / Database / SAP ERP / Setup SAP ERP APIs + url: /connectors/database/sap-erp/setup-sap-apis - category: Connectors / Database / SAS url: /connectors/database/sas - category: Connectors / Database / SAS / Run Externally diff --git a/openmetadata-docs/images/v1.5/connectors/sap-erp/add-new-service.png b/openmetadata-docs/images/v1.5/connectors/sap-erp/add-new-service.png new file mode 100644 index 000000000000..e307896ee2d0 Binary files /dev/null and b/openmetadata-docs/images/v1.5/connectors/sap-erp/add-new-service.png differ diff --git a/openmetadata-docs/images/v1.5/connectors/sap-erp/add-reference.png b/openmetadata-docs/images/v1.5/connectors/sap-erp/add-reference.png new file mode 100644 index 000000000000..e627633810bc Binary files /dev/null and b/openmetadata-docs/images/v1.5/connectors/sap-erp/add-reference.png differ diff --git a/openmetadata-docs/images/v1.5/connectors/sap-erp/add-service-as-endpoint.png b/openmetadata-docs/images/v1.5/connectors/sap-erp/add-service-as-endpoint.png new file mode 100644 index 000000000000..0f41f446dbc4 Binary files /dev/null and b/openmetadata-docs/images/v1.5/connectors/sap-erp/add-service-as-endpoint.png differ diff --git a/openmetadata-docs/images/v1.5/connectors/sap-erp/create-project.png b/openmetadata-docs/images/v1.5/connectors/sap-erp/create-project.png new file mode 100644 index 000000000000..f842c37d5b3d Binary files /dev/null and b/openmetadata-docs/images/v1.5/connectors/sap-erp/create-project.png differ diff --git a/openmetadata-docs/images/v1.5/connectors/sap-erp/data-definition-object.png b/openmetadata-docs/images/v1.5/connectors/sap-erp/data-definition-object.png new file mode 100644 index 000000000000..8fbd8446177c Binary files /dev/null and b/openmetadata-docs/images/v1.5/connectors/sap-erp/data-definition-object.png differ diff --git a/openmetadata-docs/images/v1.5/connectors/sap-erp/register-odata-service.png b/openmetadata-docs/images/v1.5/connectors/sap-erp/register-odata-service.png new file mode 100644 index 000000000000..1982ce0eb764 Binary files /dev/null and b/openmetadata-docs/images/v1.5/connectors/sap-erp/register-odata-service.png differ diff --git a/openmetadata-docs/images/v1.5/connectors/sap-erp/select-service.png b/openmetadata-docs/images/v1.5/connectors/sap-erp/select-service.png new file mode 100644 index 000000000000..dc8440250c5a Binary files /dev/null and b/openmetadata-docs/images/v1.5/connectors/sap-erp/select-service.png differ diff --git a/openmetadata-docs/images/v1.5/connectors/sap-erp/service-connection.png b/openmetadata-docs/images/v1.5/connectors/sap-erp/service-connection.png new file mode 100644 index 000000000000..3f338a572012 Binary files /dev/null and b/openmetadata-docs/images/v1.5/connectors/sap-erp/service-connection.png differ