Integrasi dengan Salesforce (SFDC)

Halaman ini menjelaskan langkah-langkah integrasi untuk workload operasional Salesforce (SFDC) di Cortex Framework Data Foundation. Cortex Framework mengintegrasikan data dari Salesforce dengan pipeline Dataflow hingga BigQuery, sementara Managed Service untuk Apache Airflow menjadwalkan dan memantau pipeline Dataflow ini untuk mendapatkan insight dari data Anda.

File konfigurasi

config.json File di repositori Cortex Framework Data Foundation mengonfigurasi setelan yang diperlukan untuk mentransfer data dari sumber data mana pun, termasuk Salesforce. File ini berisi parameter berikut untuk workload operasional Salesforce:

    "SFDC": {
        "deployCDC": true,
        "createMappingViews": true,
        "createPlaceholders": true,
        "datasets": {
            "cdc": "",
            "raw": "",
            "reporting": "REPORTING_SFDC"
        }
    }

Tabel berikut menjelaskan nilai untuk setiap parameter operasional SFDC:

Parameter Artinya Nilai Default Deskripsi
SFDC.deployCDC Deploy CDC true Menghasilkan skrip pemrosesan CDC untuk menjalankan sebagai DAG di Managed Service untuk Apache Airflow. Lihat dokumentasi untuk berbagai opsi penyerapan untuk Salesforce Sales Cloud.
SFDC.createMappingViews Membuat tampilan pemetaan true DAG yang disediakan untuk mengambil data baru dari Salesforce API memperbarui data di landing. Nilai ini ditetapkan ke true menghasilkan tampilan di set data yang diproses CDC untuk mengekspos tabel dengan "versi kebenaran terbaru" dari set data Mentah. Jika ditetapkan ke false dan SFDC.deployCDC adalah true, DAG akan dibuat dengan pemrosesan Pengambilan Data Perubahan (CDC) berdasarkan SystemModstamp. Lihat detail tentang pemrosesan CDC untuk Salesforce.
SFDC.createPlaceholders Membuat Placeholder true Membuat tabel placeholder kosong jika tidak dibuat oleh proses penyerapan untuk memungkinkan deployment pelaporan downstream dieksekusi tanpa kegagalan.
SFDC.datasets.raw Set data landing mentah - Digunakan oleh proses CDC, di sinilah alat replikasi menempatkan data dari Salesforce. Jika menggunakan data pengujian, buat set data kosong.
SFDC.datasets.cdc Set Data yang Diproses CDC - Set data yang berfungsi sebagai sumber untuk tampilan pelaporan, dan target untuk DAG yang diproses data. Jika menggunakan data pengujian, buat set data kosong.
SFDC.datasets.reporting Set Data Pelaporan SFDC "REPORTING_SFDC" Nama set data yang dapat diakses oleh pengguna akhir untuk pelaporan, tempat tampilan dan tabel yang ditampilkan kepada pengguna di-deploy.
SFDC.currencies Memfilter mata uang [ "USD" ] Jika Anda tidak menggunakan data pengujian, masukkan satu mata uang (misalnya, [ "USD" ]) atau beberapa mata uang (misalnya,[ "USD", "CAD" ]) yang relevan dengan bisnis Anda. Nilai ini digunakan untuk mengganti placeholder dalam SQL di model analisis jika tersedia.

Model Data

Bagian ini menjelaskan Model Data Salesforce (SFDC) menggunakan Diagram Hubungan Entitas (ERD).

Diagram Hubungan Entity untuk SFDC

Gambar 2. Salesforce (SFDC): Diagram Hubungan Entitas.

Tampilan dasar

Ini adalah objek biru di ERD dan merupakan tampilan pada tabel CDC tanpa transformasi selain beberapa alias nama kolom. Lihat skrip di src/SFDC/src/reporting/ddls.

Tampilan pelaporan

Ini adalah objek hijau di ERD dan berisi atribut dimensi yang relevan yang digunakan oleh tabel pelaporan. Lihat skrip di src/SFDC/src/reporting/ddls.

Persyaratan data Salesforce

