feat(salesforce): add getting started

docs/snowflake-native-apps/snowflake-connectors/_category_.yaml

@@ -0,0 +1,4 @@
+label: "Maxa Connectors"
+position: 2
+link:
+  type: "generated-index"

docs/snowflake-native-apps/snowflake-connectors/salesforce-sales-cloud/_category_.yaml

@@ -0,0 +1,4 @@
+label: "Maxa Connector for Salesforce Sales Cloud"
+position: 1
+link:
+  type: "generated-index"

docs/snowflake-native-apps/snowflake-connectors/salesforce-sales-cloud/app-overview.md

@@ -0,0 +1,14 @@
+---
+sidebar_position: 1
+---
+
+# App Overview
+
+The Salesforce Sales Cloud Connector by Maxa is a Snowflake Native Application that allows you to extract data from your Salesforce Sales Cloud account and load records into a Snowflake database of your choice.
+
+
+# Contact Us
+
+- Support: [support.maxa.ai](https://support.maxa.ai/)
+- Email: snowflake-info@maxa.ai
+- Website: [maxa.ai/contact](https://www.maxa.ai/contact/)

docs/snowflake-native-apps/snowflake-connectors/salesforce-sales-cloud/how-to-install.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 3
+---
+
+# How to Use
+
+## Configuration
+
+Navigate to the tab `Configuration`. Start the configuration by selecting a `Destination Database` where the Salesforce objects records will be saved. `Secret Name` and `External Access Integration Name` should already be there if you followed the “Grant Salesforce Access” section. If not, please go to the section and follow the procedure. Finally, select the virtual `Warehouse` where your sync will run. 
+
+A checked box inform you that you are giving consent for Maxa to access your event table for issue resolution and improved user experience purposes. Information will be treated confidentially according to our [privacy policy](https://www.maxa.ai/legal/) and used solely to enhance your user experience. By consenting, you acknowledge and agree that Maxa is not liable for any issues arising from the use of this information. Unchecking the box will disable sharing of your event table with Maxa. In that case, we will be unable to know when an issue occurs on your app. 
+
+### Advanced Options
+
+All the advanced options are optional.
+
+`Destination Table Prefix` allows to choose a prefix to apply to all tables where Salesforce objects records will be saved. The table names will have the prefix followed by the Salesforce objects name. 
+
+`Default Replication Frequency` allows to set a default replication frequency which will be apply to all enabled Salesforce objects unless specify otherwise. The available frequency modes are:
+
+- `Manual`: user triggers manually the replication.
+- `Cron`: the user must specify a cron string for the replication. ([Documentation](https://docs.snowflake.com/en/sql-reference/sql/create-task))
+- `Every 24 hours`: replication will occur in 24 hours intervals at midnight UTC.  This is the default frequency the app will use if no other mode as been specified.
+- `Every 12 hours`: replication will occur in 12 hours intervals at midnight and noon UTC.
+
+`Default Replication Mode` allows to set a default replication mode which will be applied to all enabled Salesforce objects unless specify otherwise. The available modes are: 
+
+- `Incremental | Append + Deduped` : only the records that have been updated since the last sync will be read. New records read will replace the previous version in the destination table. If an existing row has been updated, the new row will be added to the table replacing the previous version. The firs sync of the incremental mode will act like a full refresh. This is the default mode the app will use if no other mode as been specified.
+- `Incremental | Append` : only the records that have been updated since the last sync will be read. New records read will be append to the destination table. If an existing row has been updated, the new row will be added to the table and the previous version will stay in the table as well. The firs sync of the incremental mode will act like a full refresh.
+- `Full Refresh | Overwrite` : the entire history of the records will be read during the sync. Existing data, if any, will be overwritten by the data read during the sync.
+- `Full Refresh | Append` : the entire history of the records will be read during the sync. Existing data, if any, will stay in intact in the destination table and new data ready will be append to it. If similar data is synced, every sync will replicated existing data.
+
+Click on `Configure` to set up and saved your configurations. Next step will be to enable Salesforce objects you would like to sync be navigating to the tab `Objects Settings`. 
+
+## Data Sync
+
+Navigate to the tab `Objects Settings`. If you haven’t configure the connector yet, go to the `Configuration` tab and fill-out mandatory options. Once your configuration is set up, you will see a list of all available Salesforce objects. A red circle indicated that the object has not been enable for replication yet. A green circle indicated that the object has been enable. 
+
+### Enable Replication
+
+If you wish to enable replication on a specific object, expand the object section by clicking on the arrow at the right of the object bar. Click on `Enable` to set replication on the object. The circle at the left of the object name will turn green indicating that the object has been enabled. To disable the replication, click on `Disable`. If a default replication schedule and mode hasn’t been configured in the advanced configuration options, the replication schedule will occur in 24 hours intervals at midnight UTC and the replication mode will be incremental. 
+
+### Set Specific Sync Frequency
+
+Once your Salesforce object is enabled, you can set a specific replication frequency in the `General` section. The replication frequency you choose for the object will override the default option for the specific object only. If you want to set a default replication frequency for all objects, go to the `Configuration` tab and in the `Advanced Options` section. The available frequency modes are:
+
+- `Manual`: user triggers manually the replication.
+- `Cron`: the user must specify a cron string for the replication. ([Documentation](https://docs.snowflake.com/en/sql-reference/sql/create-task))
+- `Every 24 hours`: replication will occur in 24 hours intervals at midnight UTC. This is the default frequency the app will use if no other mode as been specified.
+- `Every 12 hours`: replication will occur in 12 hours intervals at midnight and noon UTC.
+
+### Set Specific Sync Mode
+
+Once your Salesforce object is enabled, you can set a specific replication mode in the `General` section. The replication mode you choose for the object will override the default option for the specific object only. If you want to set a default replication mode for all objects, go to the `Configuration` tab and in the `Advanced Options` section. The available modes are: 
+
+- `Incremental | Append + Deduped` : only the records that have been updated since the last sync will be read. New records read will replace the previous version in the destination table. If an existing row has been updated, the new row will be added to the table replacing the previous version. The firs sync of the incremental mode will act like a full refresh. This is the default mode the app will use if no other mode as been specified.
+- `Incremental | Append` : only the records that have been updated since the last sync will be read. New records read will be append to the destination table. If an existing row has been updated, the new row will be added to the table and the previous version will stay in the table as well. The firs sync of the incremental mode will act like a full refresh.
+- `Full Refresh | Overwrite` : the entire history of the records will be read during the sync. Existing data, if any, will be overwrite by the data read during the sync.
+- `Full Refresh | Append` : the entire history of the records will be read during the sync. Existing data, if any, will stay in intact in the destination table and new data ready will be append to it. If similar data is synced, every sync will replicated existing data
+
+## Sync History
+
+Navigate to the tab `Sync History`. If you haven’t configure the connector yet, go to the `Configuration` tab and fill-out mandatory options. The `Sync History` tab allows you to see all previous replication and their respective state. It can also be used to trigger manual replication. 
+
+### Manual Sync
+
+If you wish to replicate all objects at once, click on `Synchronize`. If you wish to replicate only a specific object, use the search tab to select the Salesforce object to be sync and click on `Synchronize`.
+
+## Data Preview
+
+Navigate to the tab `Data Preview`. If you haven’t configure the connector yet, go to the `Configuration` tab and fill-out mandatory options. The `Data Preview` tab allows you to see the first 100 rows of the Salesforce objects you have enabled. Use the search bar to select the object you would like to preview.

docs/snowflake-native-apps/snowflake-connectors/salesforce-sales-cloud/how-to-use.md

@@ -0,0 +1,94 @@
+---
+sidebar_position: 2
+---
+
+# How to Install
+
+## Step-by-Step Guide to Running the App
+
+### 1. Prerequisites
+
+You will need a Salesforce Sales Cloud account with permission to access data from resources you want to sync. The following information will be needed after installing the app to allow Snowflake to get Salesforce access: 
+
+- `salesforce_client_id` , `salesforce_client_secret` and `salesforce_refresh_token` : this information can be obtained from Salesforce following the procedure described [here](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_refresh_token_flow.htm&type=5).
+- `salesforce_domain` : Your custom domain is the part between **https://** and **.my.salesforce.com** in your custom Salesforce URL. More info can be obtained from Salesforce following the procedure [here](https://help.salesforce.com/s/articleView?id=sf.domain_name_overview.htm&type=5).
+
+Please have this information ready to use, it will be needed after installing the app in the section “Grant Salesforce Access”.
+
+### 2. Installation
+1. Log into your Snowflake account. 
+2. Navigate to the `Marketplace` and locate the Salesforce Connector app by Maxa.
+3. Click on `Get` to initiate the installation process.
+4. Follow the prompts and grant necessary permissions to complete the installation.
+5. Click `Apps` on the left sidebar under the `Installed Apps` section, you should see the `Salesforce Connector` by Maxa.
+
+### 3. Grant Salesforce Access
+
+`salesforce_client_id` , `salesforce_client_secret` , `salesforce_refresh_token` and `salesforce_domain` are needed for this step. Please refer to the “Prerequisite” section for explanation on how to get this information. 
+
+Before opening the app, you will need to run the following script adjusted with your information in a Snowflake worksheet. This script allows you to stock your Snowflake credential in a confidential place and grant access for the app to access it. 
+
+Copy the following script in a Snowflake worksheet and replace <salesforce_domain> by `salesforce_domain` , <salesforce_client_id> by `salesforce_client_id` , <salesforce_client_secret> by `salesforce_client_secret` and <salesforce_refresh_token> by `salesforce_refresh_token` and run the script. 
+
+```sql
+SET APP_NAME = '<INSTALLED_APPLICATION_NAME>';
+SET WAREHOUSE = '<WAREHOUSE_NAME>';
+SET APP_INSTANCE_NAME = $APP_NAME || '_INSTANCE';
+SET INTEGRATION_NAME = $APP_NAME || '_INTEGRATION';
+SET SECRETS_DB = $APP_NAME || '_SECRETS';
+SET SECRETS_SCHEMA = $SECRETS_DB || '.PUBLIC';
+SET SECRET_NAME = $SECRETS_DB || '.PUBLIC.{{ config.installation.secret }}';
+
+USE ROLE ACCOUNTADMIN;
+
+CREATE OR REPLACE DATABASE IDENTIFIER($SECRETS_DB);
+USE DATABASE IDENTIFIER($SECRETS_DB);
+
+CREATE OR REPLACE NETWORK RULE SALESFORCE_RULE
+MODE = EGRESS
+TYPE = HOST_PORT
+VALUE_LIST = ('login.salesforce.com:443', '<salesforce_domain>.my.salesforce.com:443');
+
+CREATE OR REPLACE SECRET IDENTIFIER($SECRET_NAME)
+TYPE=GENERIC_STRING
+SECRET_STRING='{
+    "client_id": "<salesforce_client_id>",
+    "client_secret": "<salesforce_client_secret>",
+    "refresh_token": "<salesforce_refresh_token>"
+}';
+
+SET CREATE_INTEGRATION = 'CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION
+IDENTIFIER($INTEGRATION_NAME)
+ALLOWED_NETWORK_RULES = (SALESFORCE_RULE)
+ALLOWED_AUTHENTICATION_SECRETS = (''' || $SECRET_NAME || ''')
+ENABLED = TRUE';
+
+SELECT $CREATE_INTEGRATION;
+EXECUTE IMMEDIATE $CREATE_INTEGRATION;
+
+GRANT USAGE ON INTEGRATION IDENTIFIER($INTEGRATION_NAME) TO APPLICATION IDENTIFIER($APP_INSTANCE_NAME);
+
+GRANT USAGE ON DATABASE IDENTIFIER($SECRETS_DB) TO APPLICATION IDENTIFIER($APP_INSTANCE_NAME);
+GRANT USAGE ON SCHEMA IDENTIFIER($SECRETS_SCHEMA)  TO APPLICATION IDENTIFIER($APP_INSTANCE_NAME);
+GRANT READ ON SECRET IDENTIFIER($SECRET_NAME) TO APPLICATION IDENTIFIER($APP_INSTANCE_NAME);
+
+GRANT CREATE DATABASE ON ACCOUNT TO APPLICATION IDENTIFIER($APP_INSTANCE_NAME);
+GRANT EXECUTE TASK ON ACCOUNT TO APPLICATION IDENTIFIER($APP_INSTANCE_NAME);
+
+CREATE DATABASE IF NOT EXISTS LOGS;
+CREATE EVENT TABLE IF NOT EXISTS LOGS.PUBLIC.EVENT_TABLE;
+
+GRANT USAGE ON DATABASE LOGS TO APPLICATION IDENTIFIER($APP_INSTANCE_NAME);
+GRANT USAGE ON SCHEMA LOGS.PUBLIC TO APPLICATION IDENTIFIER($APP_INSTANCE_NAME);
+GRANT SELECT ON TABLE LOGS.PUBLIC.EVENT_TABLE TO APPLICATION IDENTIFIER($APP_INSTANCE_NAME);
+
+GRANT USAGE ON WAREHOUSE IDENTIFIER($WAREHOUSE) TO APPLICATION IDENTIFIER($APP_INSTANCE_NAME);
+```
+
+### Grant Privileges
+
+Once you open the `Salesforce Connector` app, you will need to grant the application privileges necessary to extract data into Snowflake. Click on the security logo situated in the top right corner. Under `Account level privileges`, click `Review` , enable `Create Database` , `Create Warahouse` and `Execute Task` and click on `Update Privileges`. 
+
+# App Functionality
+
+Note: All tabs except "Configuration" will show a warning message until the connector is configured.