Merge branch 'LRDOCS-4954-kaleo-forms-dxp' of https://github.com/step…

…henkostas/liferay-docs into LRDOCS-4954-kaleo-forms

discover/portal/articles-dxp/140-workflow/02-kaleo-forms/00-kaleo-forms-intro.markdown

@@ -0,0 +1,64 @@
+# Workflow Forms [](id=workflow-forms)
+
+Business processes are often form-based and workflow-driven. They start with
+some data that needs to be entered and progress by sending the data to other
+people or groups. The initial data is processed in some way (for example,
+further data is entered or approval is granted), and the process moves on until
+completion, when each interested party has seen and manipulated the data. To
+write an app for each of these fluid processes is laborious and not cost
+effective. Instead, a tool for quickly defining a process to suit each use case
+is needed. The process architect must define the data that gets collected and
+define the process the data must move through to reach its final state. To
+accomplish this, @product@ already includes the 
+[Dynamic Data Lists application](/discover/portal/-/knowledge_base/7-1/creating-data-definitions)
+for defining forms, and the [Kaleo Designer
+application](/discover/portal/-/knowledge_base/7-1/kaleo-designer) for designing
+workflows. The Kaleo Forms solution combines the features of these applications,
+letting you design an integrated process for sending forms through a workflow in
+one intuitive UI.
+
+The entire process includes:
+
+1. Creating a Kaleo Process
+
+2. Creating the process's field set (or selecting an existing 
+   [Data Definition](/discover/portal/-/knowledge_base/7-1/creating-data-definitions))
+
+3. Creating the process's workflow definition (or selecting one that's already
+   created)
+
+4. Creating and assigning forms for each workflow task
+
++$$$
+
+**Example Use Case:** 
+
+The Lunar Resort spa is a popular place. With all the adventure-driven
+activities (lunar hiking, rover races, etc.) available to guests, it's important
+to offer some relaxing and rejuvenating experiences. As the spa expands and new
+Spa Technicians are hired, the Spa Manager decides to implement a new process to
+handle orders. It involves several steps and several people:
+
+- The customer service representative for the spa interacts with a customer and
+  fills out an order form.
+
+- The customer service representative gives the order details to the spa
+  technicians so they can divide up the requests, with a single technician
+  assigned to each order. 
+
+- The spa technician sends the order to the spa manager for final approval and
+  comment. 
+
+- The spa manager sends the final order back to the customer service
+  representative, who contacts the customer with the final details of his spa
+  service order.
+
+A process like this is a nightmare to manage manually, but perfectly suited for
+Kaleo Forms.
+
+$$$
+
+Since Kaleo Forms is accessed through a site's administration menu (under
+Content → Kaleo Forms Admin), make sure the intended users of your Kaleo
+Processes have access to the application. See the article on [roles and permissions](/discover/portal/-/knowledge_base/7-1/roles-and-permissions) if
+you're unsure how that works.

discover/portal/articles-dxp/140-workflow/02-kaleo-forms/01-using-kaleo-forms.markdown

