Integrasi dengan Salesforce (SFDC)

Halaman ini menjelaskan langkah-langkah integrasi untuk beban kerja operasional Salesforce (SFDC) di Dasar Data Cortex Framework. Cortex Framework mengintegrasikan data dari Salesforce dengan pipeline Dataflow melalui BigQuery, sementara Cloud Composer menjadwalkan dan memantau pipeline Dataflow ini untuk mendapatkan insight dari data Anda.

Catatan: Sebelum mengonfigurasi integrasi untuk beban kerja, ikuti langkah-langkah untuk deployment Cortex Framework Data Foundation.

File konfigurasi

File config.json 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 Salesforce operasional:

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

Tabel berikut menjelaskan nilai untuk setiap parameter operasional SFDC:

Parameter	Arti	Nilai Default	Deskripsi
SFDC.deployCDC	Men-deploy CDC	true	Buat skrip pemrosesan CDC untuk dijalankan sebagai DAG di Cloud Composer. Lihat dokumentasi untuk berbagai opsi penyerapan data untuk Salesforce Sales Cloud.
SFDC.createMappingViews	Membuat tampilan pemetaan	true	DAG yang disediakan untuk mengambil data baru dari Salesforce API memperbarui data di halaman landing. Jika nilai ini disetel ke benar, tampilan akan dibuat di set data yang diproses CDC untuk mengekspos tabel dengan "versi kebenaran terbaru" dari set data Mentah. Jika salah (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	Buat tabel penampung kosong jika tabel tersebut tidak dibuat oleh proses penyerapan untuk memungkinkan deployment pelaporan hilir dieksekusi tanpa gagal.
SFDC.datasets.raw	Set data halaman 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 memproses rekaman. Jika menggunakan data pengujian, buat set data kosong.
SFDC.datasets.reporting	Reporting Dataset 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).

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

Tampilan dasar

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

Tampilan pelaporan

Objek ini adalah objek hijau dalam 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 secara spesifik cara data Salesforce Anda harus distrukturkan untuk digunakan dengan Cortex Framework.

• Struktur Tabel:
  • Penamaan: Nama tabel menggunakan snake_case (kata huruf kecil yang dipisahkan dengan garis bawah) dan berbentuk jamak. Misalnya, some_objects.
  • Jenis Data: Kolom mempertahankan jenis data yang sama seperti yang ditampilkan dalam Salesforce.
  • Keterbacaan: Beberapa nama kolom mungkin sedikit disesuaikan agar lebih jelas di lapisan pelaporan.
• Tabel dan Deployment Kosong: Tabel wajib yang tidak ada dalam set data mentah akan otomatis dibuat sebagai tabel kosong selama proses deployment. Hal ini memastikan eksekusi langkah deployment CDC yang lancar.
• Persyaratan CDC: Kolom Id dan SystemModstamp sangat penting agar skrip CDC dapat melacak perubahan pada data Anda. Nama-nama tersebut dapat sama persis atau berbeda. Skrip pemrosesan mentah yang disediakan mengambil kolom ini secara otomatis dari API dan memperbarui tabel replikasi target.
  • Id: Kolom ini berfungsi sebagai ID unik untuk setiap data.
  • SystemModstamp: Kolom ini menyimpan stempel waktu yang menunjukkan terakhir kali rekaman diubah.
• Skrip Pemrosesan Raw:Skrip pemrosesan Raw yang diberikan 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 opsi default, di mana 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 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 antar-mata uang dari waktu ke waktu.

Framework Cortex mengharapkan tabel ini ada jika Anda menggunakan pengelolaan mata uang lanjutan. Jika tidak menggunakan pengelolaan mata uang lanjutan, Anda dapat menghapus entri terkait 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 disesuaikan 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 ditujukan untuk data yang dapat diakses langsung melalui API. Cortex Framework dapat memanggil API, mengambil data, dan menyimpannya dalam set data "Raw" 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 dibutuhkan 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 sesuai dengan perubahan tersebut. Skrip ini mengandalkan dua kolom khusus dalam data Anda:

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

   Jika data Anda tidak memiliki nama yang persis sama, 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 tetap dapat menggunakannya. Skrip CDC dilengkapi dengan file pemetaan yang dapat menerjemahkan struktur data yang ada ke dalam format yang dibutuhkan 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 ditujukan untuk alat yang dapat menambahkan record data baru (_appendalways_pattern) atau memperbarui record yang ada.
3. Alat replikasi dan menambahkan data baru: Jika alat tidak memperbarui data dan mereplikasi perubahan apa pun sebagai data baru ke dalam tabel target (Raw), Cortex Data Foundation akan memberikan opsi untuk membuat skrip pemrosesan CDC. Untuk mengetahui informasi selengkapnya, lihat proses CDC.