Bagian ini menguraikan spesifikasi tentang cara data Salesforce Anda harus disusun untuk digunakan dengan Cortex Framework.

  • Struktur Tabel:
    • Penamaan: Nama tabel menggunakan snake_case (kata huruf kecil yang dipisahkan oleh garis bawah) dan berbentuk jamak. Misalnya, some_objects.
    • Jenis Data: Kolom mempertahankan jenis data yang sama seperti yang direpresentasikan dalam Salesforce.
    • Keterbacaan: Beberapa nama kolom mungkin sedikit disesuaikan untuk kejelasan yang lebih baik di lapisan pelaporan.
  • Tabel Kosong dan Deployment: Tabel yang diperlukan yang tidak ada dalam set data mentah akan otomatis dibuat sebagai tabel kosong selama proses deployment. Hal ini memastikan eksekusi langkah deployment CDC berjalan lancar.
  • Persyaratan CDC: Kolom Id dan SystemModstamp sangat penting agar skrip CDC dapat melacak perubahan dalam data Anda. Kolom tersebut dapat memiliki nama yang sama persis atau berbeda. Skrip pemrosesan Mentah yang disediakan mengambil kolom ini secara otomatis dari API dan memperbarui tabel replikasi target.
    • Id: Bertindak sebagai ID unik untuk setiap data.
    • SystemModstamp: Kolom ini menyimpan stempel waktu yang menunjukkan kapan terakhir kali data diubah.
  • Skrip Pemrosesan Mentah:Skrip pemrosesan Mentah yang disediakan tidak memerlukan pemrosesan tambahan (CDC). Perilaku ini ditetapkan selama deployment secara default.

Tabel sumber untuk Konversi Mata Uang

Salesforce memungkinkan Anda mengelola mata uang dengan dua cara:

  • Dasar: Ini adalah setelan default, tempat semua data menggunakan satu mata uang.
  • Lanjutan: Mengonversi antara beberapa mata uang berdasarkan nilai tukar (memerlukan pengaktifan Pengelolaan Mata Uang Lanjutan).

Jika Anda menggunakan Pengelolaan Mata Uang Lanjutan, Salesforce akan menggunakan dua tabel khusus:

  • CurrencyTypes: Tabel ini menyimpan informasi tentang berbagai mata uang yang Anda gunakan (misalnya, USD, EUR, dll.).
  • DatedConversionRates: Tabel ini menyimpan nilai tukar antara mata uang dari waktu ke waktu.

Cortex Framework mengharapkan tabel ini ada jika Anda menggunakan pengelolaan mata uang lanjutan. Jika Anda tidak menggunakan pengelolaan mata uang lanjutan, Anda dapat menghapus entri yang terkait dengan tabel ini dari file konfigurasi (src/SFDC/config/ingestion_settings.yaml). Langkah ini mencegah upaya yang tidak perlu untuk mengekstrak data dari tabel yang tidak ada.

Memuat data SFDC ke BigQuery

Cortex Framework menyediakan solusi replikasi berdasarkan skrip Python yang dijadwalkan di Apache Airflow dan Salesforce Bulk API 2.0. Skrip Python ini dapat diadaptasi dan dijadwalkan di alat pilihan Anda. Untuk mengetahui informasi selengkapnya, lihat Modul ekstraksi SFDC.

Cortex Framework juga menawarkan tiga metode berbeda untuk mengintegrasikan data Anda, bergantung pada asal data dan cara pengelolaannya:

  1. Panggilan API: Opsi ini untuk data yang dapat diakses langsung melalui API. Cortex Framework dapat memanggil API, mengambil data, dan menyimpannya dalam set data "Mentah" di BigQuery. Jika ada data yang sudah ada dalam set data, Cortex Framework dapat memperbaruinya dengan data baru.
  2. Tampilan Pemetaan Struktur: Metode ini berguna jika Anda sudah memuat data ke BigQuery melalui alat lain, tetapi struktur data tidak cocok dengan yang diperlukan Cortex Framework. Cortex Framework menggunakan "tampilan" (seperti tabel virtual) untuk menerjemahkan struktur data yang ada ke dalam format yang diharapkan oleh fitur pelaporan Cortex Framework.

  3. Skrip Pemrosesan CDC (Pengambilan Data Perubahan): Opsi ini dirancang khusus untuk data yang terus berubah. Skrip CDC melacak perubahan ini dan memperbarui data di BigQuery. Skrip ini mengandalkan dua kolom khusus dalam data Anda:

    • Id: ID unik untuk setiap data.
    • SystemModstamp: stempel waktu yang menunjukkan kapan data diubah.

    Jika data Anda tidak memiliki nama yang sama persis, skrip dapat disesuaikan untuk mengenalinya dengan nama yang berbeda. Anda juga dapat menambahkan kolom kustom ke skema data selama proses ini. Misalnya, tabel sumber dengan data objek Akun harus memiliki kolom Id dan SystemModstamp asli. Jika kolom ini memiliki nama yang berbeda, file src/SFDC/src/table_schema/accounts.csv harus diperbarui dengan nama kolom Id yang dipetakan ke AccountId dan kolom stempel waktu modifikasi sistem apa pun yang dipetakan ke SystemModstamp. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi SystemModStamp.

