diff --git a/docs/build/troubleshooting.md b/docs/build/troubleshooting.md index 388b4cc9503..a037e57e09c 100644 --- a/docs/build/troubleshooting.md +++ b/docs/build/troubleshooting.md @@ -3,13 +3,18 @@ title: Troubleshooting integrations sidebar_label: Troubleshooting --- -Or, a penny for your thoughts during the debugging process. - - - So, you've noticed that something isn't quite right. Here's a list of questions, and complications, that might help you get to the bottom of it. +:::tip + +Check out the [Troubleshooting page](../monitor-history/troubleshooting.md) in +the "Monitor History" section for more specific tips and common errors. + +::: + + + ## The Implementation Perspective First, keep this quick checklist at hand... answering these questions _in order_ diff --git a/docs/manage-projects/link-to-gh.md b/docs/manage-projects/link-to-gh.md new file mode 100644 index 00000000000..1e046475511 --- /dev/null +++ b/docs/manage-projects/link-to-gh.md @@ -0,0 +1,58 @@ +--- +title: Linking Your Project to GitHub (Version Control) +sidebar_label: Linking Your Project to GitHub +slug: /link-to-github +--- + +You can set up version control for your OpenFn projects. This article walks you +through the configuration steps. + +### Setting up GitHub integration + +You can connect your OpenFn project to a GitHub repository that you have +administrator access to. This enables a 2-way sync - you can sync your project +to GitHub, and you can deploy changes you've made outside of OpenFn to your +project. + +1. Navigate to `Project Settings > Sync to GitHub` . + +![Connect to GitHub](/img/lightning_connect_to_gh.png) + +2. Select `Connect Branch`. You'll be prompted to sign in to GitHub. + +Click `Configure`... + +![Configure](/img/lightning_gh_configure.png) + +3. ...then select the GitHub account that owns the repository you want to + connect to. + +![Install](/img/lightning_gh_install_openfn.png) + +4. Select the repository to sync with and hit `Save`. + +![Permissions](/img/lightning_gh_permissions.png) + +5. You'll be redirected to OpenFn. Select the repository and branch you want to + sync to, and click `Connect Branch`. + +6. Your GitHub connection is now set up! From here, each time you want to sync + between your project and GitHub, click `Initiate Sycn to Branch`. + +### How It Works in a Nutshell + +Your whole OpenFn project can be represented as a project.yaml file. + +Using our Command Line Interface, the +[@openfn/cli](../deploy/portability.md) +you can pull a project config from OpenFn to a folder or repo on your computer, +and you can deploy a change in your project.yaml file from that directory or +repo to OpenFn. + +The `Sync to Github` feature makes use of GitHub actions to automatically deploy +(after a commit) or pull (when `Initiate Sync to Branch` button is clicked) to +keep a repository in sync with your OpenFn project. + +For more detailed information on representing your project as code and using the +@openfn/cli, head over to our documentation on +[Portability](../deploy/portability.md). diff --git a/docs/manage-projects/notifications.md b/docs/manage-projects/notifications.md index e6d67fae83c..5927e507bbf 100644 --- a/docs/manage-projects/notifications.md +++ b/docs/manage-projects/notifications.md @@ -1,28 +1,42 @@ --- title: Failure Notifications and Digests -sidebar_label: Notifications +sidebar_label: Email Notifications +slug: /notifications --- If you would like to receive email `Notifications` when a Workflow Run fails or emailed summary `Digests` on activity across your project, read on to learn how to configure your project settings accordingly. -## How to turn on email notifications for Run failures +This article walks you through how to set up email notifications to monitor your +workflows. -1. Go to your Project `Settings` > `Collaboration` page -2. Find your User -3. In the `Failure Alert` dropdown, choose `Enabled` to turn on real-time email - notifications for Run failures +### Failure Alerts -![Notifications Config](/img/notifications.png) +You can enable failure alerts to receive email notifications when a job fails +under `Project Settings > Collaboration`. -## How to turn on email notifications for Run failures +![Failure Alert](/img/lightning_failure_alert.png) -1. Go to your Project `Settings` > `Collaboration` page -2. Find your User -3. In the `Digest` dropdown, choose desired notification frequency (`Daily`, - `Weekly`,`Monthly`, or `Never` ) if you would also like to receive a summary - of Work Order activity and success rates across your project. See below - screenshot for an example digest. +The email notification includes the logs and a link to the failed run that you +can inspect and begin troubleshooting. -![Digest Email](/img/digest_email.png) +![Failure Email](/img/lightning_failure_email.png) + +![Failure Run](/img/lightning_failed_run.png) + +### Email Digests + +Also in `Project Settings > Collaboration`, you can choose to receive daily, +weekly or monthly email digests from a project, summarizing successful and +failed runs for each of your workflows. + +![Digest Email Setting](/img/lightning_digest.png) + +![Digest Email](/img/lightning_weekly_digest.png) + +:::note + +If you want to adjust your notifications settings and you are a Collaborator on more than 1 Project, then you will need to go to the `Project Settings > Collaboration` page for _each_ Project you belong to. + +::: diff --git a/docs/manage-users/api-tokens.md b/docs/manage-users/api-tokens.md new file mode 100644 index 00000000000..470464a96a5 --- /dev/null +++ b/docs/manage-users/api-tokens.md @@ -0,0 +1,35 @@ +--- +title: Create and Manage API Tokens +sidebar_label: API Tokens +slug: /api-tokens +--- + +This article shows you how to create a personal access API token. + +### About API Tokens + +OpenFn provides API permission for users to build or interact with their project +on the platform via the API. You need a Personal Access Token to be able to +access the platform via the API. You can find out more about creating or +updating your project programmatically, visit our +[Portability](../deploy/portability.md) +page. + +Your API access provides you the same level of permission as you have as a user +on OpenFn (for example, if your profile has Admin level access, your API user +will also have Admin permissions). + +### Creating an API token + +You can manage your tokens in your User Profile. + +![API Tokens Profile](/img/lightning_user_profile_api_tokens.png) + +![API Tokens](/img/lightning_no_api_token.png) + +1. Click `Generate New Token` to create a new one. + +![New Token](/img/lightning_new_api_token.png) + +2. Make sure you copy your new token right away. You won't be able to view or + copy it later. diff --git a/docs/manage-users/user-credentials.md b/docs/manage-users/user-credentials.md index bb92bda8eb1..d30ac3fd41a 100644 --- a/docs/manage-users/user-credentials.md +++ b/docs/manage-users/user-credentials.md @@ -14,7 +14,7 @@ The `Credentials` page of your `User Settings` allows you to add, view, edit or ![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/manage-projects/manage-credentials) page. +For guidance on how to set up a new Credential, head over to our [Manage Credentials](../manage-projects/manage-credentials.md) page. You can update the name and login details of a Credential after clicking `Edit`. diff --git a/docs/manage-users/user-profile.md b/docs/manage-users/user-profile.md index b7d2b5f8655..8968535e9aa 100644 --- a/docs/manage-users/user-profile.md +++ b/docs/manage-users/user-profile.md @@ -3,10 +3,38 @@ title: Update User Profile sidebar_label: User Profile slug: /user-profile --- -:::warning Under construction -This docs page is under construction. Check back later for the complete docs, or check out the Docs Version "Platform (v1)". +This article walks you through how to view and update your user information in +your User Profile. -::: +![User Profile](/img/lightning_select_user_profile.png) - \ No newline at end of file +### Change Email and Password + +You can change the email address associated with your Profile, and update your +password. + +![Change Email Password](/img/lightning_change_email_pw.png) + +### Enable Multi-Factor Authentication + +By enabling Multi-Factor Authentication, you can add an additional layer of +security to your account by requiring more than just a password for logging in. + +![Enable MFA](/img/lightning_enable_MFA.png) + +You can link your account to an authenticator app or a browser extension like +1Password or Authy. Once configured, the app will generate a one-time password +for you to provide during sign-in to verify your identity at each login. + +To configure multi-factor authentication, use an authenticator app or browser +extension to scan the QR code found on your profile. + +Alternatively, you can provide the secret key generated on your profile to the +app to set it up. + +### Account Deletion + +Your User Profile is also the place where you can delete your OpenFn account. + +![Delete Account](/img/lightning_delete_account_cropped.png) diff --git a/docs/monitor-history/inspect-runs.md b/docs/monitor-history/inspect-runs.md index e9532e89b0a..e63b28fa78e 100644 --- a/docs/monitor-history/inspect-runs.md +++ b/docs/monitor-history/inspect-runs.md @@ -3,13 +3,13 @@ title: Inspect Runs & Search via the History page sidebar_label: Inspect Runs --- -A [Run](/documentation/get-started/terminology#run) is created each time +A [Run](../get-started/terminology.md#run) is created each time OpenFn attempts to excute a Workflow for a given Work Order. All Runs can be viewed, filtered, and searched via the `History` page. In short, Runs tell us "what happened" when OpenFn tried to execute the Workflow. Runs have start times, end times, logs, and -[status codes](/documentation/monitor-history/status-codes) that indicate +[status codes](./status-codes.md) that indicate when they took place, what they did, and whether or not they succeeded. ## Inspect Runs @@ -26,4 +26,4 @@ To learn how to search and filter Work Order and Run history via the History page, check out the below video tutorial ([or see link](https://youtu.be/XIUykmLCxwQ?si=pCzefw4zyLxG1voE)). - + diff --git a/docs/monitor-history/troubleshooting.md b/docs/monitor-history/troubleshooting.md index 7c6b27214f1..26b54d3fc59 100644 --- a/docs/monitor-history/troubleshooting.md +++ b/docs/monitor-history/troubleshooting.md @@ -8,14 +8,14 @@ This page provides troubleshooting tips for *OpenFn v2 platform* users. ## Runs One of the most helpful pages for troubleshooting on OpenFn is the -[History](/documentation/monitor-history/activity-history) page. -This page provides a list of all of the runs executed for a Work Order and their status. Project administrators can troubleshoot errors by clicking into the run to review the run details. Learn more about runs [here](/documentation/monitor-history/inspect-runs) here. +[History](./activity-history.md) page. +This page provides a list of all of the runs executed for a Work Order and their status. Project administrators can troubleshoot errors by clicking into the run to review the run details. Learn more about runs [here](./inspect-runs.md) here. ### Status codes Every run will have a status code. The status code is a way for OpenFn to classify the run status and can help you troubleshoot errors. Learn more about OpenFn -status codes and what each one means [here](/documentation/monitor-history/status-codes). +status codes and what each one means [here](./status-codes.md). ### The time it took for the workflow to fail @@ -89,7 +89,7 @@ Check out this [video](https://youtu.be/XIUykmLCxwQ?si=hquc8rPTJrAZkbbD) for how ## Sign up for email alerts -You can turn on notifications to receive [email alerts](/documentation/manage-projects/notifications) when a workflow fails and subscribe to digests that summarize project activity. +You can turn on notifications to receive [email alerts](../manage-projects/notifications.md) when a workflow fails and subscribe to digests that summarize project activity. ## More diff --git a/sidebars-main.js b/sidebars-main.js index 79041260aa3..856a6c12911 100644 --- a/sidebars-main.js +++ b/sidebars-main.js @@ -103,12 +103,17 @@ module.exports = { 'manage-projects/manage-credentials', 'manage-projects/user-roles-permissions', 'manage-projects/notifications', + 'manage-projects/link-to-gh', ], }, { type: 'category', label: 'Manage Users & Credentials', - items: ['manage-users/user-profile', 'manage-users/user-credentials'], + items: [ + 'manage-users/user-profile', + 'manage-users/user-credentials', + 'manage-users/api-tokens', + ], }, { type: 'category', diff --git a/static/img/lightning_change_email_pw.png b/static/img/lightning_change_email_pw.png new file mode 100644 index 00000000000..5ac732630cd Binary files /dev/null and b/static/img/lightning_change_email_pw.png differ diff --git a/static/img/lightning_connect_to_gh (1).png b/static/img/lightning_connect_to_gh (1).png new file mode 100644 index 00000000000..db0129f4b20 Binary files /dev/null and b/static/img/lightning_connect_to_gh (1).png differ diff --git a/static/img/lightning_connect_to_gh.png b/static/img/lightning_connect_to_gh.png new file mode 100644 index 00000000000..db0129f4b20 Binary files /dev/null and b/static/img/lightning_connect_to_gh.png differ diff --git a/static/img/lightning_delete_account_cropped.png b/static/img/lightning_delete_account_cropped.png new file mode 100644 index 00000000000..3bebde18ab1 Binary files /dev/null and b/static/img/lightning_delete_account_cropped.png differ diff --git a/static/img/lightning_digest.png b/static/img/lightning_digest.png new file mode 100644 index 00000000000..419d7b59585 Binary files /dev/null and b/static/img/lightning_digest.png differ diff --git a/static/img/lightning_enable_MFA.png b/static/img/lightning_enable_MFA.png new file mode 100644 index 00000000000..50aa87074dc Binary files /dev/null and b/static/img/lightning_enable_MFA.png differ diff --git a/static/img/lightning_failed_run.png b/static/img/lightning_failed_run.png new file mode 100644 index 00000000000..350116f7bc1 Binary files /dev/null and b/static/img/lightning_failed_run.png differ diff --git a/static/img/lightning_failure_alert.png b/static/img/lightning_failure_alert.png new file mode 100644 index 00000000000..cc82afb2a4c Binary files /dev/null and b/static/img/lightning_failure_alert.png differ diff --git a/static/img/lightning_failure_email.png b/static/img/lightning_failure_email.png new file mode 100644 index 00000000000..cb15ac8122d Binary files /dev/null and b/static/img/lightning_failure_email.png differ diff --git a/static/img/lightning_gh_configure.png b/static/img/lightning_gh_configure.png new file mode 100644 index 00000000000..dc8555f55f0 Binary files /dev/null and b/static/img/lightning_gh_configure.png differ diff --git a/static/img/lightning_gh_install_openfn.png b/static/img/lightning_gh_install_openfn.png new file mode 100644 index 00000000000..918ea2c9c09 Binary files /dev/null and b/static/img/lightning_gh_install_openfn.png differ diff --git a/static/img/lightning_gh_permissions.png b/static/img/lightning_gh_permissions.png new file mode 100644 index 00000000000..b2b4e909efe Binary files /dev/null and b/static/img/lightning_gh_permissions.png differ diff --git a/static/img/lightning_new_api_token.png b/static/img/lightning_new_api_token.png new file mode 100644 index 00000000000..82400e9bd94 Binary files /dev/null and b/static/img/lightning_new_api_token.png differ diff --git a/static/img/lightning_no_api_token (1).png b/static/img/lightning_no_api_token (1).png new file mode 100644 index 00000000000..8c2bbae39d0 Binary files /dev/null and b/static/img/lightning_no_api_token (1).png differ diff --git a/static/img/lightning_no_api_token.png b/static/img/lightning_no_api_token.png new file mode 100644 index 00000000000..8c2bbae39d0 Binary files /dev/null and b/static/img/lightning_no_api_token.png differ diff --git a/static/img/lightning_openfn_select_repo_branch.png b/static/img/lightning_openfn_select_repo_branch.png new file mode 100644 index 00000000000..07709ef4ed9 Binary files /dev/null and b/static/img/lightning_openfn_select_repo_branch.png differ diff --git a/static/img/lightning_select_user_profile.png b/static/img/lightning_select_user_profile.png new file mode 100644 index 00000000000..908d168f766 Binary files /dev/null and b/static/img/lightning_select_user_profile.png differ diff --git a/static/img/lightning_user_profile_api_tokens.png b/static/img/lightning_user_profile_api_tokens.png new file mode 100644 index 00000000000..ff158492b36 Binary files /dev/null and b/static/img/lightning_user_profile_api_tokens.png differ diff --git a/static/img/lightning_weekly_digest.png b/static/img/lightning_weekly_digest.png new file mode 100644 index 00000000000..37454d6d236 Binary files /dev/null and b/static/img/lightning_weekly_digest.png differ