使用 Theobald Xtract Universal 加载数据

简介

本页面介绍了如何使用 Theobald Xtract Universal (XU) 将数据从 SAP 源系统加载到Process Mining (Automation Suite)中的流程应用程序中。有关 Theobald Xtract Universal (XU) 的更多信息，请前往Theobald 软件官方网站。

Theobald Xtract Universal 可以快速访问和提取 SAP ECC 和 SAP HANA 数据源。有关如何使用 Theobald Xtract Universal (XU) 的一般说明，请参阅官方 Theobald 软件文档 Theobald Xtract Universal 入门。

先决条件

假设您已经：

• 有效的 Theobald Xtract 通用许可证。
• 已安装 Theobald Xtract Universal。有关安装更新 Theobald Xtract Universal和自定义 SAP 中表格提取功能模块的更多信息，请参阅官方 Theobald 软件文档。

备注：

使用 Theobald Xtract Universal 加载数据需要可以执行命令行工具 ( xu.exe )，而无需额外的身份验证。

设置 Theobald Xtract Universal

Theobald Xtract Universal 是经过 SAP 认证的提取工具，用于从 SAP 源系统中提取数据，并通过远程函数调用 (RFC) 与 SAP 集成。Theobald Xtract Universal 包含要在 SAP 中安装的只读自定义功能模块。使用以下链接下载自定义模块：Z_THEO_READ_TABLE-transport1.zip。

备注：

许可证通过 UiPath 提供，用于 Process Mining。

请按照以下步骤设置 Theobald Xtract Universal。

1. 从我们的网站下载 Theobald Xtract Universal 的最新试用版，请参阅下载试用版。在 Windows Server/虚拟机上安装 Theobald Xtract Universal。
2. 检查 SAP 系统的网络访问是否已打开，请参阅SAP TCP/IP 端口。
3. 授予 SAP 用户访问 SAP 实例的权限，请参阅授权对象 - 适用于表格的 SAP 用户权限。
4. 需要在 SAP 中自定义 Theobald Xtract Universal 中的以下组件：Z_THEO_READ_TABLE。
5. 为所需的应用程序模板配置 Theobald Xtract Universal。请参阅应用程序模板。

备注：

步骤 2-4 需要 SAP 团队的验证。

Setup credentials for the SQL Server database

Uploading data to Process Mining (Automation Suite) requires access to the SQL Server database location to which the extracted data needs to be uploaded. To set up a SQL Server destination connection you need the following setup parameters to authenticate access to the SQL Server database location.

• Server
• Database
• Schema
• Role

查看检索 SQL Server 数据库参数。

使用 Theobald Xtract Universal 加载数据

使用 Theobald Xtract Universal 设置数据加载需要执行多个步骤。

1. 设置 SQL 用户以上传数据；
2. 导入模板提取；
3. 配置来源；
4. 配置目标；
5. 配置提取脚本；
6. 运行提取脚本。

下面将详细介绍这些步骤。

设置 SQL 用户以上传数据

每个使用通过提取程序上传数据选项的流程应用程序都需要专用的 SQL Server 用户，该用户对与流程应用程序相关联的架构拥有特定访问权限。

请执行以下步骤：

步骤	操作	语法
1	创建登录。 需要在主数据库中创建登录名。	CREATE LOGIN <SQL_login_name> WITH PASSWORD = '<Password>'
2	为登录创建数据库用户。 需要在 AutomationSuite_ProcessMining_Warehouse 数据库中创建此用户。	CREATE USER <User_name> FOR LOGIN <SQL_login_name>
3	将用户分配给正确的数据库角色。	SP_ADDROLEMEMBER <Role>, <User_name>
4	为已创建的用户设置默认架构。 只有使用 Theobald Xtract Universal 加载数据时才需要执行此步骤。	ALTER USER <User_name> WITH DEFAULT_SCHEMA = <Schema>

导入模板提取

请按照以下步骤在 Theobald Xtract Universal 中导入模板提取。

步骤	操作
1	转到“应用程序模板”页面，然后打开应用程序模板的文档页面。
2	找到“使用 Theobald Xtract Universal 加载数据”部分，然后下载适用于您的应用程序模板的 XU_template_extractions_as.zip 文件。请参阅应用程序模板。 此 XU_template_extractions_as.zip 文件包含文件夹 destinations、extractions 和 sources。
3	将下载的XU_template_extractions_as.zip文件中的文件夹复制到 Xtract Universal 的config文件夹。 此文件夹的位置为[XU_installation_path] /config。
4	打开 Xtract Universal 设计器，然后单击其中的刷新按钮以加载所有提取内容。

