2024.03.13

Salesforceメタデータの操作入門：レポート・レポートフォルダ編

R.T

目次

Just a moment... (31668)

via pixabay.com

はじめに

皆さんはSalesforce開発の中でメタデータを活用していますか？
Salesforceメタデータは、うまく活用すれば「よりフレキシブルなリリースが可能になる」「環境間の比較ができる」などなどのメリットがあり、非常に便利です。

一方で、扱いに慣れないうちはメタデータの取得やデプロイがなかなかうまくいかず、フラストレーションがたまる……なんてことも、よくあるのではないでしょうか。

メタデータには種類もたくさんあり、それぞれに操作の際注意すべき点が存在します。
今回はその中からレポートに関するものについて、備忘も兼ねてまとめてみたいと思います。

おさらい -Salesforceメタデータについて-

Salesforceメタデータ

さて、本題に入る前に、簡単にSalesforceのメタデータについておさらいしておきましょう。

Salesforceのメタデータは、その組織のさまざまな設定を記述したものです。
例えば、オブジェクトのメタデータには、

  • オブジェクトのAPI参照名

  • Name項目の名称

  • Name項目の型 …etc.

などなどがXML形式で記載されています。

普段設定画面で見ている内容がテキストで表現されているため、以下のような場面で非常に有用です。

  • 複数組織同士の設定差異を比較する

  • 複数箇所の設定を一括で変更する

  • 項目名などの設定変更の影響を調査する …etc.

メタデータの取得・リリース

メタデータは、Salesforce CLIのsfコマンドやVisual Studio Codeの拡張機能などを利用して操作することができます。
※sfdxコマンドのサポートは終了しています。

メタデータの取得、リリースについてはこのTech Blogでも以下の記事などで紹介していますので、今回は詳細な解説は割愛します。
メタデータの比較とリリース - TerraSkyBase | テラスカイを支える人とテクノロジーの情報を発信する基地局

package.xmlについて

package.xmlは、メタデータの種別、名称、APIバージョンなどがXML形式で記載されるマニフェストファイルです。
Salesforce CLIを利用したメタデータの取得、デプロイなどの際には、必ずと言っていいほどこのpackage.xmlが登場します。
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<!-- package.xmlサンプル -->
    <types>
        <members>Account</members>
        <members>Contact</members>
        <name>CustomObject</name>
    </types>
    <types>
        <members>AccountTriggerHandler</members>
        <name>ApexClass</name>
    </types>
    <version>60.0</version>
</Package>
package.xml
package.xmlでは以下の要素を記載することによって、操作するメタデータを具体的に指定することができます。

  • <types>：
    この要素が1つのメタデータ種別のまとまりを示します。
    この要素の内部に以下の2つの要素を記載して、より具体的にメタデータの詳細を指定します。

  • <name>：
    <types>要素の内部に必ず1つ記載します。
    操作するメタデータコンポーネント種別（例：CustomObject）を指定します。

  • <members>：
    <types>要素の内部に複数列挙する形で記載できます。
    操作するメタデータコンポーネント種別（例：CustomObject）を指定します。
    操作したいコンポーネントの名称をAPI参照名で記載します（例：Contact）。
    この<members>要素の記載により、<name>要素で指定したコンポーネント種別の中から、具体的にどのコンポーネントを操作するか特定することができます。


これらを踏まえて上記のpackage.xmlを再度見てみると、ここでは

  • オブジェクト：取引先(Account)、取引先責任者(Contact)
  • Apexクラス：AccountTriggerHandler

を指定していることが読み取れます。
またその他にも、package.xmlには使用するAPIバージョンも記載されます。

レポートのメタデータについて

レポートのメタデータ

