Merge pull request #143 from World-of-Workflows/Jim-edits9July

solutions and Managing workflows

docs/08_handling _the_data/README.md

@@ -11,7 +11,7 @@ World of Workflows provides robust capabilities for working with data stored in
 
 ## Relevant Activities
 
-When you want manipulate data in the User Configurtable Database in World of Workflows you will use the `Data` activities.  Here are the most commonly used:
+When you want manipulate data in the User Configurtable Database in World of Workflows you will use the `Data` activities.  Here are the most commonly used:  
 ![Data activities](2024-07-10-15-37-54.png)
 
 
@@ -24,4 +24,12 @@ When integrating data activities into your workflows, consider the following bes
 3. **Data Validation:** Validate data before performing create or update operations to ensure it meets your business rules and constraints.
 4. **Security:** Secure access to data activities to ensure that only authorized users can perform certain operations, such as updating or deleting records.
 
-By following these steps and best practices, you can effectively work with data in the database of World of Workflows, ensuring your workflows are robust, efficient, and reliable.
+By following these steps and best practices, you can effectively work with data in the database of World of Workflows, ensuring your workflows are robust, efficient, and reliable.
+
+## Worked example
+
+Go to `Admin` -> `Workflows` -> `Create Workflow`  
+Click the arrow beside Publish and import this workflow file:  <a href="./working-with-data-examples.json" download>Example workflow file</a>
+
+<img src="2024-07-11-13-09-11.png" alt="Import button graphic" style="width: 250px; height: auto; border-radius: 10px; box-shadow: 2px 2px 5px grey;" />
+

docs/08_handling _the_data/gettingDataRecords.md