备注：

您可以使用默认用户登录。

系统将显示所有提取内容的列表，每个提取内容从 SAP 系统中提取一个表格。模板源名为SAP ，模板目标名为SQL Server 。

配置源

请按照以下步骤在 Theobald Xtract Universal 中配置 SAP 源。

步骤	操作
1	转到“服务器 - 管理来源” ，然后编辑 SAP 来源。
2	填写常规和身份验证选项卡上的设置以连接到 SAP 系统。
3	测试连接。

配置目标

请按照以下步骤在 Theobald Xtract Universal 中配置 SQL Server 目标。

1. 转到“服务器 - 管理目标” ，然后编辑 SQL Server 目标。
2. 填写设置以连接到 SQL Server 目标。

有关更多信息，请参阅检索 SQL Server 数据库参数。

配置提取脚本

请按照以下步骤配置提取脚本。

步骤	操作
1	转到“应用程序模板”页面，然后打开应用程序模板的文档页面。
2	找到“使用 Theobald Xtract Universal 加载数据”部分，然后下载应用程序模板的extract_theobald_as.zip文件。此extract_theobald_as.zip文件包含extract_theobald.ps1脚本和config.json文件。
3	在安装了 Theobald Xtract Universal 的服务器上解压extract_theobald_as.zip文件的内容。
4	在config.json中配置脚本的变量，如下所示。

变量	描述
xu_location	Xtract Universal 安装文件夹。您可以在其中找到 xu.exe 文件夹。例如：C:\MyFolder。
xu_server	安装 Xtract Universal 的服务器的地址。 默认值为localhost 。
xu_port	安装 Xtract Universal 的服务器的端口。 安装的默认端口为8065 。
as_server	URL 中表示创建应用程序的服务器的部分。请参阅检索 SQL Server 数据库参数。
as_organization	URL 中用于表示已创建应用程序的组织的部分。请参阅检索 SQL Server 数据库参数。
as_tenant	URL 中用于表示已创建应用程序的租户的部分。请参阅检索 SQL Server 数据库参数。
as_app_ID	已创建应用程序的应用程序 ID。
extraction_start_date	用于限制提取的开始日期。 仅在此日期筛选应用了日期筛选器的表格。 格式为 YYYYMMDD。 默认情况下无限制，开始日期 19700101指示。 extraction_start_date 必须具有值。
extraction_end_date	用于限制提取的结束日期。 仅在此日期筛选应用了日期筛选器的表格。 格式为 YYYYMMDD。 默认情况下，结束日期 20991231指示无限制。 extraction_end_date 必须具有值。
language	从源系统中提取数据所用的语言。 默认为 E。
exchange_rate_type	用于货币转换的汇率类型。 默认为 M。

运行提取脚本

要加载数据并将其上传以在 Process Mining 中使用，您必须运行 extract_theobald.ps1 文件。

此任务花费的时间在很大程度上取决于加载的数据量。

手动启动文件

请按照此步骤开始数据运行。

步骤	操作
1	运行 extract_theobald.ps1 文件以开始数据运行。

数据运行还会创建一个日志文件，如果出现意外结果或使用数据上传器上传数据失败，该文件可以提供帮助。文件 extraction.log 包含上次数据运行的日志。对于每个失败的提取，系统会显示返回代码。有关更多信息，请参阅 Theobald 软件官方文档通过命令行调用。如果设置不正确，则会在错误消息中提及。

为数据运行计划任务

除了手动运行文件外，您还可以使用 Windows 任务计划程序来计划任务，该任务会运行批处理脚本以实现自动数据刷新。

备注：

在 Windows 计划程序中创建任务时，建议选择本地系统用户帐户来运行任务，并在“创建任务”窗口中选择“以最高优先级运行”。

重要提示：

如果您添加没有可用数据的间隔，仪表板将显示错误消息。

成功提取后，由于提取了错误的数据，数据提取可能会失败。您可以使用 WHERE 语句使用 Theobald Xtract Universal 筛选出此数据。有关 WHERE 语句的更多信息，请参阅 Theobald 官方文档。

备注：

如果您的 WHERE 子句使用变量（例如提取日期），则无法通过用户界面进行筛选。