Jika Anda telah memuat data melalui alat lain (dan data tersebut terus diperbarui), Cortex masih dapat menggunakannya. Skrip CDC dilengkapi dengan file pemetaan yang dapat menerjemahkan struktur data yang ada ke dalam format yang diperlukan Cortex Framework. Anda bahkan dapat menambahkan kolom kustom ke data selama proses ini.

Mengonfigurasi integrasi API dan CDC

Untuk memasukkan data Salesforce ke BigQuery, Anda dapat menggunakan cara berikut:

  1. Skrip Cortex untuk panggilan API: menyediakan skrip replikasi untuk Salesforce atau alat replikasi data pilihan Anda.Kuncinya adalah data yang Anda masukkan harus terlihat sama seperti jika berasal dari Salesforce API.
  2. Alat replikasi dan selalu tambahkan : Jika Anda menggunakan alat untuk replikasi, cara ini adalah untuk alat yang dapat menambahkan data baru (_appendalways_pattern) atau memperbarui data yang ada.
  3. Alat replikasi dan tambahkan data baru: Jika alat tidak memperbarui data dan mereplikasi perubahan apa pun sebagai data baru ke dalam tabel target (Mentah), Cortex Data Foundation akan memberikan opsi untuk membuat skrip pemrosesan CDC. Untuk mengetahui informasi selengkapnya, lihat Proses CDC.

Workload Salesforce: Opsi Integrasi Data

Gambar 1. Workload Salesforce: opsi integrasi data.

Untuk memastikan data Anda cocok dengan yang diharapkan Cortex Framework, Anda dapat menyesuaikan konfigurasi pemetaan untuk memetakan alat replikasi atau skema yang ada. Tindakan ini akan menghasilkan tampilan pemetaan yang kompatibel dengan struktur yang diharapkan oleh Cortex Framework Data Foundation.

Gunakan file ingestion_settings.yaml untuk mengonfigurasi pembuatan skrip untuk memanggil Salesforce API dan mereplikasi data ke dalam set data Mentah (bagian salesforce_to_raw_tables) dan pembuatan skrip untuk memproses perubahan yang masuk ke dalam set data Mentah dan ke dalam set data yang diproses CDC (bagian raw_to_cdc_tables).

Secara default, skrip yang disediakan untuk membaca dari API memperbarui perubahan ke dalam set data Mentah, sehingga skrip pemrosesan CDC tidak diperlukan, dan tampilan pemetaan untuk menyelaraskan skema sumber dengan skema yang diharapkan akan dibuat.

Pembuatan skrip pemrosesan CDC tidak dijalankan jika SFDC.createMappingViews=true di config.json (perilaku default). Jika skrip CDC diperlukan, tetapkan SFDC.createMappingViews=false. Langkah kedua ini juga memungkinkan pemetaan antara skema sumber ke dalam skema yang diperlukan seperti yang diperlukan oleh Cortex Framework Data Foundation.

Contoh file konfigurasi setting.yaml berikut mengilustrasikan pembuatan tampilan pemetaan saat alat replikasi memperbarui data langsung ke dalam set data yang direplikasi, seperti yang diilustrasikan dalam option 3 (yaitu, tidak ada CDC yang diperlukan, hanya pemetaan ulang tabel dan nama kolom). Karena tidak ada CDC yang diperlukan, opsi ini akan dieksekusi selama parameter SFDC.createMappingViews dalam file config.json tetap true.

  salesforce_to_raw_tables:
  - base_table: accounts
    raw_table: Accounts
    api_name: Account
      load_frequency: "@daily"
  - base_table: cases
    raw_table: cases2
    api_name: Case
    load_frequency: "@daily"

Dalam contoh ini, menghapus konfigurasi untuk tabel dasar atau semuanya dari bagian akan melewati pembuatan DAG tabel dasar tersebut atau seluruh bagian, seperti yang diilustrasikan untuk salesforce_to_raw_tables. Untuk skenario ini, menetapkan parameter deployCDC : False memiliki efek yang sama, karena tidak ada skrip pemrosesan CDC yang perlu dibuat.

Pemetaan data

Anda harus memetakan kolom data yang masuk ke format yang diharapkan oleh Cortex Data Foundation. Misalnya, kolom bernama unicornId dari sistem data sumber Anda harus diganti namanya dan dikenali sebagai AccountId (dengan jenis data string) dalam Cortex Data Foundation:

  • Kolom Sumber: unicornId (nama yang digunakan dalam sistem sumber)
  • Kolom Cortex: AccountId (nama yang diharapkan oleh Cortex)
  • Jenis Data: String (jenis data yang diharapkan oleh Cortex)

