はじめに

WinActorのOAuth関連ライブラリを使用して、Salesforce Lightning Platform (以降、Salesforceと記載します。) の Leadオブジェクトから、データを取得するサンプルシナリオについて説明します。

本サンプルシナリオの概要

本サンプルシナリオは、以下の処理を行います。

• OAuthを使用して、Salesforce のアクセストークンを取得します。
• Excelファイルを開いて、取得データの名称を取得します。
  
• Salesforce LeadからデータをID順に取得します。
  
• Excelファイルの最後尾に取得したデータを格納します。
• 使用したSalesforce のアクセストークンを開放します。

使用するWinActorモジュール

本サンプルシナリオでは、以下のWinActorモジュールを使用します。

• ノード/アクション/スクリプト実行
• ノード/アクション/クリップボード
• ノード/ユーザ/待機ボックス
• ノード/変数/カウントアップ

• ノード/変数/変数値設定

• 01_WinActor制御/02_シナリオ制御/シナリオ停止.ums5

• 07_文字列操作/03_連結/文字列の連結（２つ）.ums5

• 13_ファイル関連/02_ファイル操作/ファイル存在有無チェック.ums5

• 13_ファイル関連/05_ファイル名/シナリオフォルダのファイルパス.ums5

• 18_Excel関連/01_ファイル操作/Excel開く（前面化）.ums5
• 18_Excel関連/03_行列操作/Excel操作(行コピー).ums5
• 18_Excel関連/03_行列操作/Excel操作(最終行取得　その１).ums5
• 18_Excel関連/04_セル操作/Excel操作(セルのアクティブ化).ums5

• 18_Excel関連/04_セル操作/Excel操作(上書き保存する).ums5

• 99_外部サービス連携/01_OAuth関連/アクセストークンの取得.ums5
  
• 99_外部サービス連携/01_OAuth関連/アクセストークンの取り消し.ums5
  

• 99_外部サービス連携/01_OAuth関連/RESTful API実行.ums5

本サンプルシナリオの入力ファイル

Excelファイルを入力ファイルとします。
シナリオ内でExcelファイルをオープンし、処理を実施するのに必要な情報を取得します。
入力ファイルの詳細は入力ファイルの形式を参照してください。

本サンプルシナリオの出力ファイル

Salesforceから取得したJSONファイルを、「入力ファイル名.json」として保存します。
取得したJSONファイルから抽出したデータを、Excelファイルの最後尾に追記します。

本サンプルシナリオの想定レベル

本ドキュメントは、以下の技術レベルのユーザを対象としています。

• Salesforce の REST API の使い方について理解している。
  
• OAuth認証の用語について理解している。

動作確認環境

本サンプルシナリオは以下の環境で確認しています。

• Windows 10
  
• WinActor 5.3.1
  
• Microsoft Excel 2016
  
• Salesforce REST API v44.0

制約事項

• 本サンプルシナリオを実行するためには、Salesforce Lightning Platform Developer Editionにアクセスするためのインターネット環境が必要です。
  
• 本サンプルシナリオおよびドキュメントは、Salesforce Lightning Platform Developer Edition のアカウントを新規作成した状態を前提に記載されています。
  
• Salesforce Lightning Platform Developer Editionの利用方法やREST APIの使用、OAuth認証用パラメータの取得方法などは、Salesforce社のドキュメントを参照してください。
  
• 本サンプルシナリオは WinActor 5.3.1 でサポートされた機能を使用しています。WinActor 5.3.1 より古いバージョンでは動作しません。
• 本サンプルシナリオは、大量データでの動作は未検証です。問題が発生した場合は、一度に取得するデータ量を減らすことにより処理を分割してみてください。
• 本サンプルシナリオは、nextRecordsUrl（大量データが存在し、１回のリクエストでは全てを取得できない時に、Salesforceが応答に組み込む情報）には未対応です。

本サンプルシナリオの使い方

本サンプルシナリオの実施方法は以下の通りです。

Step 1. Salesforceの接続アプリケーション設定

本サンプルシナリオでSalesforce にアクセスする場合、Salesforce 側にも接続用のアプリケーションが必要です。まだ 接続アプリケーションを作成していない場合は、 Salesforce.com日本語公開ヘルプサイトの「接続アプリケーションの作成」 を参照して、以下の接続アプリケーションを作成してください。

• OAuth 設定の有効
• データへのアクセスと管理 (api)実施可能
• Web サーバフローの秘密が必要
• 存在しないURLのコールバックを指定（例：mysampleapp://auth/success）

Step 2. 入力ファイルをディレクトリに配置

本サンプルシナリオ（SS1903_5448_AccessSalesforceLead_Read.ums5）が格納されているディレクトリに移動します。
このディレクトリに入力ファイルを配置します。
本サンプルシナリオには、サンプルのExcelファイル(sample_read_alldata.xlsx)が添付されています。
このファイルを使用して、取得を行うことができます。
他の入力ファイルを使用する場合は、その入力ファイルを、本サンプルシナリオと同じディレクトリに配置します。

Step 3. WinActorで本サンプルシナリオを読み込み

WinActorを起動し、本サンプルシナリオを読み込みます。

Step 4. Salesforceアクセス用情報を設定

Salesforceの接続アプリケーションにアクセスするための値を、変数一覧で設定します。
アクセス用情報の設定 を参照してください。

Step 5. 入力ファイル名を設定

本サンプルシナリオを実行するために必要な値を、変数一覧で更新します。
本サンプルシナリオの実行にあたり、事前に設定が必要な変数は下記の通りです。