@@ -12,7 +12,6 @@ To retrieve a specific record from the database, you can use the `ObjectInstance
 
 1. **Add the `ObjectInstanceGet` Activity:**
    - Drag and drop the `ObjectInstanceGet` activity into your workflow.
-   - Specify the `Type` from which to retrieve the record.
    - Define the ObjectId to select the record.
 
 2. **Example Configuration:**

docs/08_handling _the_data/working-with-data-examples.json

@@ -0,0 +1 @@
+{"$id":"1","definitionId":"a2982cf0de4b46a2a76bf2197bb0a86e","versionId":"b644b1ef56cd44d1a2fb2f473070cbc6","name":"WorkingWithDataExamples","displayName":"Working with data examples","version":1,"variables":{"$id":"2","data":{}},"customAttributes":{"$id":"3","data":{}},"isSingleton":false,"persistenceBehavior":"WorkflowBurst","deleteCompletedInstances":false,"isPublished":false,"isLatest":true,"createdAt":"2024-07-10T05:36:17.1861724Z","activities":[{"$id":"4","activityId":"9caf3c3e-4c99-4515-ac15-68dbf4245352","type":"ObjectInstanceList","name":"ListContacts","displayName":"List Object Instances - Active Contacts","x":160,"y":280,"persistWorkflow":false,"loadWorkflowContext":false,"saveWorkflowContext":false,"properties":[{"$id":"5","name":"ObjectType","expressions":{"$id":"6","Literal":"9"}},{"$id":"7","name":"Expand","expressions":{"$id":"8"}},{"$id":"9","name":"Filter","expressions":{"$id":"10","Literal":"Status eq 'Active'"}},{"$id":"11","name":"Skip","expressions":{"$id":"12"}},{"$id":"13","name":"Limit","expressions":{"$id":"14","Literal":"100"}},{"$id":"15","name":"OrderBy","expressions":{"$id":"16","Literal":"LastName asc"}}],"propertyStorageProviders":{"$id":"17"}},{"$id":"18","activityId":"346332c5-e163-4b5e-9bee-f4881f9effb0","type":"ForEach","displayName":"For Each contact","x":700,"y":260,"persistWorkflow":false,"loadWorkflowContext":false,"saveWorkflowContext":false,"properties":[{"$id":"19","name":"Items","syntax":"JavaScript","expressions":{"$id":"20","JavaScript":"activities.ListContacts.Output()"}}],"propertyStorageProviders":{"$id":"21"}},{"$id":"22","activityId":"613c4edf-124b-4a29-a6aa-f5d335906df6","type":"ObjectInstanceGet","displayName":"Get Contact","x":1100,"y":220,"persistWorkflow":false,"loadWorkflowContext":false,"saveWorkflowContext":false,"properties":[{"$id":"23","name":"InstanceId","syntax":"JavaScript","expressions":{"$id":"24","JavaScript":"12345"}},{"$id":"25","name":"Expanded","expressions":{"$id":"26","Literal":"true"}},{"$id":"27","name":"VariableName","expressions":{"$id":"28","Literal":"Contact"}}],"propertyStorageProviders":{"$id":"29"}},{"$id":"30","activityId":"2704b50b-c0fc-4ae3-b651-75cdda57a4a0","type":"SetVariable","displayName":"Set Variable","x":980,"y":420,"persistWorkflow":false,"loadWorkflowContext":false,"saveWorkflowContext":false,"properties":[{"$id":"31","name":"VariableName","expressions":{"$id":"32","Literal":"Contact"}},{"$id":"33","name":"Value","syntax":"JavaScript","expressions":{"$id":"34","Literal":"John","JavaScript":"activities.ListContacts.Output()[0]"}}],"propertyStorageProviders":{"$id":"35"}},{"$id":"36","activityId":"7b144acd-d730-4c56-aab0-3d8986958c77","type":"ObjectInstanceUpdate","displayName":"Update Contact - set APIkey","x":1540,"y":160,"persistWorkflow":false,"loadWorkflowContext":false,"saveWorkflowContext":false,"properties":[{"$id":"37","name":"InstanceId","syntax":"JavaScript","expressions":{"$id":"38","JavaScript":"getVariable(\"Contact\").ObjectId"}},{"$id":"39","name":"ClearOmittedFields","expressions":{"$id":"40"}},{"$id":"41","name":"Values","syntax":"JavaScript","expressions":{"$id":"42","Json":"{\"APIKey\":\"123456\"}","JavaScript":"return {\r\n    \"APIKey\":\"123456\"\r\n}"}},{"$id":"43","name":"VariableName","expressions":{"$id":"44","Literal":"Contact"}}],"propertyStorageProviders":{"$id":"45"}},{"$id":"46","activityId":"8afd09dc-cb9a-4cd4-9277-9cdab5f2df44","type":"ObjectInstanceUpdate","displayName":"Update Contact - set APIkey","x":1520,"y":320,"persistWorkflow":false,"loadWorkflowContext":false,"saveWorkflowContext":false,"properties":[{"$id":"47","name":"InstanceId","syntax":"Liquid","expressions":{"$id":"48","JavaScript":"getVariable(\"Contact\").ObjectId","Liquid":"{{Variables.Contact.ObjectId}"}},{"$id":"49","name":"ClearOmittedFields","expressions":{"$id":"50"}},{"$id":"51","name":"Values","syntax":"JavaScript","expressions":{"$id":"52","Json":"{\"APIKey\":\"123456\"}","JavaScript":"return {\r\n    \"APIKey\":\"123456\"\r\n}"}},{"$id":"53","name":"VariableName","expressions":{"$id":"54","Literal":"Contact"}}],"propertyStorageProviders":{"$id":"55"}},{"$id":"56","activityId":"e63f3f79-7ee0-4d26-a548-a4a1fa1b8f55","type":"QuickDataInsert","displayName":"JSON Data Insert","x":618,"y":-36,"persistWorkflow":false,"loadWorkflowContext":false,"saveWorkflowContext":false,"properties":[{"$id":"57","name":"ObjectType","expressions":{"$id":"58","Literal":"9"}},{"$id":"59","name":"KeyField","expressions":{"$id":"60","Literal":"Title"}},{"$id":"61","name":"ClearOmittedFields","expressions":{"$id":"62"}},{"$id":"63","name":"Values","syntax":"JavaScript","expressions":{"$id":"64","Json":"{\r\n    \"Title\":\"John Doe\",\r\n    \"FirstName\":\"John\",\r\n    \"Surname\":\"Doe\",\r\n    \"APIKey\":\r\n}","JavaScript":"return {\r\n    \"Title\":\"John Doe\",\r\n    \"FirstName\":\"John\",\r\n    \"Surname\":\"Doe\",\r\n    \"APIKey\":getVariable(\"XeroAPIKey\")\r\n}"}}],"propertyStorageProviders":{"$id":"65"}},{"$id":"66","activityId":"250c2d88-6fad-4037-9756-4d629716e839","type":"DeleteObjectInstance","displayName":"Delete Object Instance","x":1360,"y":480,"persistWorkflow":false,"loadWorkflowContext":false,"saveWorkflowContext":false,"properties":[{"$id":"67","name":"ObjectInstanceId","syntax":"Liquid","expressions":{"$id":"68","Liquid":"{{Variables.Contact.ObjectId}"}}],"propertyStorageProviders":{"$id":"69"}},{"$id":"70","activityId":"e7bf473a-955e-47b7-ad97-cc3886c23aa7","type":"ObjectInstanceCreate","displayName":"Create Object Instance","x":40,"y":-80,"persistWorkflow":false,"loadWorkflowContext":false,"saveWorkflowContext":false,"properties":[{"$id":"71","name":"ObjectType","expressions":{"$id":"72","Literal":"9"}},{"$id":"73","name":"Values","syntax":"JavaScript","expressions":{"$id":"74","Json":"{\"FirstName\":\"John\",\"LastName\":\"Doe\",\"Email\":\"john.doe@example.com\"}","JavaScript":"return {\r\n    \"FirstName\":\"John\",\r\n    \"LastName\":\"Doe\",\r\n    \"Email\":getVariable(\"Company\").PrimaryEmail\r\n    }"}},{"$id":"75","name":"VariableName","expressions":{"$id":"76","Literal":"Contact"}}],"propertyStorageProviders":{"$id":"77"}}],"connections":[{"$id":"78","sourceActivityId":"9caf3c3e-4c99-4515-ac15-68dbf4245352","targetActivityId":"346332c5-e163-4b5e-9bee-f4881f9effb0","outcome":"Done"},{"$id":"79","sourceActivityId":"346332c5-e163-4b5e-9bee-f4881f9effb0","targetActivityId":"613c4edf-124b-4a29-a6aa-f5d335906df6","outcome":"Iterate"},{"$id":"80","sourceActivityId":"346332c5-e163-4b5e-9bee-f4881f9effb0","targetActivityId":"2704b50b-c0fc-4ae3-b651-75cdda57a4a0","outcome":"Done"},{"$id":"81","sourceActivityId":"613c4edf-124b-4a29-a6aa-f5d335906df6","targetActivityId":"7b144acd-d730-4c56-aab0-3d8986958c77","outcome":"Success"}],"id":"b644b1ef56cd44d1a2fb2f473070cbc6"}

docs/10_ManagingWorkflows/README.md

@@ -0,0 +1,76 @@
+---
+title: Managing Workflows
+layout: default
+nav_order: 10
+has_children: true
+---
+
+# Managing Workflows
+
+The World of Workflows graphical interface allows you to build workflows simply with drag and drop.
+
+The workflows interface provides for the ability to `Publish`, `Export`, `Delete` and `Import` individual workflows.
+
+A workflow is not usable by the World of Workflows engine until it is published.  
+
+## Removing previous versions
+
+Each time a workflow is Published, a new copy is created in the database.  This provides the ability to roll back to previous versions.  To remove old versions you can Export a workflow, delete the workflow and reimport it.  
+This should be a regular task you perform when developing new workflows to maintain the performance of your World of Workflows instance.
+
+### Procedure:  
+
+At the bottomn of every workflow there is a `Publish` button.  use the arrow beside the button to expose this menu  
+<img src="2024-07-11-13-09-11.png" alt="Import button graphic" style="width: 250px; height: auto; border-radius: 10px; box-shadow: 2px 2px 5px grey;" />
+1. Save your worklflow to disk by Exporting it  
+   This creates a `<workflowname>.json` file in your browser's downloads folder 
+2. Delete your workflow 
+   Don't worry: all your work is saved in the `<workflowname>.json` file!
+3. Create a new workflow  
+<img src="2024-07-11-12-59-23.png" alt="Import button graphic" style="width: 150px; height: auto; border-radius: 10px; box-shadow: 2px 2px 5px grey;" />
+
+4. Import the workflow from disk
+   Click the arrow beside Publish again, click Import and find the `<workflowname>.json` file from step 1
+5. Publish the new workflow.  
+   It will be an exact copy of the original workflow, but it will have no previous versions.
+
+
+
+
+## Duplicating Workflows
+
+To make a copy of your workflow, follow this procedure:
+
+### Procedure:  
+
+At the bottomn of every workflow there is a `Publish` button.  use the arrow beside the button to expose this menu  
+<img src="2024-07-11-13-09-11.png" alt="Import button graphic" style="width: 250px; height: auto; border-radius: 10px; box-shadow: 2px 2px 5px grey;" />
+1. Save your worklflow to disk by Exporting it  
+   This creates a `<workflowname>.json` file in your browser's downloads folder 
+2. Navigate to Admin -> Workflows
+3. Create a new workflow  
+<img src="2024-07-11-12-59-23.png" alt="Import button graphic" style="width: 150px; height: auto; border-radius: 10px; box-shadow: 2px 2px 5px grey;" />
+
+4. Import the workflow from disk
+   Click the arrow beside Publish again, click Import and find the `<workflowname>.json` file from step 1
+5. Click the cog icon <img src="2024-07-11-13-36-53.png" alt="Import button graphic" style="width: 70px; height: auto; border-radius: 10px; box-shadow: 2px 2px 5px grey; vertical-align: middle;" /> and rename the workflow.  Change both the `Name` and the `Display Name`.
+6. Make any desired changes
+7. Publish the new workflow.
+
+## Copying between instances
+
+Copying workflows between instances, such as from `Personal Edition` to `Business Edition` is a similar process.
+
+### Procedure:  
+
+At the bottomn of every workflow there is a `Publish` button.  use the arrow beside the button to expose this menu  
+<img src="2024-07-11-13-09-11.png" alt="Import button graphic" style="width: 250px; height: auto; border-radius: 10px; box-shadow: 2px 2px 5px grey;" />
+1. Save your worklflow to disk by Exporting it  
+   This creates a `<workflowname>.json` file in your browser's downloads folder 
+3. Navigate to Admin -> Workflows in the other World of Workflows instance.
+4. Create a new workflow  
+<img src="2024-07-11-12-59-23.png" alt="Import button graphic" style="width: 150px; height: auto; border-radius: 10px; box-shadow: 2px 2px 5px grey;" />  
+5. Import the workflow from disk
+   Click the arrow beside Publish again, click Import and find the `<workflowname>.json` file from step 1
+6. Publish the new workflow.
+

docs/11_SolutionsExportImport/README.md

@@ -0,0 +1,56 @@
+---
+title: Solutions - Export and Import
+layout: default
+nav_order: 11
+has_children: true
+---
+
+# Solutions: Export and Import your work
+
+Any World of Workflows instance will be a collection of Types, Views, Data, Workflows and possibly Plugins.  
+
+An important feature of World of Workflows is that these are portable between World of Workflows instances.  Development is usually performed on your own copy of Personal Edition.  When the time comes to add this to your Business Edition instance you will use Solutions Export and Import.
+
+## Creating a Solution
+
+1. Navigate to `Admin` -> `Solutions` in your source instance (eg Personal Edition)  
+<img src="2024-07-11-13-50-46.png" alt="Import button graphic" style="width: 350px; height: auto; border-radius: 10px; box-shadow: 2px 2px 5px grey;" />
+2. Select `Create Solution Export`  
+<img src="2024-07-11-13-53-20.png" alt="Import button graphic" style="width: 350px; height: auto; border-radius: 10px; box-shadow: 2px 2px 5px grey;" />
+3. Enter a name (or take the default), a version if relevant, and an icon (to brand your solution) and a description to indicate the contents of your Solution.
+4. Choose the Types, Workflows and Views
+   ![](2024-07-11-14-00-34.png)
+
+5. When you select a Type, you can choose to also copy some of the data within the type.  This can be helpful when setting up a Production environment from yoru Development environment, to copy items such as the list of Statuses used in a dropdown menu
+   ![](2024-07-11-14-03-53.png)
+6. Types which reference other Types are noted in blue.  Selecting one (eg Contacts in this example wil automatically select the referenced types.  You can unselect these as appropriate.
+   ![](2024-07-11-14-05-54.png)
+7. Select any desired Workflows  
+   ![](2024-07-11-14-08-41.png)
+   Any Plugins required by your workflows will be automatically included in the solution.'
+8. Select any desired Views   
+   ![](2024-07-11-14-11-33.png)
+
+> Note that Search text on this page is Case Sensitive
+
+A summary is displayed.  Use the button to export the solution
+![](2024-07-11-14-12-33.png)
+A Zip file will be created in your browser's download folder.
+
+### Modifying a Solution
+
+World of Workflows is an open, extensible environment.  This applies to Solutions as well. 
+A Solution is a carefully-crafted World of Workflows workflow.  Like any workflow, it can be altered using World of Workflows graphical interface.  
+Here is an example of the contents of a Solution:  
+![](2024-07-11-14-18-47.png)  
+You can import any of the SETUPxxx_WF.json files to modify what the workflow will do when the solution is impoerted.  This might be useful if you wanted to run a proprietary workflow once when a solution is imported.
+Note that the Utilities plugin is included in this solution.
+
+## Importing a solution
+
+To add a Solution to a World of Workflows instance:
+1. Navigate to `Admin` -> `Solutions`
+2. Click `Import Solution`
+3. Select the solution's .Zip file
+4. Confirm the actions before importing the solution.
+   ![](2024-07-11-14-22-23.png)