Merge pull request #15 from forcedotcom/onboarding-readme-updates

Start on README updates, more to come

Author: markdlv-sf

README.md

@@ -8,6 +8,14 @@ More specifically, this codebase gives you ability to test code locally before p
 
 Use of this project with Salesforce is subject to the [TERMS OF USE](./TERMS_OF_USE.md)
 
+## Prerequisites
+
+- Python 3.11 (If your system version is different, we recommend using [pyenv](https://github.com/pyenv/pyenv) to configure 3.11)
+- [Azul Zulu OpenJDK 17.x](https://www.azul.com/downloads/?version=java-17-lts&package=jdk#zulu)
+- Docker support like [Docker Desktop](https://docs.docker.com/desktop/)
+- A salesforce org, with some DLOs or DMOs with data
+- A [connected app](#creating-a-connected-app)
+
 ## Installation
 The SDK can be downloaded directly from PyPI with `pip`:
 ```
@@ -19,12 +27,16 @@ You can verify it was properly installed via CLI:
 datacustomcode version
 ```
 
-## Development Setup
-We offer two built-in development interfaces: `devcontainers` and Jupyter, but you can set up any tool you would like manually.
+## Quick start
+Ensure you have all the [prerequisites](#prerequisites) prepared on your machine.
 
-To get started, use the CLI to initialize a new development environment:
-```
-datacustomcode init [DIRECTORY TO DUMP NEW REPO]
+To get started, create a directory and initialize a new project with the CLI:
+```zsh
+mkdir datacloud && cd datacloud
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install salesforce-data-customcode
+datacustomcode init my_package
 ```
 
 This will yield all necessary files to get started:
@@ -43,11 +55,31 @@ This will yield all necessary files to get started:
 * `Dockerfile` <span style="color:grey;font-style:italic;">(Do not update)</span> – Development container emulating the remote execution environment.
 * `requirements-dev.txt` <span style="color:grey;font-style:italic;">(Do not update)</span> – These are the dependencies for the development environment.
 * `jupyterlab.sh` <span style="color:grey;font-style:italic;">(Do not update)</span> – Helper script for setting up Jupyter.
-* `requirements.txt` – Here you define the requirements that you will need remotely
+* `requirements.txt` – Here you define the requirements that you will need for your script.
 * `payload` – This folder will be compressed and deployed to the remote execution environment.
   * `config.json` – This config defines permissions on the back and can be generated programmatically with `scan` CLI method.
   * `entrypoint.py` – The script that defines the data transformation logic.
 
+A functional entrypoint.py is provided so you can run once you've configured your connected app:
+```zsh
+cd my_package
+datacustomcode configure
+datacustomcode run ./payload/entrypoint.py
+```
+
+> [!IMPORTANT]
+> The example entrypoint.py requires a `Account_Home__dll` DLO to be present.  And in order to deploy the script (next step), the output DLO (which is `Account_Home_copy__dll` in the example entrypoint.py) also needs to exist and be in the same dataspace as `Account_Home__dll`.
+
+After modifying the `entrypoint.py` as needed, using any dependencies you add in the `.venv` virtual environment, you can run this script in Data Cloud:
+```zsh
+datacustomcode scan ./payload/entrypoint.py
+datacustomcode deploy --path ./payload --name my_custom_script
+```
+
+> [!TIP]
+> The `deploy` process can take several minutes.  If you'd like more feedback on the underlying process, you can add `--debug` to the command like `datacustomcode --debug deploy --path ./payload --name my_custom_script`
+
+
 ## API
 
 You entry point script will define logic using the `Client` object which wraps data access layers.
@@ -98,6 +130,12 @@ Options:
 - `--client-secret TEXT`: Connected App Client Secret
 - `--login-url TEXT`: Salesforce login URL
 
+#### `datacustomcode zip`
+Zip a transformation job in preparation to upload to Data Cloud.
+
+Options:
+- `--path TEXT`: Path to the code directory (default: ".")
+
 #### `datacustomcode deploy`
 Deploy a transformation job to Data Cloud.
 
@@ -133,3 +171,21 @@ Argument:
 Options:
 - `--config-file TEXT`: Path to configuration file
 - `--dependencies TEXT`: Additional dependencies (can be specified multiple times)
+
+## Prerequisite details
+
+### Creating a connected app
+
+1. Log in to salesforce as an admin. In the top right corner, click on the gear icon and go to `Setup`
+2. In the left hand side, search for "App Manager" and select the `App Manager` underneath `Apps`
+3. Click on `New Connected App` in the upper right
+4. Fill in the required fields within the `Basic Information` section
+5. Under the `API (Enable OAuth Settings)` section:
+    1. Click on the checkbox to Enable OAuth Settings.
+    2. Provide a callback URL like http://localhost:55555/callback
+    3. In the Selected OAuth Scopes, make sure that `refresh_token`, `api`, `cdp_query_api`, `cdp_profile_api` is selected.
+    4. Click on Save to save the connected app
+6. From the detail page that opens up afterwards, click the "Manage Consumer Details" button to find your client id and client secret
+7. Go back to `Setup`, then `OAuth and OpenID Connect Settings`, and enable the "Allow OAuth Username-Password Flows" option
+
+You now have all fields necessary for the `datacustomcode configure` command.

src/datacustomcode/templates/jupyterlab.sh

@@ -48,13 +48,13 @@ check_docker() {
 # Function to start Jupyter server
 start_jupyter() {
     echo "Building the docker image"
-    docker build -t datacloud-byoc .
+    docker build -t datacloud-customcode .
 
     echo "Running the docker container"
     docker run -d --rm -p 8888:8888 \
         -v $(pwd):/workspace \
         --name jupyter-server \
-        datacloud-byoc jupyter lab \
+        datacloud-customcode jupyter lab \
         --ip=0.0.0.0 \
         --port=8888 \
         --no-browser \