レポートのメタデータではレポートのAPI参照名がメタデータファイル名として表現されているほか、メタデータ内の各種タグで、表示ラベル名、行・列の定義、レポートタイプ、検索条件、小計等の表示有無などなど、レポートの設定一般の情報が記載されています。
詳細：Report | メタデータ API 開発者ガイド
<?xml version="1.0" encoding="UTF-8"?>
<Report xmlns="http://soap.sforce.com/2006/04/metadata">
<!-- レポートのメタデータサンプル -->
    <columns> 
        <field>SALUTATION</field>
    </columns>
    <columns>
        <field>FIRST_NAME</field>
    </columns>
    <columns>
        <field>LAST_NAME</field>
    </columns>
    <format>Tabular</format>
    <name>ContactList</name>
    <params>
        <name>co</name>
        <value>1</value>
    </params>
    <reportType>ContactList</reportType>
    <scope>my</scope>
    <showDetails>true</showDetails>
    <showGrandTotal>true</showGrandTotal>
    <showSubTotals>true</showSubTotals>
    <timeFrameFilter>
        <dateColumn>CREATED_DATE</dateColumn>
        <interval>INTERVAL_CUSTOM</interval>
        <startDate>2024-02-13</startDate>
    </timeFrameFilter>
</Report>
ContactList.report

レポートのメタデータ操作

フォルダ内のレポート取得

では早速、Salesforce CLIを使用してこのレポートのメタデータ取得・リリースを実施してみましょう。
他のメタデータ取得の際もそうであるように、package.xmlの<name>、<members>で取得したい内容を記載し、メタデータ取得用のコマンドでそのpackage.xmlのパスを指定することでレポートのメタデータが取得可能です。
具体的に言うと、package.xmlでは、

  • <name>：Report

  • <members>：対象レポートのAPI参照名

    上記を指定することになります。

    ここまでは非常に単純ですが、取得対象のレポートがフォルダ内に配置されている場合にはもう少し注意が必要です。

    例えば、上の画像のように、

    • Folder1\Folder2

    というフォルダ階層が存在し、Folder2の配下に

    • ContactList

    という、取引先と取引先責任者のレポートが配置されている場合を例にとってみます。
    この「ContactList」レポートをpackage.xmlで指定してメタデータを取得する場合、以下のように単純に<members>タグで「ContactList」を指定するだけでは正常に取得できません。
    <?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<!-- レポートの名称のみを指定したpackage.xml -->
    <types>
        <members>ContactList</members>
        <name>Report</name>
    </types>
    <version>60.0</version>
</Package>
    package.xml

    試しに、<members>タグで取得対象レポートのAPI参照名のみを指定した上記のpackage.xmlを、以下のようにメタデータ取得用のコマンド内で指定して、レポートのメタデータ取得を試してみます。

    • sf project retrieve start --manifest [package.xmlのパス] --target-metadata-dir [取得したメタデータの出力先] -o [設定した組織のエイリアス/ユーザ名]

    すると上の画像のように、レポートのメタデータは取得できずに、package.xmlのみが含まれるunpackaged.zipフォルダが取得される結果となってしまいました。
    ※sfdxコマンドを使用している場合は、「Entity of type 'Report' named 'レポート名' cannot be found」のようなエラーが発生します。

    これは、package.xmlでフォルダ階層が表現されておらず、対象のレポートが適切に指定されていない状態になってしまっているためです。
    この問題を解消するためには、package.xmlでレポートを指定する際に

    ・最上位フォルダ/.../レポート

    のように、最上位フォルダからレポートまでのパスをスラッシュ区切りで記載する必要があります。
    ※レポートのメタデータを取得することのみが目的であれば、1つ上の階層のフォルダからのパスの記載でも問題なく取得できます。ただし、そのpackage.xmlは後述のようにリリース時には使用できません。

    以上を踏まえて修正すると、今回Folder2配下のContactListレポートのメタデータを取得するためのpackage.xmlは以下の通りになります。
    <?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<!-- レポートのパスを表現したpackage.xml -->
    <types>
        <members>Folder1/Folder2/ContactList</members>
        <name>Report</name>
    </types>
    <version>60.0</version>
