Integrasi dengan Salesforce (SFDC)

Halaman ini menjelaskan langkah-langkah integrasi untuk beban kerja operasional Salesforce (SFDC) di Cortex Framework Data Foundation. 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 apa 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 untuk Salesforce Sales Cloud.
SFDC.createMappingViews	Membuat tampilan pemetaan	true	DAG yang disediakan untuk mengambil data baru dari Salesforce API akan memperbarui data di halaman landing. Nilai ini ditetapkan ke benar akan menghasilkan tampilan dalam set data yang diproses CDC untuk mengekspos tabel dengan "versi terbaru kebenaran" dari set data Mentah. Jika salah 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 placeholder kosong jika tidak dihasilkan oleh proses penyerapan untuk memungkinkan deployment pelaporan downstream dijalankan 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 memproses data. Jika menggunakan data pengujian, buat set data kosong.
SFDC.datasets.reporting	Dataset 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).

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 secara spesifik cara data Salesforce Anda harus distrukturkan untuk digunakan dengan Framework Cortex.

• Struktur Tabel:
  • Penamaan: Nama tabel menggunakan snake_case (kata-kata huruf kecil yang dipisahkan dengan garis bawah) dan jamak. Misalnya, some_objects.
  • Jenis Data: Kolom mempertahankan jenis data yang sama seperti yang ditampilkan dalam Salesforce.
  • Keterbacaan: Beberapa nama kolom mungkin sedikit disesuaikan untuk meningkatkan kejelasan di lapisan pelaporan.
• Tabel Kosong dan Deployment: Setiap tabel yang diperlukan dan tidak ada dalam set data mentah akan otomatis dibuat sebagai tabel kosong selama proses deployment. Hal ini memastikan kelancaran eksekusi langkah deployment CDC.
• Persyaratan CDC: Kolom Id dan SystemModstamp sangat penting bagi skrip CDC untuk melacak perubahan pada data Anda. Nama tersebut dapat memiliki nama persis ini atau nama yang berbeda. Skrip pemrosesan Raw 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 data diubah.
• Skrip Pemrosesan Raw:Skrip pemrosesan Raw 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, dengan semua data menggunakan satu mata uang.
• Lanjutan: Opsi ini mengonversi antar-mata uang berdasarkan kurs (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 berisi nilai tukar antara mata uang dari waktu ke waktu.

Cortex Framework mengharapkan tabel ini ada jika Anda menggunakan pengelolaan mata uang lanjutan. Jika 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 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 "Mentah" dalam BigQuery. Jika ada data yang ada dalam set data, Framework Cortex dapat memperbaruinya dengan data baru.
2. Tampilan Pemetaan Struktur: Metode ini berguna jika Anda telah memuat data ke BigQuery melalui alat lain, tetapi struktur datanya 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. CDC (Change Data Capture) Processing Scripts: Opsi ini dirancang khusus untuk data yang terus berubah. Skrip CDC melacak perubahan ini dan memperbarui data di BigQuery. Skrip ini bergantung pada 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 persis ini, 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 perubahan 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 data yang berasal dari Salesforce API.
2. Alat replikasi dan selalu tambahkan : Jika Anda menggunakan alat untuk replikasi, cara ini ditujukan untuk alat yang dapat menambahkan data baru (_appendalways_pattern) atau memperbarui data yang ada.
3. Alat replikasi dan menambahkan data baru: Jika alat tidak memperbarui data dan mereplikasi perubahan apa pun sebagai data baru ke tabel target (Raw), Cortex Data Foundation menyediakan opsi untuk membuat skrip pemrosesan CDC. Untuk 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 API salesforce dan mereplikasi data ke set data Mentah (bagian salesforce_to_raw_tables) dan pembuatan skrip untuk memproses perubahan yang masuk ke set data Mentah dan ke set data yang diproses CDC (bagian raw_to_cdc_tables).

Secara default, skrip yang disediakan untuk membaca dari API akan 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 Framework Data Cortex.

Contoh file konfigurasi setting.yaml berikut mengilustrasikan 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 dijalankan 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 skrip pemrosesan CDC tidak perlu dibuat.

Pemetaan data

Anda perlu 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 di sistem sumber)
• Kolom Cortex: AccountId (nama yang diharapkan oleh Cortex)
• Jenis Data: String (jenis data yang diharapkan oleh Cortex)

Memetakan Kolom Polimorf

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 dari objek Task untuk direplikasi, tambahkan baris Who_Type,Who_Type,STRING. Tindakan ini menentukan kolom baru bernama Who.Type yang dipetakan ke dirinya sendiri (menjaga 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 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 Cortex Framework Data Foundation, Anda dapat melewati pembuatan tampilan pemetaan yang 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 dapat bervariasi bergantung pada sistem dan konfigurasi yang ada. Atau, Anda dapat menggunakan alat lain yang tersedia.

Menyiapkan kredensial dan Aplikasi terhubung

Login sebagai administrator ke instance Salesforce Anda untuk menyelesaikan hal 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 replikasikan. Misalnya, Akun dan Kasus. Periksa batasan atau masalah dengan administrator keamanan Anda.
   3. Tidak ada izin yang diberikan untuk hal yang terkait dengan login antarmuka pengguna, seperti Salesforce Anywhere di Lightning Experience, Salesforce Anywhere di Seluler, Pengguna Lightning Experience,dan Pengguna Lightning Login. Periksa batasan atau masalah dengan administrator keamanan Anda.
2. Buat atau gunakan identifikasi pengguna yang ada di Salesforce. Anda perlu mengetahui nama pengguna, sandi, dan token keamanan pengguna. Pertimbangkan hal berikut:
   • Idealnya, pengguna ini harus didedikasikan 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 tidak memilikinya dan token tersebut tidak digunakan oleh proses lain.
3. Buat Aplikasi Terhubung. 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 nantinya akan digunakan sebagai Client ID). 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. Telusuri 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

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

Buat secret dengan spesifikasi berikut. Untuk mengetahui petunjuk detail selengkapnya, 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 Client ID Anda.
  • SECRET_TOKEN dengan token rahasia Anda.

Untuk mengetahui informasi selengkapnya, lihat cara menemukan nama instance.

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 dokumentasi 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 di 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 komprehensif 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-ke-BigQuery untuk membuat komunikasi dengan BigQuery.

Apa langkah selanjutnya?

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