Memetakan Kolom Polimorfik

Cortex Framework Data Foundation mendukung pemetaan kolom polimorfik, yaitu kolom yang namanya dapat bervariasi tetapi strukturnya tetap konsisten. Nama jenis kolom polimorfik (misalnya, Who.Type) dapat direplikasi dengan menambahkan item [Field Name]_Type dalam file CSV pemetaan masing-masing:src/SFDC/src/table_schema/tasks.csv. Misalnya, jika Anda memerlukan kolom Who.Type objek Task untuk direplikasi, tambahkan baris Who_Type,Who_Type,STRING. Tindakan ini akan menentukan kolom baru bernama Who.Type yang dipetakan ke dirinya sendiri (mempertahankan nama yang sama) dan memiliki jenis data string.

Mengubah Template DAG

Anda mungkin perlu menyesuaikan template DAG untuk CDC atau untuk pemrosesan data Mentah seperti yang diperlukan oleh instance Airflow atau Managed Airflow Anda. Untuk mengetahui informasi selengkapnya, lihat Mengumpulkan setelan Managed Airflow.

Jika Anda tidak memerlukan CDC atau pembuatan data mentah dari panggilan API, tetapkan deployCDC=false. Atau, Anda dapat menghapus konten bagian di ingestion_settings.yaml. Jika struktur data diketahui konsisten dengan yang diharapkan oleh Cortex Framework Data Foundation, Anda dapat melewati pembuatan tampilan pemetaan dengan menetapkan SFDC.createMappingViews=false.

Mengonfigurasi modul ekstraksi

Bagian ini menyajikan langkah-langkah untuk menggunakan modul ekstraksi Salesforce ke BigQuery yang disediakan oleh Data Foundation. Persyaratan dan alur Anda mungkin berbeda-beda bergantung pada sistem dan konfigurasi yang ada. Anda dapat menggunakan alat lain yang tersedia.

Menyiapkan kredensial dan Aplikasi terhubung

Login sebagai administrator ke instance Salesforce Anda untuk menyelesaikan langkah-langkah berikut:

  1. Buat atau identifikasi profil di Salesforce yang memenuhi persyaratan berikut:
    1. Permission for Apex REST Services and API Enabled diberikan di bagian System Permissions.
    2. Izin View All diberikan untuk semua objek yang ingin Anda replikasi. Misalnya, Akun dan Kasus. Periksa batasan atau masalah dengan administrator keamanan Anda.
    3. Tidak ada izin yang diberikan untuk terkait login antarmuka pengguna, seperti Salesforce Anywhere di Lightning Experience, Salesforce Anywhere di Seluler, Pengguna Lightning Experience,dan Pengkaptenan Pengguna. Periksa batasan atau masalah dengan administrator keamanan Anda.
  2. Buat atau gunakan identifikasi pengguna yang ada di Salesforce. Anda harus mengetahui nama pengguna, sandi, dan token keamanan pengguna. Pertimbangkan hal berikut:
    • Idealnya, ini adalah pengguna yang khusus untuk menjalankan replikasi ini.
    • Pengguna harus ditetapkan ke profil yang telah Anda buat atau identifikasi di langkah 1.
    • Anda dapat melihat Nama Pengguna dan mereset Sandi di sini.
    • Anda dapat mereset token keamanan jika tidak memilikinya dan tidak digunakan oleh proses lain.
  3. Buat Aplikasi Terhubung. Aplikasi ini adalah satu-satunya saluran komunikasi untuk membuat koneksi ke Salesforce dari dunia eksternal dengan bantuan profil, Salesforce API, kredensial pengguna standar, dan token keamanannya.
    1. Ikuti petunjuk untuk mengaktifkan Setelan OAuth untuk Integrasi API.
    2. Pastikan Require Secret for Web Server Flow dan Require Secretfor Refresh Token Flow diaktifkan di bagian API (Enabled OAuth Settings).
    3. Lihat dokumentasi tentang cara mendapatkan kunci konsumen (yang nantinya akan digunakan sebagai Client ID Anda). Hubungi administrator keamanan Anda jika ada masalah atau batasan.
  4. Tetapkan Aplikasi Terhubung Anda ke profil yang dibuat.
    1. Pilih Setup dari kanan atas layar utama Salesforce.
    2. Di kotak Quick Find, masukkan profile, lalu pilih Profile. Cari profil yang dibuat pada langkah 1.
    3. Buka profil.
    4. Klik link Assigned Connected Apps.
    5. Klik Edit.
    6. Tambahkan Aplikasi Terhubung yang baru dibuat.
    7. Klik tombol Save.