</Package>
    package.xml
    こちらのpackage.xmlを指定して再度retrieveコマンドを実行すると……

    今度はレポートのメタデータファイルを取得することができました！

    レポートフォルダのメタデータ操作

    レポートのリリース ーフォルダの落とし穴ー


    さて次に、上で取得したようなフォルダ配下のレポートを、メタデータを使用して別環境にリリースすることを考えてみます。

    • sf project deploy start --metadata-dir [リリースするメタデータのパス] --target-org [設定した組織のエイリアス/ユーザ名]

    上記のコマンドで、上の項で取得したメタデータフォルダのパスを指定し、取得元とは異なる環境へレポートのリリースを行います。
    するとここでもうひとつ問題が発生します。

    「ContactList Cannot find folder:Folder2」というエラーが出てしまいました。
    これは、ContactListレポートが配置されている上位フォルダ（ここでは「Folder2」）がデプロイ先の環境に存在しないために発生しているエラーです。
    ※設定画面の「リリース状況」からも同様のエラーが確認できます。

    先ほど取得・リリースした以下のメタデータのフォルダを見てみると、以下の通り、一見フォルダ階層がメタデータにも反映されているように見えます。

    しかし、この状態ではフォルダ自体のメタデータは取得できていません。
    結果として、リリース先の環境には「Folder1」、「Folder2」のレポートフォルダがリリースされておらず、存在しないフォルダへ「ContactList」レポートの配置を指定する形になってしまったため、エラーが発生したわけです。
    変更セットでも、ついついレポートフォルダを入れ忘れてエラーが出ること、ありますよね……

    この問題を解決するためには、リリース先の環境にも同名のフォルダを作成しておく必要がありますね。
    もちろんリリース先の環境に手動でレポートフォルダを作成することもできますが、せっかくなのでレポートフォルダのメタデータも一緒に取得し、リリースしてみましょう。

    レポートフォルダのメタデータ取得

    レポートフォルダのメタデータを取得する際は、

    • <name>タグ：Report
    • <members>タグ：レポートフォルダのAPI参照名
    をそれぞれ指定します。
    つまり、通常のレポートを指定している<types>タグの中に、レポートと並べてフォルダも指定する形になります。

    また、フォルダに階層がある場合はレポートと同様注意が必要です。
    記載方法によっては、メタデータがうまく取得できない、取得したメタデータのリリースがうまくいかない、などの問題が発生します。

    以下に、レポートフォルダのメタデータを正常に取得できるpackage.xmlの記載方法を2つご紹介します。

    1. レポートフォルダ・レポートともに完全なパスを記載
      ⇒フォルダ階層やレポートの配置をすべて表現するため、記述に少し手間がかかります。
      ⇒リリースの際にそのまま使用してもエラーが発生しません。
      ⇒フォルダ配下のレポートを同時に取得しない場合や、レポートのパスを完全に記載しない場合、フォルダのメタデータがうまく取得できない場合があります。
    2. レポートフォルダ：フォルダ名単体、レポート：最低でも1つ上のフォルダからのパスを記載
      ⇒完全なパスを記述しない分、簡単な記載になります。
      ⇒フォルダ・レポートのパスの記載が不完全であるため、こちらの方法で記載したpackage.xmlを使用してメタデータを取得しそのままリリースに使用すると、エラーが発生します。
    <?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<!-- 1.レポートフォルダ・レポートともに完全なパスを記載 -->
    <types>
        <members>Folder1</members> <!-- Folder1の指定 -->
        <members>Folder1/Folder2</members> <!-- Folder1配下のFolder2の指定 -->
        <members>Folder1/Folder2/ContactList</members> <!-- Folder2配下のレポートContactListの指定 ※必須 -->
        <!-- 以下のようなレポートの指定は不可。Folder2のメタデータが取得されない -->
        <!-- <members>Folder2/ContactList</members> -->
        <name>Report</name>
    </types>
    <version>60.0</version>
