Theobald Xtract Universal を使用してデータを読み込む

はじめに

このページでは、Theobald Xtract Universal (XU) を使用して、Process Mining (Automation Suite) のプロセス アプリに SAP のソース システムからデータを読み込む方法について説明します。Theobald Xtract Universal (XU) について詳しくは、Theobald Software の公式 Web サイトをご覧ください。

Theobald Xtract Universal を使用すると、SAP ECC や SAP HANA のデータ ソースに対するデータ アクセスと抽出を高速で行うことができます。Theobald Xtract Universal の使用方法に関する一般的な説明については、Theobald Software の公式ドキュメント「Getting Started with Theobald Xtract Universal」をご覧ください。

前提条件

以下を前提条件とします。

• 有効な Theobald Xtract Universal ライセンス。
• Theobald Xtract Universal をインストールしました。SAP での Theobald Xtract Universal のインストール、更新 、および表 抽出用の関数モジュールの カスタマイズについて詳しくは、Theobald Software の公式ドキュメントをご覧ください。

注:

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。

注:

このライセンスは、Process Mining のために UiPath によって提供されます。

Theobald Xtract Universal をセットアップするには、以下の手順に従います。

1. Theobald Xtract Universal の最新の無料トライアル版を UiPath の Web サイトからダウンロードする方法について詳しくは、「Download Trial Version」をご覧ください。Theobald Xtract Universal を Windows Server/仮想マシンにインストールします。
2. SAP システムへのネットワーク アクセスが開いているかどうかを確認するには、「SAP TCP/IP Ports」をご覧ください。
3. SAP インスタンスへのアクセス権を SAP ユーザーに付与するには、「Authority Objects - SAP User Rights for Table」をご覧ください。
4. 次の Theobald Xtract Universal のコンポーネントは、SAP でのカスタマイズが必要です: Z_THEO_READ_TABLE。
5. 目的のアプリ テンプレートに Theobald Xtract Universal を設定します。詳しくは、「アプリ テンプレート」をご覧ください。

注:

手順 2～4 では、社内の SAP チームによる検証が必要です。

SQL Server データベースの資格情報を設定する

Process Mining (Automation Suite) にデータをアップロードするには、抽出したデータをアップロードする必要がある、SQL Server データベースの場所へのアクセス権が必要です。SQL Server の宛先の接続を設定するには、SQL Server データベースの場所へのアクセスを認証するために、次の設定パラメーターが必要です。

• 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 Designer を開き、更新ボタンをクリックしてすべての抽出を読み込みます。

注:

既定のユーザーを使用してログインできます。

すべての抽出のリストが表示されます。そのそれぞれが 1 つのテーブルを SAP システムから抽出します。テンプレート ソースの名前は SAP で、テンプレートのターゲットの名前は SQL Server です。

ソースを構成する

Theobald Xtract Universal に SAP ソースを設定するには、以下の手順に従います。

手順	操作
1	[Server] - [Manage sources] に移動し、SAP ソースを編集します。
2	[General] タブと [Authentication] タブの設定を入力して、SAP システムに接続します。
3	接続をテストします。

宛先を設定する

Theobald Xtract Universal に SQL Server の同期先を設定するには、以下の手順に従います。

1. [Server - Manage destinations] に移動して、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 Software の公式ドキュメント「Call via Commandline」をご覧ください。セットアップに何らかの誤りがあると、それがエラー メッセージに表示されます。

データ実行のタスクのスケジュールを設定する

ファイルを手動で実行する代わりに Windows のタスク スケジューラを使用すれば、バッチ スクリプトを実行するタスクをスケジュールでき、データの更新を自動化できます。

注:

Windows のタスク スケジューラでタスクを作成する場合は、[タスクの作成] ウィンドウでタスクの実行者にローカルの SYSTEM ユーザー アカウントを選択し、[最上位の特権で実行する] オプションを選択することをお勧めします。

重要:

利用できるデータがない間隔を追加すると、ダッシュボードにエラー メッセージが表示されます。

抽出に成功した場合、欠陥のあるデータが抽出されたため、データの取り込みに失敗することがあります。Theobald Xtract Universal で WHERE 句を使用すると、このようなデータをフィルター処理して除外できます。WHERE 句について詳しくは、Theobald の公式ドキュメントをご覧ください。

注:

変数 (例: 抽出日) を使用する WHERE 句がある場合、UI でフィルター処理できません。

トラブルシューティング

データ実行ではログ ファイルも作成されます。これは、予期しない結果が発生した場合や、データ アップローダーでのデータのアップロードが失敗した場合に役立ちます。extraction.log ファイルには、前回のデータ実行のログが含まれています。失敗した各抽出に対して、リターン コードが表示されます。詳しくは、Theobald Software の公式ドキュメント「Call via Commandline」をご覧ください。セットアップに何らかの誤りがあると、それがエラー メッセージに表示されます。

HANA 以外のシステム向けの CDPOS の抽出の問題

HANA 以外の一部の古いシステムでは、CDPOS はクラスター テーブルであり、以下のような「join with pool table」のエラーが発生する可能性があります。

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 で [Refresh metadata] ボタンを選択してメタデータのプロパティを更新し、お使いの SAP システムを反映させます。その後、問題が解決したかどうかを確認します。

増分抽出の問題

Theobald Xtract Universal の増分抽出で問題が発生した場合は、抽出データを開いて [ CDC リソースを削除] を選択することで、増分設定をリセットできます。

これにより、最後に成功した抽出のレコードが削除されます。次回の抽出実行時には、テーブルの全読み込みが実行されます。その後、追加の抽出は再び増分的に実行されます。

このオプションは、抽出設定を変更する場合 (新しいフィールドを追加する場合など) にも使用できます。

タイムアウトの問題

抽出時に、タイムアウトの問題が発生する可能性があります。利用可能なタイムアウト パラメーターについて詳しくは、SAP の公式ドキュメントをご覧ください。

キーを複製する

Theobald Xtract Universal を使用してデータをアップロードする際に、次のエラー メッセージが表示されることがあります。

考えられる原因

テーブルの主キーに使用されているフィールドが、抽出で取得されていません。

解決策

この問題を解決するには、テーブルの主キーに使用されているすべてのフィールドが抽出で取得されていることを確認する必要があります。

以下の図に、EKKN テーブルの例を示します。このテーブルでは、フィールド ZEKKN が取得されていないため、主キーは完全ではありません。この問題は、このフィールドが抽出でも使用されるようにすることで修正できます。

ヒント:

SAP テーブルの主キーは、フィールド名の前に表示されるキー記号によって認識できます。