故障排除

数据运行还会创建一个日志文件，如果出现意外结果或使用数据上传器上传数据失败，该文件可以提供帮助。文件 extraction.log 包含上次数据运行的日志。对于每个失败的提取，系统会显示返回代码。有关更多信息，请参阅 Theobald 软件官方文档通过命令行调用。如果设置不正确，则会在错误消息中提及。

针对非 HANA 系统的 CDPOS 的提取问题

在某些较旧的非 HANA 系统中，CDPOS 是集群表，可能会导致“与池表联接”错误，如下所示。

默认情况下， CDPOS表的提取包括与CDHDR表的联接，以限制需要提取的记录数。 请按照以下步骤解决此错误。

1. 在 Xtract Universal Designer 中编辑 CDPOS 提取，以从表格中删除 CDHDR。

2. 将CDHDR~UDATE between @extraction_start_date and @extraction_end_date替换为：

   CHANGENR between @CHANGENR_min and @CHANGENR_max

3. 在 extract_theobald.ps1中，将 &"$xu_location\xu.exe" -s "$xu_server" -p "$xu_port" -n "CDPOS" -o "extraction_start_date=$extraction_start_date" -o "extraction_end_date=$extraction_end_date" 替换为下面显示的代码。

&"$xu_location\xu.exe" -s "$xu_server" -p "$xu_port" -n "CDHDR_CSV" -o "extraction_start_date=$extraction_start_date" -o "extraction_end_date=$extraction_end_date"
CheckExtractionError('CDHDR_CSV')
$CDHDR = Import-Csv -Path "$xu_location\<app_template_specific>output\CDHDR_CSV.csv" -Delimiter "`t"
$CDHDR_sorted = $CDHDR | Sort-Object -Property CHANGENR
$CHANGENR_min=$CDHDR_sorted.GetValue(0).CHANGENR
$CHANGENR_max=$CDHDR_sorted.GetValue($CDHDR_sorted.Count-1).CHANGENR
&"$xu_location\xu.exe" -s "$xu_server" -p "$xu_port" -n "CDPOS" -o "CHANGENR_min=$CHANGENR_min" -o "CHANGENR_max=$CHANGENR_max"

备注：

这是一个一般示例，表格名称可以与应用程序模板的不同。

备注：

将输出文件夹 <app_template_specific>替换为在 extract_theobald.ps1 中为您指定的应用程序模板的输出文件夹。

其他提取问题

解析错误

当提取由于解析错误（例如Unexpected ')' ）而失败时，请检查失败的提取的WHERE子句。确保中括号的间距及其中的值正确无误。格式不一致可能会导致出现解析问题。

例如， name in ('a', ‘b', ‘c’)应更新为name in ( ‘a’, ‘b’, ‘c’ ) ）。

更正WHERE子句并保存提取后，再次运行。

元数据

在提取过程中，您可能会遇到意外错误。 例如：

23,O2C_VBAK,2023-05-16_08:46:54.984,4,FinishedErrors,Error,LiveDataExtraction,Theobald.Extractors.Table.TheoReadTableException: Length of the field VBTYP not valid. Given length is 000002 . Length in SAP is 000008

这可能是由于模板提取中定义的属性与您的 SAP 系统不匹配所致。

在 Theobald Xtract Universal 中，选择“刷新元数据”按钮以更新元数据属性，以反映您的 SAP 系统，并检查问题是否已解决。

增量提取问题

如果您在 Theobald Xtract Universal 中遇到增量提取问题，可以通过打开提取并选择“删除 UTC 资源”来重置增量设置。

这将删除上次成功提取的记录。下次运行提取时，它将执行表格的完整加载。后续提取将再次以增量方式运行。

修改提取配置（例如，添加新字段）时，您也可以使用此选项。

超时问题

在提取期间，您可能会遇到超时问题。请参阅官方SAP 文档，查看可用的超时参数。

复制密钥

使用 Theobald Xtract Universal 上传数据时，可能会出现以下错误消息：

可能的原因

提取中不会检索用于表格主键的字段。

解决方案

要解决此问题，您需要检查提取过程中是否检索到了用于表格主键的所有字段。

下图显示了EKKN表中的示例。 此表格的主键不完整，因为未检索到字段ZEKKN 。 可以通过确保在提取中也使用此字段来解决此问题。

提示：

SAP 表中的主键可以通过字段名称前面显示的键符号来识别。