[doc] How to create and use custom strong type connection

.github/workflows/samples_flows_standard_flow_with_package_tool_using_custom_strong_type_connection.yml

@@ -0,0 +1,89 @@
+# This code is autogenerated.
+# Code is generated by running custom script: python3 readme.py
+# Any manual changes to this file may cause incorrect behavior.
+# Any manual changes will be overwritten if the code is regenerated.
+
+name: samples_flows_standard_flow_with_package_tool_using_custom_strong_type_connection
+on:
+  schedule:
+    - cron: "38 19 * * *" # Every day starting at 3:38 BJT
+  pull_request:
+    branches: [ main ]
+    paths: [ examples/flows/standard/flow-with-package-tool-using-custom-strong-type-connection/**, examples/*requirements.txt, .github/workflows/samples_flows_standard_flow_with_package_tool_using_custom_strong_type_connection.yml ]
+  workflow_dispatch:
+
+jobs:
+  samples_readme_ci:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Setup Python 3.9 environment
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+      - name: Generate config.json
+        run: echo '${{ secrets.TEST_WORKSPACE_CONFIG_JSON_CANARY }}' > ${{ github.workspace }}/examples/config.json
+      - name: Prepare requirements
+        working-directory: examples
+        run: |
+          if [[ -e requirements.txt ]]; then
+            python -m pip install --upgrade pip
+            pip install -r requirements.txt
+          fi
+      - name: Prepare dev requirements
+        working-directory: examples
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r dev_requirements.txt
+      - name: Refine .env file
+        working-directory: examples/flows/standard/flow-with-package-tool-using-custom-strong-type-connection
+        run: |
+          AOAI_API_KEY=${{ secrets.AOAI_API_KEY_TEST }}
+          AOAI_API_ENDPOINT=${{ secrets.AOAI_API_ENDPOINT_TEST }}
+          AOAI_API_ENDPOINT=$(echo ${AOAI_API_ENDPOINT//\//\\/})
+          if [[ -e .env.example ]]; then
+            echo "env replacement"
+            sed -i -e "s/<your_AOAI_key>/$AOAI_API_KEY/g" -e "s/<your_AOAI_endpoint>/$AOAI_API_ENDPOINT/g" .env.example
+            mv .env.example .env
+          fi
+      - name: Create run.yml
+        working-directory: examples/flows/standard/flow-with-package-tool-using-custom-strong-type-connection
+        run: |
+          gpt_base=${{ secrets.AOAI_API_ENDPOINT_TEST }}
+          gpt_base=$(echo ${gpt_base//\//\\/})
+          if [[ -e run.yml ]]; then
+            sed -i -e "s/\${azure_open_ai_connection.api_key}/${{ secrets.AOAI_API_KEY_TEST }}/g" -e "s/\${azure_open_ai_connection.api_base}/$gpt_base/g" run.yml
+          fi
+      - name: Azure Login
+        uses: azure/login@v1
+        with:
+          creds: ${{ secrets.AZURE_CREDENTIALS }}
+      - name: Extract Steps examples/flows/standard/flow-with-package-tool-using-custom-strong-type-connection/README.md
+        working-directory: ${{ github.workspace }}
+        run: |
+          python scripts/readme/extract_steps_from_readme.py -f examples/flows/standard/flow-with-package-tool-using-custom-strong-type-connection/README.md -o examples/flows/standard/flow-with-package-tool-using-custom-strong-type-connection
+      - name: Cat script
+        working-directory: examples/flows/standard/flow-with-package-tool-using-custom-strong-type-connection
+        run: |
+          cat bash_script.sh
+      - name: Run scripts
+        working-directory: examples/flows/standard/flow-with-package-tool-using-custom-strong-type-connection
+        run: |
+          export aoai_api_key=${{secrets.AOAI_API_KEY_TEST }}
+          export aoai_api_endpoint=${{ secrets.AOAI_API_ENDPOINT_TEST }}
+          export test_workspace_sub_id=${{ secrets.TEST_WORKSPACE_SUB_ID }}
+          export test_workspace_rg=${{ secrets.TEST_WORKSPACE_RG }}
+          export test_workspace_name=${{ secrets.TEST_WORKSPACE_NAME_CANARY }}
+          bash bash_script.sh
+      - name: Pip List for Debug
+        if : ${{ always() }}
+        working-directory: examples/flows/standard/flow-with-package-tool-using-custom-strong-type-connection
+        run: |
+          pip list
+      - name: Upload artifact
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v3
+        with:
+          name: artifact
+          path: examples/flows/standard/flow-with-package-tool-using-custom-strong-type-connection/bash_script.sh

.github/workflows/samples_flows_standard_flow_with_script_tool_using_custom_strong_type_connection.yml

@@ -0,0 +1,89 @@
+# This code is autogenerated.
+# Code is generated by running custom script: python3 readme.py
+# Any manual changes to this file may cause incorrect behavior.
+# Any manual changes will be overwritten if the code is regenerated.
+
+name: samples_flows_standard_flow_with_script_tool_using_custom_strong_type_connection
+on:
+  schedule:
+    - cron: "13 20 * * *" # Every day starting at 4:13 BJT
+  pull_request:
+    branches: [ main ]
+    paths: [ examples/flows/standard/flow-with-script-tool-using-custom-strong-type-connection/**, examples/*requirements.txt, .github/workflows/samples_flows_standard_flow_with_script_tool_using_custom_strong_type_connection.yml ]
+  workflow_dispatch:
+
+jobs:
+  samples_readme_ci:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Setup Python 3.9 environment
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+      - name: Generate config.json
+        run: echo '${{ secrets.TEST_WORKSPACE_CONFIG_JSON_CANARY }}' > ${{ github.workspace }}/examples/config.json
+      - name: Prepare requirements
+        working-directory: examples
+        run: |
+          if [[ -e requirements.txt ]]; then
+            python -m pip install --upgrade pip
+            pip install -r requirements.txt
+          fi
+      - name: Prepare dev requirements
+        working-directory: examples
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r dev_requirements.txt
+      - name: Refine .env file
+        working-directory: examples/flows/standard/flow-with-script-tool-using-custom-strong-type-connection
+        run: |
+          AOAI_API_KEY=${{ secrets.AOAI_API_KEY_TEST }}
+          AOAI_API_ENDPOINT=${{ secrets.AOAI_API_ENDPOINT_TEST }}
+          AOAI_API_ENDPOINT=$(echo ${AOAI_API_ENDPOINT//\//\\/})
+          if [[ -e .env.example ]]; then
+            echo "env replacement"
+            sed -i -e "s/<your_AOAI_key>/$AOAI_API_KEY/g" -e "s/<your_AOAI_endpoint>/$AOAI_API_ENDPOINT/g" .env.example
+            mv .env.example .env
+          fi
+      - name: Create run.yml
+        working-directory: examples/flows/standard/flow-with-script-tool-using-custom-strong-type-connection
+        run: |
+          gpt_base=${{ secrets.AOAI_API_ENDPOINT_TEST }}
+          gpt_base=$(echo ${gpt_base//\//\\/})
+          if [[ -e run.yml ]]; then
+            sed -i -e "s/\${azure_open_ai_connection.api_key}/${{ secrets.AOAI_API_KEY_TEST }}/g" -e "s/\${azure_open_ai_connection.api_base}/$gpt_base/g" run.yml
+          fi
+      - name: Azure Login
+        uses: azure/login@v1
+        with:
+          creds: ${{ secrets.AZURE_CREDENTIALS }}
+      - name: Extract Steps examples/flows/standard/flow-with-script-tool-using-custom-strong-type-connection/README.md
+        working-directory: ${{ github.workspace }}
+        run: |
+          python scripts/readme/extract_steps_from_readme.py -f examples/flows/standard/flow-with-script-tool-using-custom-strong-type-connection/README.md -o examples/flows/standard/flow-with-script-tool-using-custom-strong-type-connection
+      - name: Cat script
+        working-directory: examples/flows/standard/flow-with-script-tool-using-custom-strong-type-connection
+        run: |
+          cat bash_script.sh
+      - name: Run scripts
+        working-directory: examples/flows/standard/flow-with-script-tool-using-custom-strong-type-connection
+        run: |
+          export aoai_api_key=${{secrets.AOAI_API_KEY_TEST }}
+          export aoai_api_endpoint=${{ secrets.AOAI_API_ENDPOINT_TEST }}
+          export test_workspace_sub_id=${{ secrets.TEST_WORKSPACE_SUB_ID }}
+          export test_workspace_rg=${{ secrets.TEST_WORKSPACE_RG }}
+          export test_workspace_name=${{ secrets.TEST_WORKSPACE_NAME_CANARY }}
+          bash bash_script.sh
+      - name: Pip List for Debug
+        if : ${{ always() }}
+        working-directory: examples/flows/standard/flow-with-script-tool-using-custom-strong-type-connection
+        run: |
+          pip list
+      - name: Upload artifact
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v3
+        with:
+          name: artifact
+          path: examples/flows/standard/flow-with-script-tool-using-custom-strong-type-connection/bash_script.sh

docs/how-to-guides/develop-a-tool/create-and-use-tool-package.md

@@ -163,4 +163,5 @@ Alternatively, you can test your tool package using the script below to ensure t
 
 ## Advanced features
 [Customize your tool icon](add-a-tool-icon.md)  
-[Add category and tags for tool](add-category-and-tags-for-tool.md)  
+[Add category and tags for tool](add-category-and-tags-for-tool.md)
+[Create your own custom strong type connection](create-your-own-custom-strong-type-connection.md) 

docs/how-to-guides/develop-a-tool/create-your-own-custom-strong-type-connection.md

@@ -0,0 +1,107 @@
+# Create and Use Your Own Custom Strong Type Connection
+Connections serve as a secure method for managing credentials for external APIs and data sources. This document provides a step-by-step guide on how to create and use a custom strong type connection. The advantages of using a custom strong type connection are as follows:
+
+* Enhanced User-Friendly Experience: Custom strong type connections offer an enhanced user-friendly experience compared to custom connections, as they eliminate the need to fill in connection keys. Only values are required.
+* Improved IntelliSense Experience: By using a custom strong type connection, you can benefit from an enhanced IntelliSense experience, receiving real-time suggestions and auto-completion for available keys.
+* Centralized Information: A custom strong type connection provides a centralized location to access and view all available keys and value types, making it easier to explore and create the connection.
+
+For other connections types, please refer to [Connections](https://microsoft.github.io/promptflow/concepts/concept-connections.html).
+
+## Prerequisites
+- Please ensure that your [Prompt flow for VS Code](https://marketplace.visualstudio.com/items?itemName=prompt-flow.prompt-flow) is updated to version 1.1.2 or a more recent version.
+- Install promptflow package.
+
+  ```bash
+  # Eventually only need to pip install promptflow==0.1.0b8
+  pip install "promptflow==0.0.108377202" --extra-index-url https://azuremlsdktestpypi.azureedge.net/promptflow
+  ```
+
+## Create your own custom strong type connection
+You can take this [file](https://github.com/microsoft/promptflow/blob/main/examples/tools/tool-package-quickstart/my_tool_package/tools/tool_with_custom_strong_type_connection.py) as an example to have a better understanding of how to create a custom strong type connection and how a tool uses it.
+Create your custom strong type connection as belows:
+```python
+from promptflow.connections import CustomStrongTypeConnection
+from promptflow.contracts.types import Secret
+
+
+class MyCustomConnection(CustomStrongTypeConnection):
+    """My custom strong type connection.
+
+    :param api_key: The api key.
+    :type api_key: String
+    :param api_base: The api base.
+    :type api_base: String
+    """
+    api_key: Secret
+    api_base: str = "This is a fake api base."
+
+```
+Make sure that you adhere to the following guidelines:
+
+* You can define your own custom connection using any desired name. But ensure that it inherits the class `CustomStrongTypeConnection`.
+  > [!Note] Avoid using the `CustomStrongTypeConnection` class directly.
+* When specifying connection API keys, please use the `Secret` type to indicate that the key should be treated as a secret. Secret keys will be scrubbed to enhance security.
+* You can either have your custom connection class with your custom tool or separate it into a distinct Python file.
+* Document your custom strong type connection by using docstrings.  Follow the format of docstring like this. Use `param` and `type` to provide explanations for each key.
+
+  ```python
+  """My custom strong type connection.
+
+  :param api_key: The api key get from "https://xxx.com".
+  :type api_key: String
+  :param api_base: The api base.
+  :type api_base: String
+  """
+  ```
+  The purpose of parsing the docstring into a connection template is to enhance the clarity and understanding for users when creating a custom strong type connection. By providing detailed explanations for each key, users can easily grasp the meaning and purpose of each key, allowing them to accurately fill in the corresponding values.
+
+  ```yaml
+  $schema: https://azuremlschemas.azureedge.net/promptflow/latest/CustomStrongTypeConnection.schema.json
+  name: "to_replace_with_connection_name"
+  type: custom
+  custom_type: MyCustomConnection
+  module: my_tool_package.tools.my_tool_with_custom_strong_type_connection
+  package: test-custom-tools
+  package_version: 0.0.2
+  configs:
+    api_base: "This is a fake api base." # String, The api base.
+  secrets:
+    api_key: <user-input> #  String, The api key get from "https://xxx.com". Don't replace the '<user-input>' placeholder. The application will prompt you to enter a value when it runs.
+  ```
+
+## Develop a flow with a package tool with custom strong type connection
+To develop a flow with a package tool that uses a custom strong type connection, follow these steps:
+* Step1: Refer to the [create and use tool package](create-and-use-tool-package.md#create-custom-tool-package) documentation to build and install your tool package in your local environment.
+  > [!Note] After installing the new tool package in your local environment, you will need to reload the window for the new tools and custom strong type connections to show up.
+* Step2: Develop a flow with custom tools. Please take this [folder](https://github.com/microsoft/promptflow/blob/431f58ba5f16aaab90768f43a4d9655c4984c0cc/examples/flows/standard/flow-with-package-tool-using-custom-strong-type-connection/) as an example.
+* Step3: Create a custom strong type connection using one of the following methods:
+  - Should the connection type have not been previously created, the 'Add connection' button would appear in the node interface. Click it to generate the connection.
+    ![create_custom_strong_type_connection_in_node_interface](../../media/how-to-guides/develop-a-tool/create_custom_strong_type_connection_in_node_interface.png)
+  - Click 'Create connection' add sign in the CONNECTIONS section.
+    ![create_custom_strong_type_connection_add_sign](../../media/how-to-guides/develop-a-tool/create_custom_strong_type_connection_add_sign.png)
+  - Click 'Create connection' add sign in the Custom category.
+    ![create_custom_strong_type_connection_in_custom_category](../../media/how-to-guides/develop-a-tool/create_custom_strong_type_connection_in_custom_category.png)
+
+  Fill in the `values` starting with `to-replace-with` in the connection template.
+  ![custom_strong_type_connection_template](../../media/how-to-guides/develop-a-tool/custom_strong_type_connection_template.png)
+
+* Step4: Use the created custom strong type connection in your flow and run.
+  ![use_custom_strong_type_connection_in_flow](../../media/how-to-guides/develop-a-tool/use_custom_strong_type_connection_in_flow.png)
+
+## Develop a flow with a script tool with custom strong type connection
+To develop a flow with a script tool that uses a custom strong type connection, follow these steps:
+* Step1: Develop a flow with python script tools. Please take this [folder](https://github.com/microsoft/promptflow/blob/431f58ba5f16aaab90768f43a4d9655c4984c0cc/examples/flows/standard/flow-with-script-tool-using-custom-strong-type-connection/) as an example.
+* Step2: Using a custom strong type connection in a script tool is slightly different from using it in a package tool. When creating the connection, you will create a `CustomConnection`. Fill in the `keys` and `values` in the connection template.
+  ![custom](../../media/how-to-guides/develop-a-tool/custom_connection_template.png)
+* Step3: Use the created custom connection in your flow.
+  ![use_custom_connection_in_flow](../../media/how-to-guides/develop-a-tool/use_custom_connection_in_flow.png)
+
+## Local to cloud
+Whether you are using a custom strong type connection in a package tool or a script tool, when creating the necessary connections in Azure AI, you will need to create a `CustomConnection`. In the node interface of the flow, the input type would be displayed as `CustomConnection` type.
+
+Please refer to [Run prompt flow in Azure AI](https://microsoft.github.io/promptflow/cloud/azureai/quick-start.html) for more details.
+
+Here is an example command:
+```
+pfazure run create --subscription 96aede12-2f73-41cb-b983-6d11a904839b -g promptflow -w my-pf-eus --flow D:\proj\github\ms\promptflow\examples\flows\standard\flow-with-package-tool-using-custom-strong-type-connection --data D:\proj\github\ms\promptflow\examples\flows\standard\flow-with-package-tool-using-custom-strong-type-connection\data.jsonl --runtime test-compute
+```

docs/how-to-guides/develop-a-tool/index.md

@@ -8,4 +8,4 @@ We provide guides on how to develop a tool and use it.
 create-and-use-tool-package
 add-a-tool-icon
 add-category-and-tags-for-tool
-```
+create-your-own-custom-strong-type-connection