@@ -0,0 +1,122 @@
+# Creating Kaleo Forms Process [](id=creating-kaleo-forms-process)
+
+To start creating a Kaleo Forms Process you need to get to Kaleo Forms Admin: 
+
+1.  Go to *Site Administration* → *Content*.
+
+2.  Select *Kaleo Forms Admin*.
+
+    Kaleo Forms appears with a listing of the defined processes. If you're 
+    coming here for the first time, there won't be any, so create one. 
+
+3.  Click the *Add* (![Add](../../../images-dxp/icon-add.png)) button to open 
+    the New Process Wizard and begin the first step in creating a Kaleo 
+    Process. 
+
+## Creating the Process
+
+In the first step, enter the basic information about the process:
+
+1.  Enter *Spa Order Process* for the *Name* and add a *Description*.
+    Name
+
+2.  Click *Next*.
+
+![Figure 1: Add a Kaleo Forms Process to link a form with a workflow definition.](../../../images-dxp/kaleo-forms-add.png)
+
+## Creating the Form [](id=creating-the-form)
+
+In the second step of the New Process Wizard, define the fields that can appear
+in your process's forms. There are two methods:
+
+1.  Choose a predefined field set. To use a field set that already exists, pick
+    one from the list of field sets by clicking the Kebab menu
+    (![Actions](../../../images-dxp/icon-actions.png)) next to its entry and
+    selecting *Choose*. 
+
+2.  Create a new field set. Use the *Add Field Set* button to add a new field
+    set. If you're not sure about creating a field set, see the documentation on
+    [creating data definitions](/discover/portal/-/knowledge_base/7-1/creating-data-definitions)
+    first.
+    - For this example, Add a new field set: 
+        - A Text field called *Customer Name* 
+        - A Text Box called *Requested Spa Technician*
+        - A Select field called *Services Requested* with these options: 
+            - Massage
+            - Fish Pedicure
+            - Sauna
+            - Acupuncture
+            - Moon Mud Facial Mask
+        - A Boolean field called *Returning Customer?*
+        - A Date field called *Preferred Date*
+        - A Text field called *Preferred Time*
+        - A Date field called *Available Date*
+        - A Text field called *Available Time*
+        - A Boolean field called *Approved*
+        - A Text Box field called *Managerial Comments*
+
+Click *Next* to move to the next step in the wizard: adding a workflow for
+the process.
+
+![Figure 2: In the second step of the New Process Wizard, define and choose the fields for your form.](../../../images-dxp/kaleo-forms-fields.png)
+
+## Selecting a Workflow [](id=choosing-a-workflow)
+
+In the third step of the New Process Wizard you select a workflow to use for
+your forms. The Single Approver workflow is included by default. See how it's
+defined by opening it in the Kaleo Designer.
+
+1.  Click the actions menu (![Actions](../../../images-dxp/icon-actions.png))
+
+2.  Select *Edit*. 
+
+The graphical interface for editing or defining a workflow appears below the
+Single Approver edit screen's Details section. 
+
+If you don't want to base your workflow on the Single Approver definition (or
+any definition already available in your system), add a new workflow from
+scratch using the Kaleo Designer. Click the *Add Workflow* button to get
+started.
+
+- For the Spa Order Process, make a new workflow definition called *Spa Order
+    Workflow*:
+
+![Figure 3: The Spa Order Process has three tasks that happen sequentially.](../../../images-dxp/kaleo-forms-spa-order-definition.png)
+
+The definition has a StartNode and three task nodes. Develop it in the graphical
+designer built into Kaleo Forms. There's a more detailed write-up of the
+Kaleo Designer [here](/discover/portal/-/knowledge_base/7-1/kaleo-designer) if
+you're not already familiar with it. 
+
+This workflow exhibits simple linear processing, so that the initial form is
+filled out (in the StartNode) and then the workflow moves to the first task
+(Technician Claim), then to the second task (Managerial Approval), and finally,
+to the final order task.
+
+The task assignments of this workflow are as follows:
+
+- Technician Claim: Assigned to the Spa Technician Role.
+- Managerial Approval: Assigned to the Spa Manager Role.
+- Final Order: Assigned to the Asset Creator.
+
++$$$
+
+**Note:** Create the Spa Technician Role and the Spa Manager Role as 
+[Site Roles](/discover/portal/-/knowledge_base/7-1/roles-and-permissions), 
+and give them
+[permission](/discover/portal/-/knowledge_base/7-1/defining-role-permissions)
+to access the Kaleo Forms application. In the role's page for defining
+permissions, they're under Site Administration → Content → Kaleo Forms
+Admin. Give both roles all of the permissions available for Kaleo Forms Admin.
+
+$$$
+
+Once the workflow is done, select it:
+
+1.  Click *Actions* → *Choose* on the workflow you just created.
+
+2.  Click *Next*.
+
+Now that you have the workflow definition completed assigned, you must create
+and assign forms for each workflow task. 
+

discover/portal/articles-dxp/140-workflow/02-kaleo-forms/02-assigning-kaleo-forms.markdown