Menyiapkan Secret Manager

Konfigurasi Secret Manager untuk menyimpan detail koneksi. Modul Salesforce ke BigQuery mengandalkan Secret Manager untuk menyimpan kredensial yang diperlukan untuk terhubung ke Salesforce dan BigQuery dengan aman. Pendekatan ini menghindari pemaparan informasi sensitif seperti sandi langsung dalam kode atau file konfigurasi Anda, sehingga meningkatkan keamanan.

Buat secret dengan spesifikasi berikut. Untuk mengetahui petunjuk selengkapnya, lihat Membuat secret.

  • Nama Secret: airflow-connections-salesforce-conn

  • Nilai Secret:

    http://USERNAME:PASSWORD@https%3A%2F%2FINSTANCE_NAME.lightning.force.com?client_id=CLIENT_ID&security_token=SECRET_TOKEN`

    Ganti kode berikut:

    • USERNAME dengan nama pengguna Anda.
    • PASSWORD dengan sandi Anda.
    • INSTANCE_NAME dengan nama instance.
    • CLIENT_ID dengan ID klien Anda.
    • SECRET_TOKEN dengan token rahasia Anda.

Untuk mengetahui informasi selengkapnya, lihat cara menemukan nama instance Anda.

Library Managed Airflow untuk replikasi

Untuk menjalankan skrip Python di DAG yang disediakan oleh Cortex Framework Data Foundation, Anda harus menginstal beberapa dependensi. Untuk Airflow versi 1.10, ikuti dokumentasi Menginstal dependensi Python untuk Managed Service untuk Apache Airflow 1 untuk menginstal paket berikut, secara berurutan:

tableauserverclient==0.17
apache-airflow-backport-providers-salesforce==2021.3.3

Untuk Airflow versi 2.x, lihat dokumentasi Menginstal dependensi Python untuk Managed Service untuk Apache Airflow 2 untuk menginstal apache-airflow-providers-salesforce~=5.2.0.

Gunakan perintah berikut untuk menginstal setiap paket yang diperlukan:

  gcloud composer environments update ENVIRONMENT_NAME \
  --location LOCATION \
   --update-pypi-package PACKAGE_NAME EXTRAS_AND_VERSION

Ganti kode berikut:

  • ENVIRONMENT_NAME dengan nama lingkungan yang ditetapkan.
  • LOCATION dengan lokasi.
  • PACKAGE_NAME dengan nama paket yang dipilih.
  • EXTRAS_AND_VERSION dengan spesifikasi tambahan dan versi.

Perintah berikut adalah contoh penginstalan paket yang diperlukan:

gcloud composer environments update my-composer-instance \
  --location us-central1 \
  --update-pypi-package apache-airflow-backport-providers-salesforce>=2021.3.3

Mengaktifkan Secret Manager sebagai backend

Aktifkan Google Secret Manager sebagai backend keamanan. Langkah ini menginstruksikan Anda untuk mengaktifkan Secret Manager sebagai lokasi penyimpanan utama untuk informasi sensitif seperti sandi dan kunci API yang digunakan oleh lingkungan Managed Service untuk Apache Airflow. Hal ini meningkatkan keamanan dengan memusatkan dan mengelola kredensial dalam layanan khusus. Untuk mengetahui informasi selengkapnya, lihat Secret Manager.

Mengizinkan akun layanan Composer mengakses secret

Langkah ini memastikan bahwa akun layanan yang terkait dengan Managed Service untuk Apache Airflow memiliki izin yang diperlukan untuk mengakses secret yang disimpan dalam Secret Manager. Secara default, Managed Service untuk Apache Airflow menggunakan akun layanan Compute Engine. Izin yang diperlukan adalah Secret Manager Secret Accessor. Izin ini memungkinkan akun layanan mengambil dan menggunakan secret yang disimpan di Secret Manager.Untuk panduan lengkap tentang cara mengonfigurasi kontrol akses di Secret Manager, lihat dokumentasi kontrol akses.

Koneksi BigQuery di Airflow

Pastikan untuk membuat koneksi sfdc_cdc_bq sesuai dengan Mengumpulkan setelan Managed Airflow. Koneksi ini kemungkinan digunakan oleh modul Salesforce ke BigQuery untuk membuat komunikasi dengan BigQuery.

Apa langkah selanjutnya?