• 入力ファイル
  • 本サンプルシナリオの入力ファイル名を指定します。
    例) sample_read_alldata.xlsx

Step 6. WinActorで本サンプルシナリオを実行

本サンプルシナリオを実行開始します。
SalesforceのLeadオブジェクトに登録されている全データを取得します。

Step 7. サンプルシナリオ実行終了後の確認

Salesforceのサイトにアクセスし、登録されているデータがすべて入力ファイル（Excel）に格納されていることを確認してください。

トラブルシューティング

本サンプルシナリオでは、シナリオ固有のエラーメッセージ、および使用しているライブラリ由来のエラーメッセージを表示することがあります。

以下に、シナリオ固有のエラーメッセージについて記載します。

ライブラリ由来のエラーメッセージについては、ライブラリのエラーメッセージ一覧を参照してください。

サンプルシナリオ解説

本サンプルシナリオで使用している実装テクニックについて説明します。

入力ファイルの形式

入力ファイル(Excel)は以下の形式をとります。

何の項目を取得するかを、入力ファイルの１行目にヘッダとして指定します。
必須項目、および任意の項目を指定可能です。

本サンプルシナリオで確認している項目については、Salesforce Leadのデータ項目 を参照してください。

Salesforceでは、Lead等の各オブジェクトに新しいデータを追加したり、データ形式を変更することができます。
Leadの初期値に無い項目を指定して取得することも可能ですが、本サンプルシナリオでは、Leadの初期状態でのみ動作確認を行っています。

Salesforceに送る情報(RESTful API URLパス名)

本サンプルシナリオでは、RESTful API実行.ums5ライブラリ呼び出し時、「RESTful API URLパス名」にLeadからのデータ取得用SQL文を指定して、全データを取得しています。
取得データの条件を変更したい場合、この「RESTful API URLパス名」に渡す内容「header_tail」（「RESTful API URLパス名」の後半部として使用） を変更すると、参照するオブジェクトを変更したり、出力順番を変更することができます。

• Lead以外のオブジェクトから取得したい。

  本サンプルシナリオではLeadオブジェクトからデータを取得しています。
  異なるオブジェクトからデータを取得したい場合、変数「header_tail」の値を修正してください。

  現在の設定：「+from+Lead+Order+by+ID」    ← LeadからID順にデータ取得   
  参照先変更：「+from+Account+Order+by+ID」 ← AccountからID順にデータ取得   

  Lead以外のオブジェクトからデータを取得する場合、入力ファイルのヘッダも新しいオブジェクトに沿ったものに変更します。

• 取得時の順番を変更したい。

  本サンプルシナリオではID順にデータを取得しています。
  異なる順番でデータを取得したい場合、変数「header_tail」の値を修正してください。

  現在の設定：「+from+Lead+Order+by+ID」      ← LeadからID順にデータ取得   
  取得順変更：「+from+Lead+Order+by+LastName」← LeadからLastName順にデータ取得    

Salesforceから送られる情報(受信用データファイル)

RESTful API実行.ums5 ライブラリ呼び出し時、受信したデータはJSON形式で保存されます。
この受信データは、入力ファイルと同じディレクトリに「入力ファイル名.json」の名称で出力されます。 「JSONファイルの解析に失敗しました。」などのエラーが発生した場合、この出力ファイルを参照してください。

JSONファイルの解析とExcelへの保存

本サンプルシナリオは「SalesForce_Leadデータ取得用_JSON→EXCEL出力」処理で、JSONファイルの中身を解析してデータを取得し、Excelに格納する処理を行っています。 内部では、以下の処理を実施しています。

1. Excelファイルを開く。
2. JSONファイルをUTF8として読み込む。
3. 読み出したデータをJSONとして解析（具体的には、HtmlFile オブジェクトを使用して、JSONParse します）。
4. パースされたJSONのオブジェクトから、Excelで指定されたデータ名のデータを取得。
5. 取得したデータをExcelのセルに設定。

SalesForceの取得データ JSON出力例

{  
  "totalSize" : 2,                        取得データ数  
  "done" : true,                      実施結果  
  "records" : [ {                     取得したレコードの情報（配列）  
    "attributes" : {                      １レコード目の取得データの属性  
      "type" : "Lead",                    取得データの所属  
       "url" : "/services/data/v44.0/sobjects/Lead/AAAAAAAAAAAAAAAAAA"  取得データのURL（直接参照する場合のURL）  
    },  
    "Id" : "AAAAAAAAAAAAAAAAAA",          取得データ１項目  
    :  
    "Status" : "Closed - Converted"       取得データ最終項目  
  }, {                                    ２レコード目  
    :  
  } ]  
}  

ここで扱うJSONファイルの形式は、Salesforce固有のものを想定しています。
JSONファイルの形式が変わる場合、JSONファイルの形式に合わせて、処理を作成してください。

Excelへの受信データ格納

本サンプルシナリオでは、取得した文字列が数値、日付とみなされる文字列だった場合、また、文字列先頭に「=」が格納されていた場合は、Excelによって変換が行われるのを防ぐため、セルのフォーマットを文字列としてExcelファイルに格納しています。

以下は、数値、日付、先頭が=のデータの場合、セルの書式を文字列にする処理に該当する部分です。

  if IsNumeric(detail) or IsDate(detail) or InStr(detail, "=") = 1  Then  
     worksheet.Cells(xlsx_lineNo + i,1 + j).NumberFormatLocal  = "@"  
  End If  
  worksheet.Cells(xlsx_lineNo + i,1 + j).value = detail

他の文字列の書式を変更したい場合、また、項目ごとに設定を変更したい場合は、条件文、設定書式を見直す必要があります。

変更履歴