</Package>
    package.xml
    <?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<!-- 2.レポートフォルダ：フォルダ名単体、レポート：1つ上のフォルダからのパスを記載 -->
    <types>
        <members>Folder1</members> <!-- Folder1の指定 -->
        <members>Folder2</members> <!-- Folder1配下のFolder2の指定 -->
        <members>Folder2/ContactList</members> <!-- Folder2配下のレポートContactListの指定 -->
        <!-- 以下のようにレポートの完全なパスを指定してもよい -->
        <!-- <members>Folder1/Folder2/ContactList</members> -->
        <name>Report</name>
    </types>
    <version>60.0</version>
</Package>
    package.xml
    さて、今回は取得したメタデータのリリースも実行したいため、上記の1の方法を使用します。
    修正したpackage.xmlを指定し、改めてメタデータを取得してみると……

    今度はレポートフォルダ自体のメタデータファイルも一緒に取得できています！

    レポートフォルダのメタデータ

    上で取得したレポートフォルダのメタデータにはフォルダの表示ラベル名や共有設定などの情報が記述されています。
    ※参考：Folder | メタデータ API 開発者ガイド

    これを一緒にリリースすることで、レポートと一緒にレポートフォルダもリリース先環境に反映され、親フォルダの欠如によるエラーを回避することができます。

    また、メタデータを使用してレポートフォルダを別環境にリリースする際には、以下の点にも注意が必要です。

    • 共有設定について
      最上位のレポートフォルダのメタデータでは、sharedToタグ、sharedToTypeタグで共有設定の内容が記述されます。
      ※Salesforceでは、下位のフォルダには最上位フォルダの共有設定が反映されます。そのため、下位フォルダのメタデータには共有設定に関する記述はありません。

      このsharedToタグで記載しているユーザ名などがリリース先の環境に存在しないものである場合、取得したメタデータをそのままリリースすると「 In field: sharedTo - no User named [ユーザ名] found」のようなエラーが発生します。
      最上位のフォルダをリリースする際はこのエラーを回避するために、あらかじめリリース対象のメタデータを確認し、リリース先に存在しない値が含まれていた場合は修正しておく必要があります。

    レポート・レポートフォルダのリリース


    さて、ここまでで取得したFolder1、Folder2、ContactListレポートのメタデータをまとめてリリースしていきましょう。
    まず、取得したメタデータのzipファイルを展開し、フォルダ内に以下が含まれていることを確認しておきます。

    • 対象レポートの親レポートフォルダ（Folder1、Folder2）
    • 対象レポートのメタデータファイル（ContactList）
    • レポート・レポートフォルダを指定したpackage.xml
    ※リリース先環境に親レポートフォルダが存在する場合は、親レポートフォルダのメタデータファイルは不要です

    また、エラーの発生を防ぐため、以下も改めて確認しておきましょう。

    • package.xmlでレポート・レポートフォルダの階層関係が最上位から正しく記述されている
    • 各メタデータに、リリース先環境に存在しない値（項目、ユーザー名など）が含まれていない

    しっかり確認できたら、deployコマンドを使用してメタデータが格納されているフォルダを指定し、リリースを実施します。

    • sf project deploy start --metadata-dir [リリースするメタデータのパス] --target-org [設定した組織のエイリアス/ユーザ名]

    2つのフォルダとレポートのリリースが成功しました！

    おわりに

    今回はレポート・レポートフォルダのメタデータ操作について確認してきました。
    特にレポートの場合は、フォルダ階層の関係でメタデータ操作時に注意すべき点が多くなっています。
    またこのような注意点の多くはダッシュボードやClassicメールテンプレートなど、フォルダの存在する設定に共通していますので、覚えておくとよいかもしれません。

    最後までご覧いただきありがとうございました。
    この他にもメタデータを扱う際にはつまずきやすいポイントがたくさんありますので、またの機会にご紹介していきたいと思います。

    参考

    package.xml マニフェストファイルのサンプル |メタデータ API 開発者ガイド
    ステップ 2: Package.xml マニフェストを作成する |メタデータ API 開発者ガイド
    Report | メタデータ API 開発者ガイド
    Folder | メタデータ API 開発者ガイド
    74 件
      　
    • banner
    • banner

    関連する記事

    関連するキーワード