@@ -0,0 +1,153 @@
+# Assigning Forms for Workflow Tasks [](id=adding-task-forms)
+
+In the fourth (and final) step of the New Process wizard, assign a form to each
+task in the workflow definition (and to the StartNode to get the process kicked
+off). All forms you work with here will be either the entire field set you
+defined in step two, or a subset of it. 
+
++$$$
+
+**Note:** In this step, you can't add any proper form fields (fields that accept
+user input). If you forgot to add a Select field to the field set in step two,
+for example, you cannot add one here. Instead go back and add it to the field
+set.
+
+$$$
+
+For review, the Spa Order Process has these fields:
+
+- Customer Name
+- Requested Spa Technician
+- Services Requested 
+- Returning Customer?
+- Preferred Date
+- Preferred Time
+- Available Date
+- Available Time
+- Approved
+- Managerial Comments
+
+Not all the available fields should appear on each form. For example, the
+Approved field should only appear on the form for the managerial review task.
+
+Each applicable workflow node (the initial state and each task) appears in a row
+with its associated form and a button that lets you assign a form. In the Spa
+Order Workflow definition, there are four nodes that need forms: StartNode,
+Technician Claim, Managerial Approval, and Final Order. Next you'll assign a 
+form for each of the four nodes.
+
+
+## Assigning Kaleo Forms
+
+![Figure 5: You can assign a form to each task in the workflow, and for the initial state (*Created* in this case.)](../../../images-dxp/kaleo-forms-task-forms.png)
+
+1.  Click on the actions menu (![Action](../../../images-dxp/icon-actions.png)) next to the Request Entered task
+
+2.  Click *Assign Form*.
+
+3.  Click the *Add* button (![Add](../../../images-dxp/icon-add.png)) on the 
+    next screen.
+
+4.  Name the initial form (call it *Spa Order Process--Order Form* if 
+    you like). 
+
+5.  Delete these fields from the form (mouse over
+    the field and click the delete
+    icon--![Delete](../../../images/icon-trash.png)):
+    
+    - Available Date
+    - Available Time
+    - Approved
+    - Managerial Comments
+
+    ![Figure 6: Workflow task forms are a subset of the original form.](../../../images-dxp/kaleo-forms-form-builder.png)
+
+6.  Click *Save*.
+
+7.  On the next screen, click on your new form to choose it.
+
+    Now the workflow definition's StartNode has a form associated with it.
+
++$$$
+
+**Note:** If you delete a field by accident or want to add another field to your
+form, drag and drop its icon from the *Fields* tab on the left to the form
+canvas on the right. Fields already on the form that can appear on it only once
+are grayed out. You can also edit the settings of a field in the form by mousing
+over it and clicking the wrench icon.
+
+$$$
+
+You have three more fields to create using these steps.
+
+1.  *Spa Order Process--Technical Claim Form*
+
+    For the Technician Claim workflow task. Follow the same procedure used 
+    above, this time deleting these fields from the full field set:
+
+    - Approved
+    - Managerial Comments
+
+
+2.  *Spa Order Process--Managerial Approval Form*
+
+    The manager can change anything she wants about the order, so include the 
+    entire field set in the form.
+
++$$$
+
+**Example Use Case Note:** In the Spa Order Process, the Managerial Approval
+workflow task and its associated form are filled out by the spa manager. The
+manager can oversee the order, making sure that customers requests are being met
+and that all technicians are fulfilling their share of the spa's duties.
+
+$$$
+
+3.  *Spa Order Process--Final Order Form*
+
+    Like the last form, it should have all the form's fields so that the 
+    customer service representative can review the order with the customer.
+
++$$$
+
+**Example Use Case note:** The customer service representative finalizes the
+order and gets back to the customer on the final details (available time, name
+of technician, and confirms the services they want).
+
+$$$
+
+![Figure 7: Once created, your process is listed in Kaleo Forms.](../../../images-dxp/kaleo-forms-processes.png)
+
+Click *Save* when finished. The process is ready to test.
+
+
+## Test the Process [](id=test-the-process)
+
+Once your new process is developed, add records to it by clicking on the process
+name and then the Plus button (![Add](../../../images-dxp/icon-add.png)).
+
+The application displays the form you assigned to the workflow's initial state.
+Fill out the form and click Save.
+
+![Figure 8: Fill out the form and send it through the process.](../../../images-dxp/kaleo-forms-new-process-form.png)
+
+Once the initial form is submitted in the Kaleo Forms application, the process
+is managed by the workflow engine. In a process backed by the Spa Order
+Workflow definition, the workflow moves first to the Technician Claim task, then
+to the Managerial Approval task, and last, to the Final Order task. Whatever
+users or roles you assigned to the tasks receive notifications, and the task
+appears in the Assigned to My Roles section of the My Workflow Tasks portlet. A
+notification is also triggered in the Notifications application. Once in the
+task, the user views and approve the form or clicks the edit button. At this 
+point the workflow task forms you created come into play. Each assigned user fills out the form, saves it, and sends it along in the workflow.
+
+The Kaleo Forms application unites two powerful features of Liferay by
+integrating a workflow and a form into a new entity, the Kaleo Process.
+
+## Related Topics [](id=related-topics)
+
+[Kaleo Designer](/discover/portal/-/knowledge_base/7-1/kaleo-designer)
+
+[Using Workflow](/discover/portal/-/knowledge_base/7-1/activating-workflow)
+
+[Liferay's Workflow Framework](/develop/tutorials/-/knowledge_base/7-1/liferays-workflow-framework)