Merge pull request #992 from codatio/connection-mgt

Connection management

docs/auth-flow/optimize/connection-management.md

@@ -1,35 +1,55 @@
 ---
 title: "Connection management"
-description: "Learn how to enhance the customer journey when a persistent connection is required"
+description: "Review our guidance on the best practice of providing your clients with control over their existing connections"
+hide_table_of_contents: true
 ---
 
-Connecting is just the beginning of the customer journey. If your use case requires a persistent connection, then it is necessary to allow your customers to manage their ongoing connections. Your customers should feel, and be in control.
+Your customer's journey with us starts when they authorize your access to their data using our auth flow. We then complete the connection to their accounting, banking, or commerce platform. 
 
-:::tip
-Why this matters
+Going forward, your customer should have control over the data they've given you the permission to access. This is key from a regulatory perspective and builds trust between you and your customer. 
+
+To achieve that, provide them with a user interface that lets them manage their ongoing data connections. It could look similar to this:
+
+![An image of three in-app screenshots of a mock connection management UI. The first picture displays a list of three existing connections to Xero, HSBC and Shopify. The second image shows the entry for the Xero connection with details of authorized data and dates the authorization was given. It also lists the option to disconnect the connection. The final image displays a prompt to confirm the decision to disconnect.](/img/auth-flow/auth-flow-connection-ui-examples.png)
+
+:::tip Codat's connection management component
+
+Codat is releasing a low-code embeddable UI component for connection management. Please let us know [here](https://forms.gle/d1zuh2iHBLJCNCsj9) if you are interested in using it.
 
-Your customers need visibility and control over the connections they own. Without the ability to view and update connections, your customers may feel a lack of control and lose trust. This may not directly affect the likelihood of your customers connecting but may affect trust between you and your customer.
 :::
 
-## Allow users to view their live connections
+When working on the user interface, consider including the following functionality to enhance your customer's connection management experience. 
+
+#### Display active connections
 
-In the connection management view, consider showing your customers some or all of the following:
+Include a general connection management view in your application and show your customer some or all of these connection details: 
 
 - Name of the connected platform
 - First sync time and date
-- The most recent sync time and date
-- Sync history
-- Linked data where possible
-- Metadata that will help identify connections i.e. currency of a connected bank account
+- Most recent sync time and date
+- Data sync history
+- Linked data, where possible
+- Metadata that helps identify connections, e.g. currency of a connected bank account
+
+You can add a detailed view for each connection to cover the details that you do not want displayed on the connection list overview.
 
-## Allow users to delete their connections
+#### Unlink or delete connections
 
-Ensure it is obvious how to do delete a connection and revoke access to connected data via your app’s UI.
+Make it easy for your customer to revoke access to their data and delete a connection via your app's UI. When they trigger this request, use our endpoints to action this depending on the requirement:
 
-## Include an option to refresh data
+- [Unlink connection](/platform-api#/operations/unlink-connection) if your customer wants to deauthorize a connection, but still access previously synced data. 
+- [Delete connection](/platform-api#/operations/delete-connection) if your customer wants to revoke access and remove the connection completely. 
 
-Allow your customers to sync new data when it is suitable for your use case.
+#### Trigger data refresh
+
+Optionally, allow your customer to manually initiate a data sync if this is suitable for your use case. Use the [Refresh all data](/platform-api#/operations/refresh-company-data) or [Refresh data type](/platform-api#/operations/refresh-data-type) endpoints to perform the refresh.
+
+#### Show active syncs
+
+Optionally, you can add an indicator to signal that the data is in process of syncing, e.g. a loading spinner animation.
+
+---
 
-## ⭐ Show when the data is actively syncing
+## Read next
 
-Add animation to indicate when data is syncing, e.g. a loading spinner.
+- [Optimize your auth flow](/auth-flow/optimize/optimize-the-connection-journey)

docs/bank-feeds/create-account.md

@@ -253,6 +253,8 @@ fmt.Println(connectionOtpResponse.Connection.LinkUrl)
 
 If your customer wants to revoke their approval and sever the connection to their accounting package, use the [Unlink connection](/bank-feeds-api#/operations/unlink-connection) endpoint.
 
+You can [learn more](/auth-flow/optimize/connection-management) about connection management best practices and see how you can provide this functionality in your app's UI. 
+
 <Tabs>
 
 <TabItem value="nodejs" label="TypeScript">

docs/configure/portal/companies.md

@@ -10,11 +10,12 @@ In the Codat Portal, click **Companies** in the navigation bar to view a list of
 
 From here you can:
 
-- [Add a new company](/configure/portal/companies#add-a-new-company)
-- Copy your [Link URL](/auth-flow/authorize-hosted-link#use-the-hosted-link-url) to allow your customers to share their data through Link
-- [Retrieve Link URLs for existing companies](/auth-flow/authorize-hosted-link#use-the-hosted-link-url) to allow them to authorize additional data connections, or re-authorize unlinked connections where required
-- View details and show the status of existing companies
-- Search for a previously created company by clicking on the search icon
+- [Add a new company](/configure/portal/companies#add-a-new-company).
+- Copy your [Link URL](/auth-flow/authorize-hosted-link#use-the-hosted-link-url) to allow your customers to share their data through Link.
+- [Retrieve Link URLs for existing companies](/auth-flow/authorize-hosted-link#use-the-hosted-link-url) to allow them to authorize additional data connections, or re-authorize unlinked connections where required.
+- View details and show the status of existing companies.
+- Search for a previously created company by clicking on the search icon.
+- Manage the company's existing [connections](/core-concepts/connections).
 - [Delete companies](/configure/portal/companies#delete-a-company).
 
 ## Add a company
@@ -78,5 +79,6 @@ Clicking on a data connection allows you to manage the connection and see any li
 
 Click on a company to access information pertaining to it:
 
-- A brief **Summary** that includes the company's revenue, operating profit, and equity, as well as an activity log
-- Company's **Data**, including the [history of dataset pulls and their statuses](/core-concepts/status), and uploaded files
+- A brief **Summary** that includes the company's revenue, operating profit, and equity, as well as an activity log.
+- The **Manage connections** menu that lets you copy the LInk URL and unlink or delete an existing connection.
+- Company's **Data** and **Data history**, including the [history of dataset pulls and their statuses](/core-concepts/status), and uploaded files.

docs/core-concepts/connections.md

@@ -57,9 +57,11 @@ In the response, note the following fields:
 
 ## Disconnect a data connection to revoke your access to a data source
 
-You can disconnect a data connection using the <a href="/platform-api#/operations/unlink-connection" target="_blank">Unlink connection</a> endpoint. This revokes your access to synchronize data with the linked company and sets the data connection's status to `Unlinked`.
+You can disconnect a data connection using the [Codat Portal](https://app.codat.io/). Navigate to **Companies**, choose the company you want to manage connections for, then select **Manage connections** and use the three-dot menu to unlink the connection. 
 
-To disconnect a data connection, you'll need to provide:
+This revokes your access to synchronize data with the linked company and sets the data connection's status to `Unlinked`.
+
+Alternatively, you can use our <a href="/platform-api#/operations/unlink-connection" target="_blank">Unlink connection</a> endpoint. To disconnect a data connection, you'll need to provide:
 
 - The `companyId` of the linked company as a path parameter.
 - The `connectionId` of the data connection to disconnect as a path parameter.
@@ -224,7 +226,9 @@ var res = await codatPlatform.Connections.UnlinkAsync(new UnlinkConnectionReques
 
 ## Delete a data connection
 
-To delete a data connection, send a request to the <a href="/platform-api#/operations/delete-connection" target="_blank">DELETE /connectionId endpoint</a> and provide the `companyId` and `connectionId` as path parameters.
+You can delete a data connection using the [Codat Portal](https://app.codat.io/). Navigate to **Companies**, choose the company you want to manage connections for, then select **Manage connections** and use the three-dot menu to delete the connection.
+
+Alternatively, you can send a request to the <a href="/platform-api#/operations/delete-connection" target="_blank">DELETE /connectionId endpoint</a> and provide the `companyId` and `connectionId` as path parameters.
 
 <Tabs>
   <TabItem value="curl" label="cURL">

docs/expenses/configure-customer.md

@@ -110,6 +110,8 @@ Use our [Create partner expense connection](/sync-for-expenses-api#/operations/c
 
 If your customer wants to revoke their approval and sever the connection to their accounting package, use the [Unlink connection](/sync-for-expenses-api#/operations/unlink-connection) endpoint.
 
+You can [learn more](/auth-flow/optimize/connection-management) about connection management best practices and see how you can provide this functionality in your app's UI.
+
 ```json
 PATCH /companies/{companyId}/connections/{connectionId}
  {

docs/payables/configure-customer.md

@@ -204,6 +204,8 @@ fmt.Println(connectionResponse.Connection.LinkUrl)
 
 If your customer wants to revoke their approval and sever the connection to their accounting package, use the [Unlink connection](/sync-for-payables-api#/operations/unlink-connection) endpoint.
 
+You can [learn more](/auth-flow/optimize/connection-management) about connection management best practices and see how you can provide this functionality in your app's UI.
+
 <Tabs>
 
 <TabItem value="nodejs" label="TypeScript">

docs/using-the-api/managing-companies.md

@@ -120,7 +120,7 @@ Once your user is redirected to the redirect URL page, they'll be able to author
 
 Occasionally the Data Connections of a Codat company will go into a _deauthorized_ state. This indicates that Codat’s link to the platform is no longer valid, and you will not be able to queue any further data syncs for that connection. You will still be able to query data previously retrieved from the platform.
 
-Data Connections can become _deauthorized_ by the user revoking access within their accounting software or due to platform limitations such as Xero's limited access period for non-partner companies.
+Data Connections can become _deauthorized_ by the user [revoking access](/core-concepts/connections#disconnect-a-data-connection-to-revoke-your-access-to-a-data-source) to their accounting software or due to platform limitations such as Xero's limited access period for non-partner companies.
 
 To enable you to refresh the company's data, you will need to ask the user to complete the auth flow in Link again.
 

sidebars/auth-flow.js

@@ -5,11 +5,12 @@ module.exports = [
     label: "Try it",
     href: "https://sdk-link.vercel.app/",
   },
-   {
+  {
     type: "link",
     label: "See examples",
     href: "https://github.com/codatio/sdk-link/tree/main/examples",
   },
+  "auth-flow/optimize/connection-management",
   {
     type: "category",
     label: "Optimize",
@@ -21,7 +22,6 @@ module.exports = [
       "auth-flow/optimize/value-exchange",
       "auth-flow/optimize/privacy",
       "auth-flow/optimize/platform-selection",
-      "auth-flow/optimize/connection-management",
     ],
   },
   {