Gambar 1. Beban kerja 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 dibuat sebagai gantinya.

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

Contoh file konfigurasi setting.yaml berikut menggambarkan pembuatan tampilan pemetaan saat alat replikasi memperbarui data langsung ke set data yang direplikasi, seperti yang diilustrasikan dalam option 3 (yaitu, tidak diperlukan CDC, 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, menyetel parameter deployCDC : False memiliki efek yang sama, karena skrip pemrosesan non-CDC perlu dibuat.

Pemetaan data

Anda perlu memetakan kolom data 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)
• Cortex Field: 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 ingin mereplikasi kolom Who.Type objek Task, tambahkan baris Who_Type,Who_Type,STRING. Tindakan ini menentukan kolom baru bernama Who.Type yang dipetakan ke dirinya sendiri (tetap memiliki nama yang sama) dan memiliki jenis data string.

Mengubah Template DAG

Anda mungkin perlu menyesuaikan template DAG untuk CDC atau untuk Pemrosesan data mentah sebagaimana diperlukan oleh instance Airflow atau Cloud Composer Anda. Untuk mengetahui informasi selengkapnya, lihat Mengumpulkan setelan Cloud Composer.

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 Data Foundation Cortex Framework, Anda dapat melewati pembuatan setelan tampilan pemetaan SFDC.createMappingViews=false.

Mengonfigurasi modul ekstraksi

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

Menyiapkan kredensial dan Aplikasi yang 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 Izin Sistem.
   2. Izin View All diberikan untuk semua objek yang ingin Anda replikasi. Misalnya, Akun, dan Kasus. Periksa apakah ada batasan atau masalah dengan administrator keamanan Anda.
   3. Tidak ada izin yang diberikan untuk terkait dengan login antarmuka pengguna, seperti Salesforce Anywhere di Lightning Experience, Salesforce Anywhere di Mobile, Pengguna Lightning Experience,dan Pengguna Login Lightning. Periksa apakah ada batasan atau masalah dengan administrator keamanan Anda.
2. Buat atau gunakan identitas pengguna yang sudah ada di Salesforce. Anda harus mengetahui nama pengguna, sandi, dan token keamanan pengguna. Pertimbangkan hal berikut:
   • Idealnya, pengguna ini adalah pengguna yang dikhususkan untuk menjalankan replikasi ini.
   • Pengguna harus ditetapkan ke profil yang telah Anda buat atau identifikasi pada langkah 1.
   • Anda dapat melihat Nama Pengguna dan mereset Sandi di sini.
   • Anda dapat mereset token keamanan jika Anda 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 (Setelan OAuth yang Diaktifkan).
   3. Lihat dokumentasi tentang cara mendapatkan kunci konsumen (yang akan digunakan nanti sebagai Client ID Anda). Hubungi administrator keamanan Anda untuk mengetahui masalah atau batasan.
4. Tetapkan Aplikasi Terhubung Anda ke profil yang dibuat.
   1. Pilih Penyiapan 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 Aplikasi Terhubung yang Ditetapkan.
   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-to-BigQuery mengandalkan Secret Manager untuk menyimpan kredensial yang diperlukan untuk terhubung ke Salesforce dan BigQuery secara aman. Pendekatan ini menghindari pemaparan informasi sensitif seperti sandi secara langsung dalam kode atau file konfigurasi Anda, sehingga meningkatkan keamanan.

Buat secret dengan spesifikasi berikut. Untuk mengetahui petunjuk yang lebih mendetail, lihat Membuat secret.

• Nama Secret: airflow-connections-salesforce-conn

• Nilai Rahasia:

  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 Cloud Composer untuk replikasi

Untuk menjalankan skrip Python di DAG yang disediakan oleh Cortex Framework Data Foundation, Anda perlu menginstal beberapa dependensi. Untuk Airflow versi 1.10, ikuti dokumentasi Menginstal dependensi Python untuk Cloud Composer 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 Cloud Composer 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 Cloud Composer Anda. 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 Cloud Composer memiliki izin yang diperlukan untuk mengakses secret yang disimpan dalam Secret Manager. Secara default, Cloud Composer 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 Cloud Composer. Koneksi ini kemungkinan digunakan oleh modul Salesforce-to-BigQuery untuk membuat komunikasi dengan BigQuery.

Apa langkah selanjutnya?

• Untuk mengetahui informasi selengkapnya tentang sumber data dan workload lainnya, lihat Sumber data dan workload.
• Untuk mengetahui informasi selengkapnya tentang langkah-langkah deployment di lingkungan produksi, lihat Prasyarat deployment Data Foundation Cortex Framework.