Merge pull request #391 from OpenFn/project

New V2 docs on Manage Project and Manage Credentials
OpenFn · Feb 12, 2024 · 21819eb · 21819eb
2 parents ede3809 + 6ef2edd
commit 21819eb
Show file tree

Hide file tree

Showing 15 changed files with 121 additions and 5 deletions.
diff --git a/docs/manage-projects/manage-credentials.md b/docs/manage-projects/manage-credentials.md
@@ -0,0 +1,59 @@
+---
+title: Manage Credentials
+---
+
+You can view the Credentials related to a Project under the Project
+`Settings > Credentials` page. In this article, you'll learn how to manage your
+credentials related to a project.
+
+### View all Project Credentials
+
+Via this `Credentials` page, you can see a list of all Credentials, including
+the name, type, and owner, and whether they are for a production environment.
+
+![Credentials Overview](/img/lightning_credentials_overview.png)
+
+:::info Viewing credential secrets
+
+All Project Collaborators can view the credential name, type, and owner, but
+only the Credential Owner can view the credential secrets (username, password,
+etc.).
+
+:::
+
+### Create a new Credential
+
+1. Click on the `New Credential` button, and choose the type of app you want to
+   connect.
+
+2. If your app is not listed, choose "Raw JSON" to create your own custom
+credential or "configuration" input. For example:
+
+```json
+{ "loginUrl": "https://random-app.com", "username": "test", "password": "pwd" }
+```
+
+![Credential Type](/img/lightning_choose_cred_type.png)
+
+3. Click `Configure Credentials` and add the authentication details for your
+   app. The credential form will indicate which fields are required.
+
+![Add Credential](/img/lightning_add_cred.png)
+
+:::tip Not sure how to fill in all credential details?
+
+While creating a new credential form, if you're not sure what some of these
+fields require (e.g., "security token"), then head over to the relevant
+`Adaptors` docs page to learn more and read about the "configuration schema" or
+ask on [Community](https://community.openfn.org).
+
+:::
+
+3. Click `Save` and you'll see it listed in your `Credentials` page. You can now
+   use it across the Project when building and running Workflows.
+
+![New Credential Ready](/img/lightning_new_cred_ready.png)
+
+### Share Credentials
+
+If you own a Credential, you can choose which Project has access to it. To update which Projects your Credential is shared with, follow the steps on the User Credentials docs page.
diff --git a/docs/manage-projects/platform-mgmt.md b/docs/manage-projects/platform-mgmt.md
@@ -2,8 +2,18 @@
 title: Project Management
 ---
 
-:::warning Under construction
+## What is a Project?
 
-This docs page is under construction. Check back later for the complete docs, or check out the Docs Version "Platform (v1)". 
+A `Project` on OpenFn is a shared workspace for a team or organization that
+contains their Workflows, Credentials and Collaborators scoped to that project.
 
-:::
+## Updating Project Information
+
+You can access your Project's information under `Settings` (see app menu
+sidebar). Setup allows you to view or edit the project name and description.
+
+![Project Overview](/img/lightning_project_overview.png)
+
+You can also export your entire project "as code" - either to save it, or to
+edit your project locally. You can learn more about this feature on our
+[Portability page](/documentation/next/deploy/portability).
diff --git a/docs/manage-projects/user-roles-permissions.md b/docs/manage-projects/user-roles-permissions.md
@@ -33,4 +33,6 @@ When OpenFn Users are invited to work on your Project as `Collaborators`, they a
 | Settings| Change Input/Output Dataclip storage policy  | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |"
 | Settings| Change History retention period  | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |"
 | Settings| Update GitHub project/repo connection  | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |"
-| Settings| Initiate GitHub sync  | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |"
+| Settings| Initiate GitHub sync  | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |"
+
+Contact your app's super admin if you need to add/remove project collaborators or modify a user's role. 
diff --git a/docs/manage-users/user-credentials.md b/docs/manage-users/user-credentials.md
@@ -0,0 +1,42 @@
+---
+title: Manage User Credentials
+sidebar_label: User Credentials
+slug: /user-credentials
+---
+
+You can manage all the Credentials you own under the `Credentials` page of your profile. This article, we'll walk you through how to manage and share the Credentials you own across projects.
+
+### All your Credentials in one place
+
+The `Credentials` page of your `User Settings` allows you to add, view, edit or delete the Credentials you own. It is the central place to manage your Credentials across all projects you collaborate on. 
+
+![User Credential](/img/lightning_user_profile_credentials.png) 
+
+![User Credentials List](/img/lightning_edit_user_credential.png)
+
+For guidance on how to set up a new Credential, head over to our [Manage Credentials](/documentation/next/manage-projects/manage-credentials) page.
+
+You can update the name and login details of a Credential after clicking `Edit`.
+
+![User Credential Edit View](/img/lightning_cred_edit_view.png)
+
+
+### Share Credentials
+
+You can also allow multiple projects to have access to a Credential you own.
+
+To add or remove project access, click `Edit` on the Credential you want to share, and choose the project from the dropdown under `Project Access`.
+
+![Update Project Access](/img/lightning_share_cred_with_project.png)
+
+:::info Shared Credentials remain secret
+
+If you share a Credential with a Project, Collaborators of that Project can _use_ the Credential in their Workflows, but they won't be able to see the login details contained.
+
+:::
+
+:::tip
+
+If you want to share the login details contained in the Credential, use a secure sharing protocol like a password manager or an encrypted messaging platform. 
+
+:::
diff --git a/sidebars-main.js b/sidebars-main.js
@@ -98,14 +98,17 @@ module.exports = {
         'manage-projects/platform-mgmt',
         'manage-projects/retention-periods',
         'manage-projects/io-data-storage',
+        'manage-projects/manage-credentials',
         'manage-projects/user-roles-permissions',
         'manage-projects/notifications',
       ],
     },
     {
       type: 'category',
       label: 'Manage Users & Credentials',
-      items: ['manage-users/user-profile'],
+      items: ['manage-users/user-profile',
+              'manage-users/user-credentials'
+    ],
     },
     {
       type: 'category',

diff --git a/static/img/lightning_add_cred.png b/static/img/lightning_add_cred.png
diff --git a/static/img/lightning_choose_cred_type.png b/static/img/lightning_choose_cred_type.png
diff --git a/static/img/lightning_cred_edit_view.png b/static/img/lightning_cred_edit_view.png
diff --git a/static/img/lightning_credentials_overview.png b/static/img/lightning_credentials_overview.png
diff --git a/static/img/lightning_edit_user_credential.png b/static/img/lightning_edit_user_credential.png
diff --git a/static/img/lightning_new_cred_ready.png b/static/img/lightning_new_cred_ready.png
diff --git a/static/img/lightning_project_overview.png b/static/img/lightning_project_overview.png
diff --git a/static/img/lightning_share_cred_with_project.png b/static/img/lightning_share_cred_with_project.png
diff --git a/static/img/lightning_user_profile_credentials.png b/static/img/lightning_user_profile_credentials.png
diff --git a/static/img/lightning_view_creds_not_edit.png b/static/img/lightning_view_creds_not_edit.png