From 5b0b9f0284cc84cb2de6d73d30a03222b5165fd2 Mon Sep 17 00:00:00 2001 From: Jonathon Broughton <760691+jsdbroughton@users.noreply.github.com> Date: Mon, 2 Dec 2024 18:19:24 +0000 Subject: [PATCH] Automate Public Beta changes (#255) * Update README.md * change to main server * Update important-caveats.md * Update getting-started.md * Update for-automate-composers.md * Update viewing-results.md * Update viewing-results.md * Update for-automate-composers.md * Create for-automate-users.md Reflects the simplification of language * Update config.js * Delete automate/for-automate-composers.md * Update for-function-authors.md * Update create-automation.md * Update update-automation.md * Update config.js * Create public-functions * Create public-functions.md * Delete automate/public-functions * Update public-functions.md * Update public-functions.md * Update public-functions.md * Update public-functions.md * Update for-function-authors.md * Update create-function.md * Update function-testing.md * Update documenting.md * Update release-function-version.md * Update release-function-version.md * Update demos.md * Update demos.md * Update feedback.md * Update roadmap.md * Update roadmap.md * Update troubleshooting.md * Update known-issues.md * Update frequently-asked-questions.md * Update config.js * Update public-functions.md * Update viewing-results.md * Update release-function-version.md * Update troubleshooting.md --- .vuepress/config.js | 10 +- automate/README.md | 15 +- automate/create-automation.md | 82 +++++------ automate/create-function.md | 121 ++++++++-------- automate/demos.md | 23 +++- automate/documenting.md | 30 +++- automate/feedback.md | 46 +++++-- automate/for-automate-composers.md | 33 ----- automate/for-automate-users.md | 44 ++++++ automate/for-function-authors.md | 25 ++-- automate/frequently-asked-questions.md | 153 ++++++++------------- automate/function-testing.md | 182 +++++++++++-------------- automate/getting-started.md | 21 +-- automate/important-caveats.md | 34 ++++- automate/known-issues.md | 17 ++- automate/public-functions.md | 69 ++++++++++ automate/release-function-version.md | 61 ++++++--- automate/roadmap.md | 60 +++++--- automate/troubleshooting.md | 24 ++-- automate/update-automation.md | 13 +- automate/viewing-results.md | 65 ++++----- 21 files changed, 654 insertions(+), 474 deletions(-) delete mode 100644 automate/for-automate-composers.md create mode 100644 automate/for-automate-users.md create mode 100644 automate/public-functions.md diff --git a/.vuepress/config.js b/.vuepress/config.js index 11d5873e..2450fec3 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -261,22 +261,22 @@ module.exports = { title: 'Core Functionalities', collapsable: true, children: [ - 'for-automate-composers', - 'viewing-results', + 'for-automate-users', 'for-function-authors', ], }, ], }, { - title: 'Working with Automations', + title: 'Automations', collapsable: false, - children: ['create-automation', 'update-automation'], + children: ['create-automation', 'update-automation', 'viewing-results'], }, { - title: 'Developing Functions', + title: 'Functions', collapsable: false, children: [ + 'public-functions', 'create-function', 'making-your-function', 'function-testing', diff --git a/automate/README.md b/automate/README.md index c07c1d67..03edae60 100644 --- a/automate/README.md +++ b/automate/README.md @@ -1,10 +1,15 @@ -# Speckle Automate Beta -::: tip 🚧 NOTE -Speckle Automate is in an accessible beta phase and restricted to the Speckle development server. These docs are a work in progress and are updated regularly. +# Speckle Automate Public Beta +::: tip 🚧 NOTE +Speckle Automate has entered the public beta phase and is now available on the Speckle production server: [app.speckle.systems](https://app.speckle.systems). These docs are a work in progress and are updated regularly to reflect the latest features and improvements. ::: +This documentation is designed to assist Speckle Automate users in creating and managing automation. As a Speckle user, you can now act as an **Automator**, leveraging public functions and creating custom workflows to streamline tasks and enhance productivity. -This mini documentation is designed to assist beta testers of Speckle Automate, focusing on the **Function Author** and **Automation Composer** personas. Your feedback is essential in refining these roles within the platform, enhancing functionality, and ensuring a user-friendly experience. +### Key Highlights: +- **Public Functions**: Available to all users on [app.speckle.systems](https://app.speckle.systems). +- **Private Functions**: Creatable and manageable within Workspaces. +- **Unified Hosting**: All data, functions, and automations are hosted on the main Speckle server. +- **Collaboration**: Workspace members can use public and private functions to create automations collaboratively. -We will continuously improve these documentation details as things develop; there may be occasions when development outpaces the documentation. If you have any questions, please reach out to us on the [Speckle Community Forum: Automate](https://speckle.community/c/making-speckle/insiders-automate/27). \ No newline at end of file +We are continuously improving the documentation. As Speckle Automate evolves, there may be occasions when development temporarily outpaces the documentation. If you have any questions, please contact us on the [Speckle Community Forum: Automate](https://speckle.community/c/making-speckle/insiders-automate/27). diff --git a/automate/create-automation.md b/automate/create-automation.md index 5b1a233d..bfe82a8f 100644 --- a/automate/create-automation.md +++ b/automate/create-automation.md @@ -2,54 +2,42 @@ ## **What is an Automation?** -- Automations allow you to achieve a wide variety of tasks. -- Automations are what apply a function to a Speckle model. -- Automations are used to configure a function to suit your particular requirements. +- Automations allow you to perform a wide variety of tasks efficiently. +- Automations apply a function to a Speckle model. +- Automations enable you to configure a function to meet your specific requirements. -For example, a function may render a photograph-quality image of any given model. An automation allows you to specify the camera position, lighting, and other settings to achieve the desired result, and then command the function to render an image of your particular Speckle model. +For example, a function might render a photograph-quality image of a model. Automation allows you to specify parameters such as the camera position, lighting, and other settings to customise the output for your particular Speckle model. ## **Creating an Automation** -Automations are created from two contexts: - -1. 1. In the context of a project, found under the Automations tab. - - ![the automations tab](./img/automations-tab.png) - -2. From the functions library - - ![alt text](./img/function-library-card.png) - - -The resulting modal dialog will present you with four or five prompt screens: - -1. If you started from an automations list, **select a function to use** and click Next. - - ![create automation](./img/create-automation.png) - - ![selected function](./img/selected-function.png) - -2. If you start from the Functions library or a Function page, you will go directly to step 3. -3. If the function has defined inputs to configure it, **set parameters** now. - - ![parameter configuration](./img/configuration.png) - -4. **Add Automation Details** - 1. If you started the automation from the project page, this is already selected for you; otherwise, you will need to choose which Speckle project and model will trigger your automation. - - ![set parameters](./img/set-parameters.png) - - 2. **Choose a Speckle Model from the current project** - - ![choose a model](./img/choose-model.png) - - 3. **Name your automation**. This is for your reference; ideally, make it meaningful, but it doesn’t need to be unique. - - ![alt text](./img/automation-name.png) - - -5. Create your Automation - - ![create!](./img/create-button.png) - -6. **Success**! 🥳 You can now view your automation. \ No newline at end of file +Automations are created from the **Automations** tab within a project. + +![the automations tab](./img/automations-tab.png) + +::: tip 💡 **Function Availability** +The library view includes both public functions and any private functions created for the Workspace if the project is a Workspace project created for your team. This ensures all team-specific and public resources are accessible during automation setup. +::: + +### Steps to Create an Automation + +1. **Select a Function** + - Choose a function from the list in the Automations tab and click **Next**. + ![create automation](./img/create-automation.png) + ![selected function](./img/selected-function.png) + +2. **Set Parameters** + - If the function has defined inputs, configure them now. + ![parameter configuration](./img/configuration.png) + +3. **Add Automation Details** + - **Choose a Speckle Model**: Select a model from the current project that will trigger your automation. + ![choose a model](./img/choose-model.png) + - **Name Your Automation**: Provide a meaningful name for reference (uniqueness is not required). + ![alt text](./img/automation-name.png) + +4. **Create Your Automation** + - Click **Create** to finalise the setup. + ![create!](./img/create-button.png) + +5. **Success!** 🥳 + - Your automation is now ready to view and manage. diff --git a/automate/create-function.md b/automate/create-function.md index f3dfe5b9..e227f16c 100644 --- a/automate/create-function.md +++ b/automate/create-function.md @@ -1,62 +1,69 @@ # Creating Functions -If you have your verified account on latest.speckle.systems, navigate to [latest.speckle.systems/functions](https://latest.speckle.systems/functions). - -You will now see above the Functions Library. In the top right, there is a new function button: +If you have a verified account on [app.speckle.systems](https://app.speckle.systems), navigate to [app.speckle.systems/functions](https://app.speckle.systems/functions). +You will see the Functions Library. In the top right, there is a **New Function** button: ![new function button](./img/new-function-button.png) -This will launch the function creation wizard - -1. **Authorise GitHub:** Required only the first time. - - ![authorise github](./img/authorise-github.png) - - ::: tip 💡 Authorized OAuth Apps - You will find Speckle Automate in your Github account Authorized OAuth Apps. Access can be revoked at any time, but will be necessary to publish new functions. - - ![alt text](./img/authorised-applications.png) - - ::: - -2. **Choose a template**: We are launching with Python and C# templates. These reflect our best-supported Speckle SDKs, **speckle-sharp** and **specklepy**. Each of our main SDKs includes the Automate SDK for that language. -3. **Define your function.** (Some of these details can be edited later) - 1. **Choose an avatar/logo/icon** [optional]: This will be displayed in the functions list - 2. **Choose a Name** [required]: This doesn’t need to be unique, but all functions will be a single list during the beta stages. The search filter will use the function name alone; it could be helpful if it identifies you as an author/company and the name/function intent. *e.g. SolarFarmLayout by Solarcorp* - 3. **Add a description** [required]: This will be the short description used in the function list. The description supports basic Markdown if you wish to add markup. - 4. **Identify source application data supported** [optional]: This may be helpful when defining Automations - 5. **Add Tags** [optional]: A list of terms to categorise your function further. Multi-word tags should use _ or - characters. *e.g. Solar_Panels* - 6. **~~Select a Github Organization** [optional]: This is only relevant if you want to publish as an organization and are a member of one.~~ - 7. **Click Next**: All being well, the wizard will create your function project on GitHub. - - ::: tip 🧙‍♂️ Wizard Actions - You will see that the wizard handles a lot of scaffolding for you. You can navigate to GitHub and see that the template project has been cloned under your repositories: - - ![alt text](./img/repo-title.png) - - A GitHub action has been created for you; the specification for it is defined in `.github/workflows/**main.yml**` - - ![alt text](./img/build-and-deploy.png) - - It also has injected two environmental variables as repository secrets for the interaction with the Automate API `SPECKLE_FUNCTION_ID` and `SPECKLE_FUNCTION_TOKEN`: - - ![alt text](./img/repo-secrets.png) - - - ::: - - ::: tip 💡 Note - Choose whatever Project restrictions you wish, but it must be Public for now. - ::: - - - -4. Your function has been created! 🥳 At this point, the template can be edited and amended to suit your own business logic. - - ![alt text](./img/function-created.png) - -5. You can follow the links provided to: - 1. **Open the repo:** this is a link to the project on GitHub - 2. **Open in codespace:** You can get coding immediately in a virtual machine operating in a container at GitHub. Remember that any changes you make must be pushed to your project. - 3. **Go to function**: This will navigate you to your functions page within Speckle Automate. -6. Your function will only appear in the [functions list](https://automate.speckle.dev/functions) once a first Release has been made. \ No newline at end of file +This launches the function creation wizard. + +--- + +## Steps to Create a Function + +1. **Authorise GitHub** + Required only the first time. + ![authorise github](./img/authorise-github.png) + + ::: tip 💡 **Authorized OAuth Apps** + Speckle Automate will appear under your GitHub account's Authorized OAuth Apps. Access can be revoked at any time but will be necessary to publish new functions. + ![authorised applications](./img/authorised-applications.png) + ::: + +2. **Choose a Template** + We currently offer Python and C# templates, reflecting our best-supported SDKs (**specklepy** and **speckle-sharp**). Each includes the Automate SDK for its respective language. + +3. **Define Your Function** + Some details can be edited later: + - **Avatar/Logo/Icon** [optional]: Displayed in the functions list. + - **Name** [required]: Does not need to be unique. Use a descriptive name to help identify the function and its purpose, e.g., `SolarFarmLayout by SolarCorp`. + - **Description** [required]: A short Markdown-supported description used in the functions list. + - **Source Application Data Supported** [optional]: Indicate which source applications your function is designed for. + - **Tags** [optional]: You can further categorise your function with single or multi-word tags, e.g., `Solar_Panels`. + - **Click Next**: The wizard will create your function project on GitHub. + + ::: tip 🧙‍♂️ **Wizard Actions** + The wizard handles scaffolding for you: + - Clones the template project into your repositories. + ![repo-title](./img/repo-title.png) + - Creates a GitHub action (`.github/workflows/main.yml`) for build and deployment. + ![build-and-deploy](./img/build-and-deploy.png) + - Injects API interaction environment variables (`SPECKLE_FUNCTION_ID` and `SPECKLE_FUNCTION_TOKEN`). + ![repo-secrets](./img/repo-secrets.png) + ::: + +4. **Repository Management** + The function wizard creates a GitHub repository under your account. + - **Public vs Private**: Whether to keep this repository public or private depends on your team's open-source or source-available development approach. Speckle Automate supports both public and private repositories. + - **Personal or Organisational Accounts**: Depending on your setup and collaboration needs, you can publish functions from either your personal GitHub account or an organisation's account. + + ::: tip 💡 **Important** + Carefully manage repository access based on your team's workflows and requirements. + ::: + +5. **Finalise Your Function** + Once created, the function template can be edited and tailored to your business logic. + ![function-created](./img/function-created.png) + +6. **Next Steps** + From the success page, you can: + - **Open the Repository**: View the project on GitHub. + - **Open in Codespace**: Start coding immediately in a virtual environment. Remember to push changes back to GitHub. + - **Go to Function**: Navigate to your function’s page within Speckle Automate. + +7. **Make a Release** + After making the first release on GitHub, your function will only appear in the Functions Library. + +--- + +With these steps, your function is ready for further development, automation, and collaboration! diff --git a/automate/demos.md b/automate/demos.md index efb0168f..e84aaf25 100644 --- a/automate/demos.md +++ b/automate/demos.md @@ -3,14 +3,27 @@ ### SpeckleCon 2023 Announcement [Introducing Speckle Automate 🤖 - SpeckleCon 2023](https://youtu.be/6_rXXGpnfb4) -### Our mission for Automate blog post +### Our Mission for Automate Blog Post [Automate with Speckle](https://speckle.systems/blog/automate-with-speckle/) ### Function Demonstrations from SpeckleCon 2023 - [Speckle Automate DEMOS 🔥 - SpeckleCon 2023](https://youtu.be/BuyUvIVUO2g) -### Demo functions for use in Automate -All our demo functions are listed as featured functions in the functions library. Most have been updated with the changes to the SDKs behind the scenes since SpeckleCo but we're working on this and also adding new functions all the time. +## Public Functions: Fully Functional Demonstrations + +Public functions in the Speckle Automate Functions Library are designed to serve as both fully functional solutions and practical demonstrations of how Speckle Automate can be used effectively. They are: + +- Ready-to-use in real-world workflows. +- Examples of how to structure functions using Speckle SDKs. +- Starting points for creating custom functions tailored to specific needs. + +These functions reflect Speckle Automate's flexibility and power, offering users immediate value and insights into best practices. + +## Demo Functions for Use in Automate + +Speckle-authored demo functions are continually updated to reflect changes to the SDKs and expand functionality. While not all demo functions are available in the Functions Library, all Speckle-authored functions are published to GitHub alongside our open-source repositories. + +These functions are typically namespaced under `speckle-automate-*` to facilitate discovery and reuse. -[All Functions - Speckle Automate](https://latest.speckle.systems/functions) +Explore the latest Automate functions here: +[All Functions - Speckle Automate](https://app.speckle.systems/functions) diff --git a/automate/documenting.md b/automate/documenting.md index dbcf85e9..44d2124a 100644 --- a/automate/documenting.md +++ b/automate/documenting.md @@ -1,10 +1,26 @@ -# Documenting your function -Your function’s `README.md` will be published to its dedicated Automate page. This is your opportunity to communicate the key functionality, limitations, and detailed instructions for the function’s inputs to automation composers. +# Documenting Your Function -Later, this will be your opportunity to market why your function is the go-to solution for quality control, solar farm layouts, or Pokemon detection for Speckle. It is also a great way to seek collaborators. +Your function’s `README.md` will be published to its dedicated Automate page. This is your opportunity to communicate the key functionality, limitations, and detailed instructions for the function’s inputs to your team and organisation. -You can choose how detailed you would want to document the functional logic, so long as it is abundantly clear what it results in given what source data. -Speckle Automate’s function listing will display with full Markdown support, including relevant imagery, etc. +Clear documentation is critical for: -![Example of the Readme as displayed in a function listing.](./img/readme.png) -Example of the Readme as displayed in a function listing. \ No newline at end of file +- Helping your team and collaborators understand how to use the function effectively. +- Ensuring consistency and transparency when sharing functions within a Workspace. +- Providing detailed instructions that reduce confusion and the need for additional support. + +## Key Points for Documentation + +- **Clarity and Precision**: Ensure it is abundantly clear what your function produces given specific source data and input parameters. +- **Detail as Needed**: Provide enough detail about the function’s purpose, logic, and limitations to enable your team to use it effectively. +- **Markdown Support**: Speckle Automate’s function listing supports full Markdown, allowing you to include relevant imagery, links, and formatting for a professional and functional presentation. + +### Example + +Below is an example of how a well-documented `README.md` might appear on a function listing: + +![Example of the Readme as displayed in a function listing.](./img/readme.png) +*Example of the README as displayed in a function listing.* + +--- + +Clear and thorough documentation ensures your function is easy to understand, use, and maintain—ultimately benefiting your team and organisation. Take the time to make it count! diff --git a/automate/feedback.md b/automate/feedback.md index 84220ad7..595950ad 100644 --- a/automate/feedback.md +++ b/automate/feedback.md @@ -1,19 +1,43 @@ # Providing Feedback -You have been invited to join the Automate closed beta on the understanding that Speckle provides the infrastructure and compute resources and that you provide feedback on: +As a participant in the Automate public beta, your feedback is crucial to shaping Speckle Automate as we approach its 1.0 release. We welcome your insights on: -- The developer experience. -- The automation experience. -- The integration of the automation results in the Speckle viewer. -- How would you see Automate as a paid product? +- The **developer experience**: How intuitive and efficient creating, deploying, and managing functions is. +- The **automation experience**: Usability and effectiveness of setting up and running automations. +- The **integration of automation results**: How well results are visualised and used within the Speckle viewer. +- Your thoughts on **cost and value**: How would you see Speckle Automate as a cost to your team, project, or organisation? -We, Speckle, will also endeavour to give you the same level of support via the [speckle.community](https://speckle.community/c/making-speckle/insiders-automate/27) forum as we already do for all other Speckle activities. In addition to the invitation to the Speckle Automate platform, you are also invited to join the private channel on the forum dedicated to Automate. -We look forward to a lively discussion, peer support, ideas sharing, best practices, and reusable code snippets so that you can all progress swiftly toward some success. +### Public and Private Functions in Beta -We will also send feedback questionnaires to capture specific areas where we want to develop the Automate product to be a first-class experience for function authors, automation composers and project leaders. +Currently, Speckle curates and authors all public functions, ensuring they meet the highest standards for functionality and reliability. During the beta, these public functions remain free to run without limits, allowing users to experience the value they bring to their workflows. -## Rewards +Speckle Automate offers private functions for private workflows, which are exclusive to Workspace projects. Compute resources for private functions are monitored but not charged during the beta phase. -If successful function development wasn’t rewarding enough, Speckle may award incentives or rewards for active participation or for finding significant bugs. In turn authors of significantly popular functions may be supported in their contribution to the public function library. +While we are not actively testing third-party contributions to the public function library during this beta phase, we are keen to hear from individuals or organisations interested in offering their functions publicly. -We also encourage Beta participants are free to showcase their successes not only on the community forum but as far and wide as their personal brand can carry. \ No newline at end of file +## Community Support and Engagement + +Speckle remains committed to supporting you throughout the beta. This includes: + +- Access to the [Speckle Community Forum](https://speckle.community/c/making-speckle/insiders-automate/27) for discussions, peer support, and idea sharing. +- Opportunities to collaborate with other beta participants by sharing best practices, reusable code snippets, and creative solutions. + +We aim to foster a vibrant exchange of ideas to help you and your team achieve success with Speckle Automate. + +## Feedback Mechanisms + +To capture your valuable insights, we will periodically send feedback questionnaires. These will help us refine Automate for: + +- **Function Authors**: Tools and workflows for creating and maintaining functions. +- **Automators**: Experiences with designing and managing automations. +- **Project Leaders**: Integrating automation results into team workflows and decision-making processes. + +Your feedback will shape the final development phase as Automate transitions toward its 1.0 release. + +### Showcase Your Success + +We encourage you to share your achievements widely: +- Post updates and success stories on the [Speckle Community Forum](https://speckle.community). +- Share your work through personal or professional networks to inspire others and highlight your contributions. + +Together, we can shape Speckle Automate's future, ensuring it meets the diverse needs of teams, projects, and organisations as we prepare for its official launch. diff --git a/automate/for-automate-composers.md b/automate/for-automate-composers.md deleted file mode 100644 index 02da375d..00000000 --- a/automate/for-automate-composers.md +++ /dev/null @@ -1,33 +0,0 @@ -# For Automation Composers - -### Designing Automation Workflows -- **Automation Workflows**: Automations are triggered by new versions published to a given model within a project. An automation will execute a function and pass the published data and any configuration parameters to it. -- **Creating Workflows**: Step-by-step guide on assembling workflows using pre-built and custom functions. - -### Viewing Automation Runs - -From your automation list, you can see each automation you have composed by name, what function it is deploying to, and which project and model it is in. If an automation has been disabled, it will be shown with a Paused icon. - -![A registered automation](./img/paused-status.png) - -If a model no longer exists, the automation will automatically be disabled, and a notification banner will be visible under the details header. - -![model removed error](./img/model-error.png) - -Below are all the runs of each automation, their status, the model version they ran on, when they started, how long they ran, and a link to view the log output of each run. This will show the current or evential status of the run: pending, running, success, or failure. - -![automation run indicating success](./img/run-success.png) - -Clicking on the details header will bring up the Automation page, where you can manage more. - -### Managing Automation Configurations - -- **Editing details**: Clicking edit will allow you to rename a function and toggle its enabled state. -- **Enable and Disable**: Once defined, automations will always run on a new version of the selected model. If this is no longer needed, you can disable it. You can re-enable it at any time. -- **Amend Function:** Clicking on the function card allows you to select a different function version and alter its configuration details. The function card will indicate if it is set to the latest revision. -- **Trigger Automation**: If the model exists, you can manually trigger it even if the automation is disabled. This will use the latest version as the source. -- **Review Runs**: The same runs review is available in an automation page focussed on just that automation. -- **Version Control**: Automation is defined to run on a specific model for a specific project. When a function is selected, by default, you are selecting the latest version of that function. This is the best option. As parts get revisions, you will be alerted that your automation is not using the newest revision. You can choose to edit the automation to do this or not. While supported by the underlying API, there is no current means of auditing what version of an automation was live at a specific time. -- **Collaboration**: - - Functions, by their open-source nature during the closed beta, may be authored by anyone with access to the function repository once created. This could be automatic among an organisation or enabled by the original function author, where the repo is tied to that author's GitHub account. - - Automations, are tied to the composer's account who must have the owner role for the project. diff --git a/automate/for-automate-users.md b/automate/for-automate-users.md new file mode 100644 index 00000000..de4ef034 --- /dev/null +++ b/automate/for-automate-users.md @@ -0,0 +1,44 @@ +# For Users + +### Designing Automation Workflows +- **Automation Workflows**: Automations are triggered by new versions published to a given model within a project. Automation will execute a function and pass the published data and any configuration parameters to it. +- **Creating Workflows**: Follow a step-by-step guide to assemble workflows using pre-built and custom functions, making it easy to automate processes efficiently. + +### Viewing Automation Runs + +From your automation list, you can view each automation by name, the function it is deploying, and the associated project and model. If an automation has been disabled, it will display a Paused icon. + +![A registered automation](./img/paused-status.png) + +If a model no longer exists, the automation will be automatically disabled, and a notification banner will appear under the details header. + +![model removed error](./img/model-error.png) + +Below the automation details, you will see a list of all runs, including their status, the model version they ran on, start time, duration, and a link to view the log output of each run. The status can be: +- Pending +- Running +- Success +- Failure + +![automation run indicating success](./img/run-success.png) + +Clicking on the details header opens the Automation page, where you can manage additional configurations. + +### Managing Automation Configurations + +- **Editing Details**: Click "Edit" to rename an automation or toggle its enabled state. +- **Enable and Disable**: Automations will automatically run on a new version of the selected model. If this is no longer needed, you can disable and re-enable it anytime. +- **Amend Function**: Clicking on the function card allows you to: + - Select a different function version. + - Modify its configuration details. + - See if the function is set to the latest revision. +- **Trigger Automation**: If the model exists, you can manually trigger the automation even if it is disabled. This will use the latest version as the source. +- **Review Runs**: The same detailed run review is available on the dedicated Automation page. +- **Version Control**: + - Automations are tied to a specific model and project. By default, automations use the latest version of a function. + - If a function revision becomes available, you will be notified that your automation is not using the newest version. You can choose to update it or continue using the existing version. + - Note: While the underlying API supports auditing the version of automation at a specific time, this is not currently available in the user interface. + +### Collaboration +- **Functions**: By default, functions are source-available. Once created, they can be accessed by anyone with repository permissions. For private functions, access depends on Workspace permissions or the original function author’s GitHub settings. +- **Automations**: Automations are tied to the user's account, which must have the **owner** role for the associated project. diff --git a/automate/for-function-authors.md b/automate/for-function-authors.md index 3af1de54..20a38394 100644 --- a/automate/for-function-authors.md +++ b/automate/for-function-authors.md @@ -1,10 +1,19 @@ # For Function Authors -- **[Creating functions](./create-function.html):** Follow our detailed instructions for publishing your first function using the Automate wizard. - -- **[Updating functions](./release-function-version.html):** After your code's initial release completes your function's publishing, subsequent releases will automatically set the function listing to show the latest revision. Automations already using your function must be edited to point to specific modifications. -- **APIs and Data Access**: Functions can make external calls or even calls to other Speckle Models using REST via whatever library you choose. Speckle SDKs include a subset of methods specifically to handle Automate data. More details about this are below. - -- **Runtime**: Automate functions run once per trigger; there is a generous execution time for all functions to cope with even intensive computation. This is not intended to allow for deliberately long-running executions with RTC or sockets, etc. -- **Rate-limits:** Functions CAN cause other functions to run. This could cause infinite execution loops. Speckle has implemented rate limiting as a bulwark against this during beta testing. When Speckle Automate moves to a paid compute, Speckle will have other methods of detecting such loops, but you could still incur an expensive compute cost. -- **Best Practices**: Do test, test and test your code. Deploying code to Automate the testing on every model version sent is possible but will become tedious. Look into modularising your function so that business logic can be tested locally. Test suites can be executed as part of the GitHub automation for quality CI/CD. +- **[Creating Functions](./create-function.md):** Follow our detailed instructions for publishing your first function using the Automate wizard. + +- **[Updating Functions](./release-function-version.md):** Once your function is published, subsequent updates automatically set the function listing to display the latest revision. However, automations already using your function must be manually edited to point to specific modifications if required. + +- **APIs and Data Access:** Functions can make external API calls or interact with other Speckle Models using REST, leveraging any library of your choice. Speckle SDKs include a subset of methods tailored for handling automation results data. Refer to the API documentation for additional details. + +- **Runtime:** Automate functions execute once per trigger and are allocated generous execution time to support computationally intensive processes. However, long-running executions using RTC, sockets, or similar methods are not supported. + +- **Private Functions and Workspaces:** + Privately developed functions are exclusive to **Workspace Projects**, enabling teams to create and manage functions specific to their organisation's needs. These private functions are only accessible within the Workspace and are not shared publicly unless explicitly released by their authors. + +- **Rate Limits:** Functions can trigger other functions, which may result in infinite execution loops. Speckle has implemented rate limiting during beta testing to mitigate this risk. Additional safeguards will be introduced once Speckle Automate transitions to a paid compute model, but excessive loops could still lead to significant compute costs. + +- **Best Practices:** + - **Test Thoroughly:** Ensure your code is thoroughly tested before deployment. Modularise your function so business logic can be tested locally, reducing the need for live testing on every model version. + - **Utilise CI/CD Pipelines:** Incorporate automated test suites into GitHub workflows for robust quality assurance. + - **Optimise Performance:** Write efficient code to minimise execution time and resource usage, enhancing the overall reliability of your functions. diff --git a/automate/frequently-asked-questions.md b/automate/frequently-asked-questions.md index f205050f..fe6811ed 100644 --- a/automate/frequently-asked-questions.md +++ b/automate/frequently-asked-questions.md @@ -1,93 +1,60 @@ -# Frequently Asked Questions - -### **How much does it cost? Is Automate included in my enterprise subscription?** - -- We want Automate to make a lot of the tedious tasks in your workflow easier, so we are working hard to make it as accessible as possible. -- Automate will be free as long as it’s in beta. We’re working on our future pricing plans and hope to announce them to you soon. -- It is anticipated that our paid Speckle server tiers will include some level of Automate usage, but where the balance lies we are still working out. -- We will be looking for feedback from our beta testers to help us shape this. - -### **I use my favourite desktop tool for clash detection. What is the difference between running clash detection in Speckle?** - -- The main difference is that clash detection with Automate runs in the background and on as many models as you wish. It runs on models from any of our integrations, such as Blender, Sketchup, Grasshopper, Revit, TopSolid etc.. So you only have to work with Automate to get similar results across all your software. That saves you much time opening your favourite desktop tool, loading models, running the clash detection and waiting for the results. -- The results from the Clash Detection running in Automate are viewable directly in your web browser. You can enable sharing for your Speckle Model, send that link to your colleagues and clients, or embed our viewer in SharePoint, Notion or a web page. You can view the clash detection results on Mobile, Desktop, or the application of your choice. -- The results can then be retrieved from Speckle into any of our [**Connectors (opens new window)**](https://v1.speckle.systems/features/connectors/), whether Revit, Excel, PowerBI, etc. Speckle makes using the most appropriate and familiar software easy to get the best from your work. -- Automate results have an API, and reporting tools could be built to integrate with external reporting workflows such as PowerBI or Jupyter Notebooks out of the gate. - -### **Is Automate faster than my desktop workflow?** - -- This is hard to tell as it depends on the complexity of your models, hardware, etc. However, Automate Function is triggered without human interaction every time you upload a new model version; this alone might result in a faster response. Automate runs in the background, saving you time to focus on more critical tasks. It runs on dedicated hardware hosted in the cloud and doesn’t slow down your computer if you try to get other things done while it runs. -- Automations you define to run on models others contribute to will not require them to notify you, for you to retrieve their data, for you to take the results and turn them into a report; this can happen while you are at lunch, at sleep or climbing a mountain. - -### What languages are supported? - -- C# and Python are currently supported as first-class extensions to the existing Speckle SDKs; we plan to add Jupyter Notebooks soon and JavaScript/Typescript later. In terms of support, we offer a template repository, software development kit, documentation, an active forum, and a large community of like-minded contributors. -- You could extend our specklepy Automate template to execute your analysis with custom C++ or Rust libraries. -- Automate can run any language, framework, or off-the-shelf software - please refer to the Function specification for more details. While this is technically possible, and we can point you to documentation to do this, you may find a different level of support in terms of SDKs, documentation, or community to support you if you choose to take this path. -- Windows and MacOS runtimes are not currently available. -- In short, if you can execute a function from a command line, you can run it in Automate. - -### **Is Automate part of the Speckle Server? How do I install the service?** - -- No, Automate is a separate service but relies on the Speckle Server that is already available. -- We will be working hard during the lifetime of the beta testing to integrate Automate into the Speckle web application more tightly; the Automate backend will be separate. -- Speckle Server is freely available and can be installed on your own infrastructure. While in beta, Automate is not currently installable or open source. - -### **What else do I need for Speckle Automation?** - -A mindset that automation is the future! - -### **How does Automate compare to Hypar, Viktor, or ShapeDiver?** - -We love every product delivering new technology to push the AEC industry forward, and we believe Automate has a complementary role beside them. Here are some of the differences: - -- The intention is different: - - Automate is **not** intended for real-time parametric modelling in immediate, millisecond response to user adjustments in an application window. This type of activity is better suited for Hypar, NodePen, Viktor, Dynamo, Grasshopper, etc.. - - Automate is intended to automate tedious or complex tasks. It is designed to run at a lower frequency whenever you send a new version of your model to Speckle. It is designed to run computations for many seconds or minutes, allowing for complex (and time-consuming) automations. -- Integrations: - - Automate builds on top of Speckle; therefore, it allows you to integrate with the software you know and love, whether SketchUp, Revit, Rhino, Grasshopper, ArchiCAD, Blender, PowerBI, Unity, etc. [The list 🔗i](https://v1.speckle.systems/features/connectors/)s long and growing! Thanks to these Speckle [Connectors 🔗a](https://v1.speckle.systems/features/connectors/)nd other integrations, you can send your model directly from your software of choice, and it will automatically start an Automation on Automate. Once the Automation is complete, you can retrieve the results and view them in your application. This doesn’t have to be the application you sent the original data from; you could, for example, send data from Revit and view the results in Power BI. - - Other cloud-based applications allow data to be saved in files and exported to your software, and some have limited integrations with other applications. However, they do not build upon existing deep integrations with your favourite software, as Speckle does! - - Automate results can be viewed in the browser, and the viewer can be embedded in many web pages and applications. The Speckle viewer also has an API which allows for extensions and customisation. -- Languages and existing software: - - Automate can run any language, framework, and existing software (see our [**Function specification**](https://deploy-preview-190--speckle-docs.netlify.app/automate/function-specification)). We provide helpful SDKs and documentation for commonly used languages, e.g. C# and Python, but limiting yourself to just those is unnecessary. - -### **Who can create Functions?** - -- Anyone on your team with coding skills or a third-party developer can write Automate Functions for your projects. We provide easy-to-use templates, complete examples, documentation, and developer-friendly software development kits to get you started. See our [**guide**](https://speckle.guide/automate/create-function) for more details. - -### **How do I use Automate in my project?** - -- Please select an existing Function from the library and create an Automation from it! See our [**guide**](https://speckle.guide/automate/create-automation) for more details. - -### **How can I create a Speckle Function? Do I upload my Functions to Speckle?** - -- You can start with our Function template or an example and expand on these to develop your own. Automate is integrated with GitHub, and you can commit your code to your repository. Your Function appears in the library, where you can assign it to a model or the whole project. See our [**guide**](https://speckle.guide/automate/create-function) for more details. - -### **Who can access my automated workflows?** - -- Speckle Server and Automate have permission controls that prevent unauthorised access, and your intellectual property stays in your organisation. You can read more on Speckle’s [**security in this article](https://v1.speckle.systems/security/).** Automations are private to an individual account; anyone with access to the project can see the results of all automation run on the models belonging to it. - -### **Are there public Functions? Can I share Functions outside my organisation? Can I limit who can use a Function?** - -- All Functions are public on [**latest.speckle.systems/functions**](https://latest.speckle.systems/functions/) and available to view in the functions list. They are shared with all users of Automate. We wish to encourage an open-source ethos and community of collaborators to create outstanding functions. We will be actively developing additional features to the functions list as we integrate them into the Speckle web application, and we welcome your insights. e.g. organisational lists and user ratings. - -### **Where can I find help?** - -- If you get stuck, our team will be happy to help you. Head to our [Community Forum](https://speckle.community/invites/Fbk5j1wbRW) and post any issues with Automate in the dedicated channel. We will publish a dedicated section on our tutorials page where you can find more tips and tricks when getting started. - -### **Is there a way to un-publish the already-used functions?** - -- We wish to retain any function used in automation to ensure that the automation will always be able to be run. However, we are considering ways to archive Functions that are no longer in use to keep the library tidy. - -### **Can we use third-party libraries? Can I send data to another service?** - -- If the third-party library's licensing terms are compatible with being run on a cloud platform such as Automate, then yes. The library and function must also comply with Speckle's Terms of Service. You are free to link to any other web-accessible API. If you need to use authentication tokens, ensure not to include them in your function code but define a field to allow automation to provide them. - -### **Is it a Function author's responsibility to describe all limitations, e.g. what host application/object types will be accepted for the function?** - -- The function author is best suited to understand what their function can handle and has been tested against. We expect them to label their function accordingly to set expectations for automation composers. - -### Are functions checked for malicious activity? How can I trust a function won’t steal my project data? - -- We will be monitoring data egress but only ad-hoc reviewing some codes as a matter of policy. We hope you’ll agree that functions as open-source are much less of a black box than other services you might be uploading project data to. Other Automatons and Specklers can review a function if you have specific questions. If you are not confident you can review the code, do not commit to using a function with project data until you are. -- All automations are tied to the revision of a function that was current at the time they were made. The automation list will indicate if newer versions are available, and you can review the changes to the function before updating your automation. It will not be possible for a function to change its operation or what it does with your data without you knowing. \ No newline at end of file +# Frequently Asked Questions + +### **How much does it cost? Is Automate included in my enterprise subscription?** +- Automate compute usage is **free during the public beta**, allowing you to explore its capabilities at no cost. +- **Private Functions** can only be authored and executed within **Workspaces**, a paid feature included in Speckle’s subscription plans. +- Automate is **fully functional during the free trial periods** of the Standard Plan, enabling testing before committing to a subscription. +- We’re still finalising future pricing and welcome feedback from beta testers to shape our plans. + +### **Is Automate faster than my desktop workflow?** +- **It depends on your perspective.** Automate may not always run faster for individual tasks, but it excels in the bigger picture: + - **Reduced learning curve**: Instead of training every team member on specific software, reusable Automate Functions make workflows accessible to everyone. + - **Hardware independence**: Automate uses cloud infrastructure, freeing local machines for other tasks. + - **Continuous automation**: Automations trigger automatically on new model uploads, eliminating manual steps and enabling results to be ready while you focus on other work. +- By streamlining collaboration and task automation, Automate can significantly reduce overall workflow time and effort. + +### **What languages are supported?** +- **Fully supported SDKs:** Python and C#. +- **Under development:** JavaScript/TypeScript and Jupyter Notebooks. +- Any language or software executable via **command-line instructions** can run in Automate, though using Speckle SDKs is recommended for seamless data interaction. +- For technical flexibility, Automate supports extending functionality with custom libraries, such as C++ or Rust, though support may vary. + +### **Is Automate part of the Speckle Server? How do I install the service?** +- Automate is a **separate service** relying on an available Speckle Server. +- While in beta, Automate is not open-source or self-installable. We are working to integrate Automate more tightly into the Speckle web application. + +### **What else do I need for Speckle Automation?** +Just a mindset that **automation is the future**! + +### **How does Automate compare to Hypar, Viktor, or ShapeDiver?** +- **Purpose**: Automate automates complex, time-consuming tasks triggered on new model uploads, not real-time parametric modelling like Hypar or ShapeDiver. +- **Integration**: Automate builds on Speckle’s Connectors, enabling seamless data exchange with tools like SketchUp, Rhino, Blender, and PowerBI. +- **Flexibility**: Automate supports any language or software while retaining Speckle’s collaborative and open-source ethos. + +### **Who can create Functions?** +- Function creation is currently **limited to within Workspaces** during this phase. +- Public Functions are those **authored or curated by Speckle** and made available for general use. + +### **How do Automations work on personal vs workspace projects?** +- For **personal projects**, Automations are fully configurable by the automation author. +- For **workspace projects**, Automations are configurable by project owners. + +### **Who can view automation results?** +- **Any project viewer** can see results directly in the Speckle web application. +- **Workspace admins and project owners** can access the full history of prior automation runs. + +### **Where can I find help?** +- Visit our [**Community Forum**](https://speckle.community/invites/Fbk5j1wbRW) to get assistance or share feedback about Automate. + +--- + +### **How would clash detection* work in Speckle Automate?** +- While a **public function for clash detection** is not yet available, here’s how it could theoretically operate: + - Automate would run clash detection **in the background**, analysing multiple models from various tools (e.g., Blender, Revit, SketchUp) without manual intervention. + Results would be viewable directly in the web application, shared via links, or embedded in platforms like SharePoint or Notion. + - Results could also be retrieved into other tools via Speckle Connectors (e.g., PowerBI or Excel). + - Automate's API would enable integration with external workflows, allowing custom reporting and visualisation. + +- This functionality would save time by automating repetitive tasks and simplifying collaboration across teams and platforms. + +*Note: Clash detection is a theoretical use case until a public function is available.* diff --git a/automate/function-testing.md b/automate/function-testing.md index f9177f4b..b3a91dcd 100644 --- a/automate/function-testing.md +++ b/automate/function-testing.md @@ -1,101 +1,85 @@ # Testing Your Functions -Functions can be tested using your preferred local testing library. We have also introduced the ability to create special “test automations” that provide you with the ability to test: - -1. how a function’s business logic executes its intended checks against a real Speckle project, and -2. how it produces the desired function results. - -A test automation is a sandbox environment that allows you to connect your local development environment for testing purposes. It enables you to run your code against project data and submit results directly to the connected test automation. - -Unlike regular automations, test automations are not triggered by changes to project data. They cannot be started by pushing a new version to a model. Consequently, test automations do not execute published functions. - -### How to create test automations - -1. Visit the new Automations tab on the project page - - ![alt text](./img/automations-tab.png) - -2. Click the New Automation button - - ![alt text](./img/new-automation-button.png) - -3. Click Create test automation in the bottom left. - - ![alt text](./img/create-test-automation.png) - -4. Follow the instructions to configure your test automation - - ![alt text](./img/configure-test.png) - -5. Congratulations! You now have a test automation against which you can run your automated functions. Uploading new versions of the project’s model(s) will provide you with new data against which to test your functions. - - ![alt text](./img/my-test-automation.png) - -### How to use test automations - -Both the [C# SDK](https://github.com/specklesystems/speckle-sharp/tree/main/Automate/Speckle.Automate.Sdk) and [Python SDK](https://github.com/specklesystems/specklepy/tree/main/src/speckle_automate) provide utilities for interacting with your test automations from local code environments. We also provide an example function in each supported language: - -- [C# example function](https://github.com/specklesystems/SpeckleAutomateDotnetExample) -- [Python example](https://github.com/specklesystems/specklepy) - -In either language, the tests can be successfully run once a `.env` file ([in python](https://github.com/specklesystems/speckle_automate_python_example/blob/main/.env.example)) or an `appsettings.json` ([in C#](https://github.com/specklesystems/SpeckleAutomateDotnetExample/blob/main/TestAutomateFunction/appsettings.example.json)) file is configured with the following values: - -- `SPECKLE_TOKEN` - See [Creating Personal Access Tokens](https://speckle.guide/dev/tokens.html) -- `SPECKLE_SERVER_URL` - The literal url of your Speckle Server, like [`https://latest.speckle.systems/`](https://latest.speckle.systems/) -- `SPECKLE_PROJECT_ID` - The id for the project with your test automation -- `SPECKLE_AUTOMATION_ID` - The id of your test automation - -Both the project id and the automation id can be found in the url of your automation’s page in the form of `/projects/[project-id]/automations/[automation-id]`. - -Once your environment variables are configured in this way, you can write your test cases and use the test setup utilities provided by your language’s SDK. Happy hacking! - -### Limitations - -To set up a sandbox automation you will need: - -- a Speckle project you are an owner of -- a function you’ve published to the Automate marketplace. -- the function needs to have minimum 1 release (its a tech limitation for now) - -Note: We do not currently enforce that test results in a test automation are coming from the author of that function. In the future, we are likely to introduce further restrictions on how and when test automations can be used like requiring the test automation owner to be the same user as the author of the function being tested. - - -::: tip Notes - - To create an easy to use yet meaningful testing setup for function authors, we’ve developed a workflow specifically geared towards providing an easy to use yet robust setup. - - When testing the correctness of an automate function, we want to test: - - 1. how a function’s business logic executes its intended checks against a real Speckle project, and - 2. how it produces the desired function results. - - For this reason we allow the creation of test automations aka automation sandboxes in the automation creation wizard. Test automations may be created on any project, where you are eligible for creating automations. - - At its core a test automation is a special type of automation, that does not run, even if the trigger conditions are met (not even manual triggers are allowed). What this means in the background we do not associate the automation with any resource in the Automate Execution engine. - - When creating a sandbox automation, we do not ask for function inputs in the wizard, those are better provided in the development environment. - - When executing a test run, the automate SDK will hook into the schematically correct test tools to provision a new test automation run, that can be used for the integration test run - - To set up a sandbox automation you will need: - - - a Speckle project you are an owner of - - a function you’ve published to the Automate marketplace. - - the function needs to have minimum 1 release (its a tech limitation for now) - - for now, the author match is not enforced, but we will probably turn on a check, that only allows using functions in sandboxes, where the automation composer is the same as the function author - - Steps: - - - got to the new automation tab on the project page - - click create new automation - - select automation dev mode - - select function from list - - automation created - - follow the instructions on the test automation page, to set up the required input values in your development environment - - run the cli test command ( npm run test, pytest, dotnet test, etc,) that is relevant for your function setup. - - Internally these test commands do the following: - - Finds the Test Automation ID, Function ID, & API token stored in the local development environment - - Calls the API to request a new Automation run and a function run - - Runs the function locally, creating the json file (this can have a uniquely generated file name including timestamp to avoid overwriting previous attempts and allow for later auditing/debugging), updating the input command parameter pointing to the file’s path. - - test run results should be visible on the automation page and in the project’s automation status display -::: \ No newline at end of file +Speckle Automate supports robust testing for your functions through local testing setups and **test automations**—sandbox environments designed to validate your function's business logic and results against real project data. + +## What Are Test Automations? + +Test automations provide a safe, sandboxed environment for function authors to: + +1. Test how a function’s business logic interacts with Speckle project data. +2. Validate that the function produces the desired results. + +Unlike regular automations, test automations: +- Are not triggered by project data changes. +- Cannot be manually triggered via the UI. +- Do not execute published functions directly, but allow you to run your function locally while connecting to Speckle data. + +## How to Create a Test Automation + +1. Navigate to the **Automations** tab on your project page. + ![automations-tab](./img/automations-tab.png) + +2. Click the **New Automation** button. + ![new-automation-button](./img/new-automation-button.png) + +3. Select **Create Test Automation** in the bottom left. + ![create-test-automation](./img/create-test-automation.png) + +4. Follow the instructions to configure your test automation. + ![configure-test](./img/configure-test.png) + +5. Once created, your test automation will appear in the list. Use it to test your function against the project’s data. + ![my-test-automation](./img/my-test-automation.png) + +## How to Use Test Automations + +Both the [C# SDK](https://github.com/specklesystems/speckle-sharp/tree/main/Automate/Speckle.Automate.Sdk) and [Python SDK](https://github.com/specklesystems/specklepy/tree/main/src/speckle_automate) include utilities for interacting with test automations. Example functions are available in both: + +- [C# Example Function](https://github.com/specklesystems/SpeckleAutomateDotnetExample) +- [Python Example Function](https://github.com/specklesystems/speckle_automate_python_example) + +### Required Environment Variables + +To run your tests, configure the following in your environment: + +- **Python**: Use a `.env` file ([example](https://github.com/specklesystems/speckle_automate_python_example/blob/main/.env.example)). +- **C#**: Use an `appsettings.json` file ([example](https://github.com/specklesystems/SpeckleAutomateDotnetExample/blob/main/TestAutomateFunction/appsettings.example.json)). + +Environment Variables: +- `SPECKLE_TOKEN`: [Create a Personal Access Token](https://speckle.guide/dev/tokens.html). +- `SPECKLE_SERVER_URL`: URL of your Speckle Server, e.g., `https://app.speckle.systems/`. +- `SPECKLE_PROJECT_ID`: The ID of your Speckle project with the test automation. +- `SPECKLE_AUTOMATION_ID`: The ID of your test automation. + +The project and automation IDs are in the URL of your automation page: `/projects/[project-id]/automations/[automation-id]`. + +## Running Test Cases + +1. Set up your local environment with the required values. +2. Run the test command (`pytest`, `dotnet test`, etc.) from your development setup. +3. The SDK utilities will: + - Connect to the test automation via the API. + - Run your function locally, generating results. + - Submit the results to the test automation for validation. + +Test results will be visible on the automation page and the project’s automation status display. + +## Limitations + +To set up a test automation, you must: +- Be an owner of the Speckle project. +- Have published the function to the Function Library. +- Ensure the function has at least one release (current technical limitation). + +::: note Future Restrictions +We may introduce further restrictions, such as requiring the test automation owner to be the author of the function being tested. +::: + +## Key Notes on Test Automations + +- Test automations do not ask for function inputs during creation; inputs should be set up in your development environment. +- Test automations are sandboxed environments designed to aid in integration testing. They do not execute functions directly within the Automate runtime. +- Test runs allow you to debug locally while validating outcomes against Speckle project data. + +Happy hacking! 🎉 +For further assistance, refer to the SDK documentation and example repositories. diff --git a/automate/getting-started.md b/automate/getting-started.md index 854a0064..f54db3e0 100644 --- a/automate/getting-started.md +++ b/automate/getting-started.md @@ -1,20 +1,21 @@ # Getting Started -## Accounts and Authentications +## Accounts and Authentication -::: tip 💡 You must verify your account on https://latest.speckle.systems. -This is done by responding via the email sent to you on sign-up -::: +To participate in the Speckle Automate public beta, you will need: + +- A verified account on [app.speckle.systems](https://app.speckle.systems) +- An account on [github.com](https://github.com) +- An account on [speckle.community](https://speckle.community) -To participate in the Speckle Automate beta, you will need: -- A verified account on [latest.speckle.systems](https://latest.speckle.systems) -- An account on [github.com](https://github.com) -- An account on [speckle.community](http://speckle.community) +::: tip 💡 +You must verify your account by responding to the email sent to you upon sign-up. +::: + ## User Interface -As a change from the closed beta experience you may have joined, Automate is now fully integrated into our main Speckle web application interface, and you can find it by clicking on a project that you are the owner of: +As part of the public beta, Automate is now fully integrated into the main Speckle web application interface. You can access it by navigating to a project that you are the owner of: ![Automate integrated into the Speckle web application](./img/integrated-ui.png) - diff --git a/automate/important-caveats.md b/automate/important-caveats.md index d9e1519d..d4266f83 100644 --- a/automate/important-caveats.md +++ b/automate/important-caveats.md @@ -2,22 +2,42 @@ ### Your Data -Our development server ([latest.speckle.systems](http://latest.speckle.systems)) has always been flagged as “transient” because we keep the server at the cutting edge of our development branch. While project data is handled exactly like all our stable servers, it comes with the note that we reserve the right to tear down the server and database and build it up again. Your functions will, by nature, be safe in GitHub, but automations, automation runs and results may be lost. +The development server ([latest.speckle.systems](http://latest.speckle.systems)) is no longer in use. All data, functions, and automations are now hosted on the main production server ([app.speckle.systems](https://app.speckle.systems)). -At the end of the Beta program, there is no plan to migrate either project data or automations to any other Speckle server. +While project data is handled with the same level of care and security as all Speckle servers note that: +- During the beta phase, Speckle reserves the right to modify or reset the Automate Execution Engine, Function library or other enabling parts of the server infrastructure. However, the data held on the server is secured and maintained. +- Automations, automation runs, and results may be subject to deletion due to infrastructure updates. +- The end of the Public beta phase will be communicated widely on [Speckle Community](httsp://speckle.community) and in the application. +- At the end of the beta program, we will announce any mechanisms to migrate project data, automation, or related artefacts that might be required. + +We strongly encourage users to continue to back up their functions in GitHub or other repositories as a safeguard. ### Your Access -Your access to Speckle Automate beta is at our discretion as we build and test the infrastructure. We have deliberately designed Automate to be highly open and permissive regarding what is possible to build. At the same time, we have some sophisticated tools to check the contents of running containers and WILL find crypto miners, spam email servers, and other nefarious use cases. There is a zero-tolerance policy, and access will be removed instantly. +Your access to Speckle Automate beta is at our discretion as we build and test the infrastructure. While we have designed Automate to be highly open and permissive regarding what is possible to build, there are strict usage policies: +- We actively monitor running containers to detect and prevent misuse (e.g., crypto miners, spam email servers, or other nefarious activities). +- A **zero-tolerance policy** is enforced. Access will be revoked instantly for violations. ### Open by Design -There are no sandbox restrictions on making external calls, limits on dependencies used, or artefact sizes. We will explore the best fit between function needs and compute platform offerings. Speckle does not currently accept inbound calls to its infrastructure. All automations are anticipated to be created, configured, and managed within the Speckle Automate interface. +Speckle Automate beta encourages open experimentation: +- No sandbox restrictions exist for making external calls, choosing dependencies, or managing artefact sizes other than restricted to normal Speckle server limits. +- Functionality is designed to allow flexible automation workflows. + +However, Speckle does not currently accept inbound calls to its infrastructure. All automation must be created, configured, and managed within the Speckle Automate interface. ### Our Infrastructure -If your code can be defined to run within a container that will run on a Linux machine, then Automate will run it (we hope). We are exploring how to support Windows runtimes and how to offer GPU computing. Speckle Automate beta can be assumed to be CPU execution only until further notice. +Automate is designed to run code within containers that execute on Linux machines. During the beta phase: +- Automations are CPU-only until further notice. +- Support for Windows runtimes and GPU computing is under exploration. +- Support for alternative code repositories than Github is under exploration. -### Our Ethical Use and Privacy +### Ethical Use and Privacy -Speckle does not use data uploaded to any Speckle server for purposes other than support when invited to join projects. We monitor logs to maintain integrity and server health and can debug problems from there without viewing user data. Function authors acknowledge that their functions are source-available and that they are responsible for their organisation's privacy, intellectual property, and security. \ No newline at end of file +Speckle adheres to strict ethical use and privacy policies: +- Speckle does not use or analyse data uploaded to any Speckle server except when invited to join projects for support purposes. +- Logs are monitored to maintain integrity and server health; debugging does not require viewing user data. +- Function authors acknowledge: + - Their functions are source-available. + - They are responsible for ensuring their organisation's privacy, intellectual property, and security. diff --git a/automate/known-issues.md b/automate/known-issues.md index 7bdcfa09..f68c56c9 100644 --- a/automate/known-issues.md +++ b/automate/known-issues.md @@ -1,4 +1,15 @@ -# Known Issues +# Known Issues -- The functions library functions are all being updated to the latest version of the SDK. This means that some functions may not work as expected. If you encounter any issues, please report them to the Speckle team. -- Automation run executions and their results performed during the closed beta are not visible in the new web application integration. They are also no longer enabled. New automations will need to be made to see results. \ No newline at end of file +We are actively working to improve Speckle Automate and value your feedback. If you encounter any issues, please report them to the Speckle team. + +### Current Known Issues: + +- **Functions Library Updates**: + All library functions are being updated to the latest SDK. As a result, some functions may not work as expected. + **Action**: If you experience unexpected behaviour, please provide details about the function and issue. + +- **Legacy Automation Run Results**: + Automation runs and results from the closed beta are no longer visible in the new web application integration and are no longer enabled. + **Action**: Create new automations to view and test results in the updated platform. + +Your input is critical to helping us identify and resolve issues quickly—thank you for your support! diff --git a/automate/public-functions.md b/automate/public-functions.md new file mode 100644 index 00000000..b563fae6 --- /dev/null +++ b/automate/public-functions.md @@ -0,0 +1,69 @@ +# Public Functions + +## What Are Public Functions? + +Public functions are reusable, pre-defined operations available to all Speckle Automate users. They are designed to be simple yet powerful, focusing on specific, high-utility use cases. They help streamline workflows without requiring custom development. + +Public functions are ideal for: + +- Automating repetitive tasks. +- Solving well-defined problems efficiently. +- Providing quick-start solutions for everyday automation needs. + +## Curated by Speckle + +At the start of the public beta, all public functions are curated and developed by Speckle to ensure reliability, simplicity, and quality. Later in the beta, we plan to expand this ecosystem by promoting: + +- **Community Contributions**: Functions designed and shared by Speckle users. +- **Third-Party Integrations**: Functions tailored to specific use cases, such as connecting with SaaS platforms. + +The goal is to create a collaborative and diverse library of functions that address a wide range of automation scenarios. + +## How to Access Public Functions + +Public functions are accessible through the **Functions Library**, located in the Automations tab of your project. + +![function-library-view](./img/function-library-card.png) + +In the library, you can: + +1. Browse available public functions. +2. Review descriptions to understand their purpose and parameters. +3. Select a function to include in your automation. + +## Using Public Functions + +To use a public function in your workflow, follow the steps outlined in the [Creating Automations](./create-automation.md) page. This guide will walk you through: + +1. Selecting a public function. +2. Configuring its parameters. +3. Assigning it to a model in your project. + +Refer to the automation pages for details on managing automations and updating configurations as needed. + +## Examples of Public Functions + +Here are some examples of public functions that offer high utility for common tasks: + +- **Render Image**: Produces high-quality rendered images of models. +- **Data Validator**: Ensures model data meets predefined standards. +- **Report Generator**: Compiles key information from a model into a structured PDF report. +- **Export GLTF**: Converts models into GLTF format for seamless 3D viewing. + +## Updates to Public Functions + +Speckle maintains and updates Public functions to improve functionality or address issues. When a new version of a public function is released: + +- Existing automations using the function will not update automatically. +- You can manually update your automation to use the latest version. Refer to the [Update an Automation](./update-automation.md) page for guidance. + +## Benefits of Public Functions + +- **Simple and Focused**: Designed for tightly defined use cases that deliver real value. +- **Accessible**: No need for custom code; just configure and automate. +- **Collaborative**: Leverage improvements from Speckle, the community, and third-party developers. +- **Efficient**: Save time with pre-configured, reliable workflows. + +Public functions empower you to tackle specific challenges easily, offering a straightforward entry point to Speckle Automate's power. + +For more information on creating your private functions, visit the [Create Functions](./create-function.md) page. diff --git a/automate/release-function-version.md b/automate/release-function-version.md index 45049684..06d67a7c 100644 --- a/automate/release-function-version.md +++ b/automate/release-function-version.md @@ -1,29 +1,54 @@ -# Releasing a new Function Version +# Releasing a New Versions -New versions of a Function will be created automatically when a new GitHub release is created. +New versions of a Function are created automatically when a new GitHub release is created. -# Deployment +For detailed instructions on creating a new GitHub release, refer to [GitHub's documentation](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository). -Your function's deployment is very straightforward when you are confident in the business logic. The GitHub action is triggered on a release. It will: +### Naming Convention -- Spin up a deployment container, -- Extract your functions input schema and validate it -- Build your function code -- Send to Speckle Automate server as an API call with your credentials and successfully compiled code. -- Automate will validate the payload and report success. +We recommend using the [Semantic Versioning (Semver)](https://semver.org/) naming convention to indicate the nature of changes in your release: -This way, only code that has completed the build steps will be sent to Automate. Once a release has been successfully sent, your function will appear in the functions list. +- **MAJOR**: Breaking changes. +- **MINOR**: Backward-compatible functionality. +- **PATCH**: Backward-compatible bug fixes. -Points to look out for: +### Deployment Process -1. You can customise your `workflow.yml` if you want a multipart build step or customise the `functionInputs.json`; ensure the steps generate all the necessary artefacts. -2. The template projects include the basic `Dockerfile` that will be deployed to Speckle Automate. This can be customised to build a set of dependencies and libraries or even custom-build Python if you need a specific version. The container derived from this Dockerfile represents your execution runtime. -3. It will be important to keep the GitHub action up to date as this is where the API call for publishing is made; any.. changes to the API will need to be reflected. +The associated GitHub action is triggered when you create a release on GitHub. This will: -# Releasing a New Version +1. Spin up a deployment container. +2. Extract your function's input schema and validate it. +3. Build your function code. +4. Send the validated and compiled function code to the Speckle Automate server via an API call using your credentials. +5. Automate validates the payload and reports success. -For detailed instructions on how to create a new GitHub release, please refer to [GitHub's documentation](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository). We recommend using the [Semver naming convention](https://semver.org/) for your release names. +Only code that completes these build steps successfully will be sent to Automate. Once the release is processed, your function will appear in the functions list. -Releasing a new version of your Function code causes a [GitHub Action](https://github.com/features/actions) to run. This can be viewed in the Actions tab along the top of your GitHub repository. If there are any errors in the release process, they will be displayed here. +### Monitoring Release Actions -If you require any assistance with understanding errors, please search Speckle's community forum at [speckle.community](https://speckle.community). +The release process triggers a [GitHub Action](https://github.com/features/actions), which can be monitored in your GitHub repository's **Actions** tab. If errors occur during the release process, they will be displayed here. + +### Troubleshooting + +If you encounter issues during deployment: +- Review the error logs in the **Actions** tab for details. +- Search for solutions or ask for assistance on the [Speckle Community Forum](https://speckle.community). + +--- + +::: note 💡 Advanced Customisation + +While the default deployment setup (e.g., `Dockerfile`, `workflow.yml`) works for most use cases, you can customise these files for advanced scenarios: + +1. **Customising the Workflow**: + - Adjust the `workflow.yml` file for multipart build steps or additional artefacts. + - Ensure all necessary artefacts (e.g., `functionInputs.json`) are generated. + +2. **Customising the Runtime**: + - Modify the `Dockerfile` to include additional dependencies, libraries, or specific runtime versions (e.g., a custom-built Python environment). + - These adjustments allow you to tailor the execution runtime for your function. + +Customisation is typically unnecessary but highlights Speckle Automate's flexibility for unique requirements. +::: + +Most authors can deploy their functions effortlessly by leveraging the default setup. Speckle Automate provides the flexibility to adapt workflows and runtimes as needed for those with specialised requirements. diff --git a/automate/roadmap.md b/automate/roadmap.md index 4dbf3a37..991af79f 100644 --- a/automate/roadmap.md +++ b/automate/roadmap.md @@ -1,30 +1,52 @@ # Roadmap -Much of the roadmap for development will be shaped by the feedback we receive from the beta testers. We are looking for feedback on the developer experience, the automation experience, the integration of the automation results in the Speckle viewer, and how you would see Automate as a paid product. +The roadmap for Speckle Automate continues to evolve based on the feedback and insights from beta participants. During the Public Beta phase, our primary focus is on validating the usefulness of Automate by addressing two key blockers identified in earlier phases: -Anything that does not yet exist listed here is entirely speculative and subject to change. +1. **Live Data Support**: Automations must run seamlessly against production data on [app.speckle.systems](https://app.speckle.systems), rather than on a development server. +2. **Private Function Development**: Organisations require secure, private workflows to realise Automate's potential fully. ### Phase 1: Closed Beta -This phase is now complete. We will share the findings at a future community standup. +This phase is now complete. The findings will be shared at an upcoming community standup. ### Phase 2: Open Beta -This is the current phase. -1. Integrated the Automate platform into the Speckle development server [latest.speckle.systems](https://latest.speckle.systems). -2. A new sandbox environment for the local testing for function code against server data. -3. We are looking for feedback on the user experience and the integration of the automation results in the Speckle viewer. - -### Phase 3: Public Beta -The Public Beta launch is planned for later in 2024. This will include: -1. Full integration into Speckle web application and migrated to [app.speckle.systems](https://app.speckle.systems) with abilty to run automations against production data. -2. The ability to have private functions for your organisation. -3. Multi-model triggers for automations. -4. The public function library will be discoverable and searchable. - +This phase concluded with the following milestones: +1. Integration of the Automate platform into the Speckle development server ([latest.speckle.systems](https://latest.speckle.systems)). +2. Introduction of a sandbox environment for local testing of function code against server data. +3. Initial user feedback on the experience and integration of automation results in the Speckle viewer. + +## Phase 3: Public Beta - **CURRENT** + +We are now in the Public Beta phase, focusing on validating Automate as a robust, scalable solution. Key priorities include: + +1. **Full Integration**: Automations are now fully integrated into the Speckle web application ([app.speckle.systems](https://app.speckle.systems)), enabling workflows against live production data. +2. **Private Functions**: Secure private function development is now available within Workspaces, addressing the need for tailored organisational workflows. +3. **Multi-Model Triggers**: Automations can respond to changes across multiple models, enabling dynamic, interconnected workflows. +4. **Discoverable Public Functions**: A curated library of Speckle-authored public functions is now searchable and available to all users. + +This phase is critical for validating the product’s readiness for broader adoption and addressing the blockers identified in earlier stages. + +### Potential Additions During Public Beta + +We are exploring additional enhancements based on user feedback, including: + +- Improvements to the user interface for managing multi-model triggers. +- Advanced results presentation for clearer insights. +- Expanded options for configuring automation outputs. +- Additional public functions addressing high-demand workflows. +- Key additional Speckle functionality delivered by Automate that requires no user interaction. + +While these are not guaranteed, they aim to refine the product further as we approach the full launch. + ### Phase 4: Product Launch -Speckle Automate Public Beta will cease as a program on full Automate launch in 2025. -1. A product with distinct payment and freemium tiers reflecting runtimes and processor specs. -2. Ability to publish code from Gitlab, Azure DevOps, Bitbucket, GitHub and others. -3. Composable automations with multiple triggers, functions and outputs. \ No newline at end of file +The Public Beta will conclude with the product launch in 2025, which may introduce: + +1. Distinct payment and freemium tiers reflecting runtime and compute specifications. +2. Support for publishing functions from multiple code repositories, including GitLab, Azure DevOps, and Bitbucket. +3. Composable automations with multiple triggers, functions, and outputs for highly customisable workflows. + +Speckle Automate's official release will mark its transition into a mature, scalable platform for the AEC industry. + +As we work toward Automate 1.0, your feedback during the Public Beta phase is more critical than ever. Thank you for helping us shape the future of automation in the AEC industry! diff --git a/automate/troubleshooting.md b/automate/troubleshooting.md index bde79d72..3e50e5ba 100644 --- a/automate/troubleshooting.md +++ b/automate/troubleshooting.md @@ -1,12 +1,18 @@ -# Troubleshooting +# Troubleshooting Automations -### Failed Automations +Automations may fail for three key reasons: -Automations may show a FAILED state for three categories of reasons: +### 1. By Design (**Failed**) +The function logic completes successfully but flags the automation as failed due to data not meeting specified checks or analyses. +**Solution:** Review the automation run reports in the UI. -- **By design**: a function successfully executes but marks the automation as Failed as part of its logic because the version data has failed the checks or analysis being run. — **Check the automation run reports in the UI** -- **By code error:** a function has exited unexpectedly early due to code logic errors. — **Check the logs to review the error message** -- **By platform error**: something in the platform has caused the execution to fail. This could be because: - - The function container is incorrectly configured — **Check the logs to review the error message** - - The available compute resource for the function container has run out of memory. — **Check the logs to review the error message** - - Squirrels have eaten through the wires — **Call animal welfare and request a rehoming**. \ No newline at end of file +### 2. By Code Error (**Exception**) +The function exits prematurely due to errors in the code logic. Speckle Automate flags the automation run with **Exception**. +**Solution:** Check the logs to identify and resolve the error. + +### 3. By Platform Error (**Exception**) +Failures caused by issues in the execution environment: +- **Misconfigured Function Container**: Logs will reveal incorrect setup details. +- **Insufficient Compute Resources**: Out-of-memory errors will appear in logs. +- **External Factors**: Squirrels may have chewed through the wires! + **Solution:** Contact animal welfare to rehome the culprits. diff --git a/automate/update-automation.md b/automate/update-automation.md index ed9820af..2b57b70a 100644 --- a/automate/update-automation.md +++ b/automate/update-automation.md @@ -1,9 +1,10 @@ # Update an Automation -Automations can be updated to amend the configuration values, or to use a different version of the Function. +Automations can be updated to amend configuration values or use a different function version. -1. From the home page of the Automate web application, click on `Details` next to the Automation you wish to amend. -1. Hover over the Function and click the `View and Edit details` button. -1. Select a new version of the Function from the dropdown menu if you wish. -1. Amend the configuration values as required. -1. Click `Save`. +1. Navigate to the **Automations** tab within your project and locate the Automation you wish to amend. +2. Click on `Details` next to the Automation. +3. Hover over the function and click the `View and Edit Details` button. +4. Select a new version of the function from the dropdown menu if needed. +5. Amend the configuration values as required. +6. Click `Save` to apply the changes. diff --git a/automate/viewing-results.md b/automate/viewing-results.md index a6f23ef4..ff481ea2 100644 --- a/automate/viewing-results.md +++ b/automate/viewing-results.md @@ -1,36 +1,37 @@ -# Viewing results in Speckle UI +# Viewing Automation Results -There are two entry points to Automate results: +There are two entry points to view Automate results: ### From the Model Scene View -If automations are running or have been completed, a results doughnut icon will appear. Clicking on this will reveal all the automations that have reported results for the currently viewed version. - - ![Automate results in model scene viewer](./img/scene-viewer-results.png) - - Clicking either of the runs cards will expand to show: - - ![Automation run results card](./img/results-card.png) - - - Status: The message included with a Fail or Success result. - - Attachments: Any artefacts uploaded by the function. - - Resulting Models: An option to add any model version produced by the function. - - Results: Each result report with its status, category, object count and message as reported by the function - - Clicking on a results card will isolate the objects reported by the card and - - Where the result includes metadata, a filter function may be presented to highlight the outcome - - ![result metadata view](./img/result-metadata.png) - - -### From the project dashboard -In the models’ list or card view, each model with automation runs completed will show the same doughnut icon. - - ![model-list-indicator](./img/passed-runs.png) - - - Clicking the doughnut in the model list will show a summary, as seen above, but with additional options. - - ![automation list showing all runs passed](./img/all-runs-passed.png) - - - **View Results**: Will link through to the relevant version and use the results context view to include any other models or objects - - **Open Model**: Will open the model at the latest version - - **View Artefact**: Will either open the artefact in a new browser tab (images) or prompt to download (files) \ No newline at end of file +A results "doughnut" icon will appear if automation registered against that model is running or has been completed. Clicking on this icon reveals all the automations that have reported results for the currently viewed version. + +![Automate results in model scene viewer](./img/scene-viewer-results.png) + +Clicking on any of the run cards expands to show details: + +![Automation run results card](./img/results-card.png) + +- **Status**: Displays the message included with a Fail or Success result. +- **Attachments**: Lists any artefacts uploaded by the function. +- **Resulting Models**: Provides the option to add any model version produced by the function. +- **Results**: Displays each result report, including: + - Status, category, object count, and message as reported by the function. + - Clicking on a results card isolates the objects reported by that card. + - A filter function may highlight specific outcomes if the result includes metadata. + + ![result metadata view](./img/result-metadata.png) + +### From the Project Dashboard + +In the model list or card view, any model with completed automation runs will display the same doughnut icon. + +![model-list-indicator](./img/passed-runs.png) + +Clicking the doughnut icon in the model list provides a summary similar to the model scene view, with additional options: + +![automation list showing all runs passed](./img/all-runs-passed.png) + +- **View Results**: Links to the relevant version and uses the results context view to include other models or objects. +- **Open Model**: Opens the model at its latest version. +- **View Artefact**: Opens the artefact in a new browser tab (e.g., images) or prompts to download (e.g., files).