From 649e1df08e189440b5f1206bcbe529580a2da5e8 Mon Sep 17 00:00:00 2001 From: Matt Conflitti Date: Tue, 12 Aug 2025 14:23:39 -0400 Subject: [PATCH 1/4] docs for integration requests --- docs/{deploying.md => deploying/index.md} | 0 docs/deploying/integration-requests.md | 52 +++++++++++++++++++++++ mkdocs.yml | 4 +- 3 files changed, 55 insertions(+), 1 deletion(-) rename docs/{deploying.md => deploying/index.md} (100%) create mode 100644 docs/deploying/integration-requests.md diff --git a/docs/deploying.md b/docs/deploying/index.md similarity index 100% rename from docs/deploying.md rename to docs/deploying/index.md diff --git a/docs/deploying/integration-requests.md b/docs/deploying/integration-requests.md new file mode 100644 index 00000000..0ec2e764 --- /dev/null +++ b/docs/deploying/integration-requests.md @@ -0,0 +1,52 @@ +Define integration requests for your deployed content by defining `integration_requests` in your content's `manifest.json` file, which can be produced manually or using the [`write-manifest`](../commands/write-manifest.md) command. + +### Integration Request Specification + +During deployment, these integration requests will be processed, and the specified integration specifications will be matched to integrations that are available on the Connect server. If a matching integration is found, it will be used for the deployment. If no matching integration is found, the deployment will fail with an error message indicating that the integration request could not be satisfied. + +| Field | Description | Matching Type | Example | +|-------|-------------|---------------|---------| +| `name` | String identifier for the integration | regex match | `"my-integration"` | +| `description` | Description of the integration | regex match | `"My Azure Integration"` | +| `type` | Integration type | exact match | `"azure"` | +| `guid` | Unique identifier for the integration | exact match | `"123e4567-e89b-12d3-a456-426614174000"` | +| `auth_type` | Authentication type | exact match | `"Viewer"` | +| `config` | Configuration settings for the integration | key-value match | `"{"auth_mode": "Confidential"}"` | + +Possible values for `type` include: +- `azure` +- `azure-openai` +- `sharepoint` +- `msgraph` +- `bigquery` +- `drive` +- `sheets` +- `vertex-ai` +- `databricks` +- `github` +- `salesforce` +- `snowflake` +- `connect` +- `aws` +- `custom` + +Possible values for `auth_type` include: +- `Viewer` +- `Service Account` +- `Visitor API Key` + + +### Example + +```json +{ + // ... + "integration_requests": [ + {"name": "my-integration", "type": "azure"}, + {"name": "another-integration", "type": "aws"}, + {"name": "custom-integration", "type": "custom", "config": {"auth_mode": "Confidential"}}, + {"guid": "123e4567-e89b-12d3-a456-426614174000"} + ] + // ... +} +``` diff --git a/mkdocs.yml b/mkdocs.yml index 96dd18fd..c6bf91a2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,7 +35,9 @@ plugins: nav: - Getting Started: index.md - Programmatic Provisioning: programmatic-provisioning.md - - Deploying Content: deploying.md + - Deployment: + - Deploying Content: deploying/index.md + - Integration Requests: deploying/integration-requests.md - Server Administration: server-administration.md - CLI reference: - rsconnect: From 4a27641213966f0992cc4f3aae7ea559e3e92c06 Mon Sep 17 00:00:00 2001 From: joshyam-k Date: Mon, 18 Aug 2025 16:00:44 -0700 Subject: [PATCH 2/4] small changes to start incorporating feedback --- docs/deploying/integration-requests.md | 62 +++++++++++++++++++++++--- 1 file changed, 57 insertions(+), 5 deletions(-) diff --git a/docs/deploying/integration-requests.md b/docs/deploying/integration-requests.md index 0ec2e764..c6da6eb5 100644 --- a/docs/deploying/integration-requests.md +++ b/docs/deploying/integration-requests.md @@ -1,9 +1,13 @@ -Define integration requests for your deployed content by defining `integration_requests` in your content's `manifest.json` file, which can be produced manually or using the [`write-manifest`](../commands/write-manifest.md) command. +Integration requests streamline your deployment process by automatically associating the necessary OAuth integrations with your content, eliminating the need for manual configuration and ensuring that your deployed content has immediate access to the external services that it depends on. + +You can define integration requests for your content by defining `integration_requests` in your content's `manifest.json` file. The base `manifest.json` file can be produced using the [`write-manifest`](../commands/write-manifest.md) command, but you will need to edit the file by hand to add the `integration_requests`. ### Integration Request Specification During deployment, these integration requests will be processed, and the specified integration specifications will be matched to integrations that are available on the Connect server. If a matching integration is found, it will be used for the deployment. If no matching integration is found, the deployment will fail with an error message indicating that the integration request could not be satisfied. +There are a variety of different fields that can be used within an integration request to reference the desired OAuth integration: + | Field | Description | Matching Type | Example | |-------|-------------|---------------|---------| | `name` | String identifier for the integration | regex match | `"my-integration"` | @@ -35,18 +39,66 @@ Possible values for `auth_type` include: - `Service Account` - `Visitor API Key` +An integration request can contain any combination of the fields listed above, and the correct combination will vary by situation. + +### Examples -### Example +#### Using the integration guid + +If the content will only ever be deployed to a single server, the easiest way to make sure an OAuth integration gets automatically associated with it is by only listing the OAuth integration `guid` in the integration request: + +```json + + // ... + "integration_requests": [ + {"guid": "123e4567-e89b-12d3-a456-426614174000"} + ] + // ... +} +``` + +A Connect administrator can locate the `guid` for an OAuth integration by navigating to **System** > **Integrations** within Connect and then clicking on the desired integration. The `guid` is listed directly beneath the integration name in the resulting popup. + +#### Using the integration name and template + +```json +{ + // ... + "integration_requests": [ + {"name": "my-integration", "type": "azure"} + ] + // ... +} +``` + +#### Using the name, template, and config + +```json +{ + // ... + "integration_requests": [ + {"name": "custom-integration", "type": "custom", "config": {"auth_mode": "Confidential"}} + ] + // ... +} +``` + + +#### Multiple integration requests + +In Posit Connect v2025.07.0 and later, multiple integrations can be associated with a single piece of content. When running this version of Connect, multiple integration requests can be listed in the manifest, and they all will be associated with the content upon deployment. ```json { // ... "integration_requests": [ {"name": "my-integration", "type": "azure"}, - {"name": "another-integration", "type": "aws"}, - {"name": "custom-integration", "type": "custom", "config": {"auth_mode": "Confidential"}}, - {"guid": "123e4567-e89b-12d3-a456-426614174000"} + {"name": "another-integration", "type": "aws"} ] // ... } ``` + +### Deploying from manifest + +Once the integration requests have been specified in the `manifest.json`. A publisher will need to use the `rsconnect deploy manifest` command in order for the auto-association to take place. See `rsconnect deploy manifest --help` for more details on deploying from manifest. From cb8b70a9bdbba65fc9a15bdac526dd748ac927a5 Mon Sep 17 00:00:00 2001 From: joshyam-k Date: Tue, 19 Aug 2025 08:49:01 -0700 Subject: [PATCH 3/4] fix formatting --- docs/deploying/integration-requests.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/deploying/integration-requests.md b/docs/deploying/integration-requests.md index c6da6eb5..d79b70bf 100644 --- a/docs/deploying/integration-requests.md +++ b/docs/deploying/integration-requests.md @@ -1,4 +1,4 @@ -Integration requests streamline your deployment process by automatically associating the necessary OAuth integrations with your content, eliminating the need for manual configuration and ensuring that your deployed content has immediate access to the external services that it depends on. +Integration requests streamline your deployment process by automatically associating the necessary OAuth integrations with your content, eliminating the need for manual configuration and ensuring that your deployed content has immediate access to the external resources that it depends on. You can define integration requests for your content by defining `integration_requests` in your content's `manifest.json` file. The base `manifest.json` file can be produced using the [`write-manifest`](../commands/write-manifest.md) command, but you will need to edit the file by hand to add the `integration_requests`. @@ -18,6 +18,7 @@ There are a variety of different fields that can be used within an integration r | `config` | Configuration settings for the integration | key-value match | `"{"auth_mode": "Confidential"}"` | Possible values for `type` include: + - `azure` - `azure-openai` - `sharepoint` @@ -35,6 +36,7 @@ Possible values for `type` include: - `custom` Possible values for `auth_type` include: + - `Viewer` - `Service Account` - `Visitor API Key` @@ -45,7 +47,7 @@ An integration request can contain any combination of the fields listed above, a #### Using the integration guid -If the content will only ever be deployed to a single server, the easiest way to make sure an OAuth integration gets automatically associated with it is by only listing the OAuth integration `guid` in the integration request: +If the content will only ever be deployed to a single server, the easiest way to make sure the correct OAuth integration gets automatically associated is by listing the OAuth integration `guid` in the integration request: ```json @@ -75,11 +77,17 @@ A Connect administrator can locate the `guid` for an OAuth integration by naviga ```json { - // ... - "integration_requests": [ - {"name": "custom-integration", "type": "custom", "config": {"auth_mode": "Confidential"}} - ] - // ... + // ... + "integration_requests": [ + { + "name": "custom-integration", + "type": "custom", + "config": { + "auth_mode": "Confidential" + } + } + ] + // ... } ``` From bc0de3f39b5681eb796ed8234be317f05bac2766 Mon Sep 17 00:00:00 2001 From: joshyam-k Date: Tue, 19 Aug 2025 10:13:39 -0700 Subject: [PATCH 4/4] remove version mention --- docs/deploying/integration-requests.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deploying/integration-requests.md b/docs/deploying/integration-requests.md index d79b70bf..b32341d0 100644 --- a/docs/deploying/integration-requests.md +++ b/docs/deploying/integration-requests.md @@ -94,7 +94,7 @@ A Connect administrator can locate the `guid` for an OAuth integration by naviga #### Multiple integration requests -In Posit Connect v2025.07.0 and later, multiple integrations can be associated with a single piece of content. When running this version of Connect, multiple integration requests can be listed in the manifest, and they all will be associated with the content upon deployment. +Multiple integration requests can be listed in the manifest, and they all will be associated with the content upon deployment. ```json {