How To: Add or View Comments or Attachments Associated With a Workflow Instance
The Workflow Attachment and Workflow Comment System SmartObjects added can be used in the context of a workflow to add or view comments or attachments associated with a workflow instance. As an example, an employee submits a leave Form for approval and the HR manager might want to add a comment about the leave Form, such as “This leave is considered leave without pay” so that the next approver (Manager) can see the comment and act accordingly.
The following Process Rights are required to use the Workflow Attachment and Workflow Comment SmartObjects. Because Comments and Attachments are added on a process instance level and not on a worklist item level, a user has to have process rights in order to use these SmartObjects; a user with just an active worklist item without any process rights cannot add or view Comments and Attachments. Process Rights can be managed in the K2 Workspace, K2 Process Portals, the K2 Management site in K2 for SharePoint, and when workflows are designed in the web-based workflow design tools.
Start | View | View Participate | Admin | Server | All | |
---|---|---|---|---|---|---|
Workflow Attachment | ||||||
GetList |
Deny |
Allow | Conditional Allow |
Allow |
Deny | Allow |
AddAttachment | Allow | Allow | Conditional Allow |
Allow |
Deny | Allow |
GetAttachment |
Deny |
Allow | Conditional Allow |
Allow |
Deny | Allow |
Workflow Comments | ||||||
Add Comment |
Allow |
Allow | Conditional Allow |
Allow |
Deny | Allow |
GetList |
Deny |
Allow | Conditional Allow |
Allow |
Deny | Allow |
The Workflow Attachment and Workflow Comment SmartObjects are located in the System Workflow folder in the K2 Designer. You may need to select the show System Objects option to see the SmartObjects in the Designer.
The process instance ID of the workflow is required to work with the Workflow Attachment and Workflow Comment SmartObjects, because this is the value that ties a Comment or Attachment to a workflow instance. If you wish to use these SmartObjects in your workflow forms, the Process Instance ID needs to be mapped in the methods used to add or retrieve Comments and Attachments. If you are using K2 SmartForms, you will need to add the integration with the Comments and Attachments SmartObjects as described below. Comments and attachments SmartObjects can be used in multiple ways to ADD or DISPLAY comments and attachments, the key to the successful use is configuring the Process Instance ID that is always required
The following is an example of configuring SmartForms and Workflow to support adding and viewing comments in Forms associated with a workflow.
The example used is an employee that submits a Leave Form and wants to add a comment on the Form describing the type of leave they want to take such as vacation leave. For a subsequent approval task, we will display the comments added to the workflow on the approval Form and allow the approver to add additional comments. To achieve this, The Start Form contains two Views: The Leave Details View contains leave information which is linked to a Leave SmartObject, and the Add Comment View is an Item View of the Workflow Comment SmartObject The user is able to capture comments while completing the leave information.
Adding comments when the leave request workflow is started:
The Approval Form contains three Views: The Leave Details View contains leave information which is linked to a Leave SmartObject, the Display Comments View is used to show a list of the previous comments for this workflow, and the Add Comment View is an Item View of the Workflow Comment SmartObject. The approver is able to add comments when submitting their decision on the leave request.
Displaying and saving comments when the leave request is approved:
Here are the high level steps to configure the Form and Workflow to save and load Comments. You can follow a similar procedure to add the Attachments integration if you wish; for this scenario we will only use the Comments SmartObject.
The first step is to create Views that will be used to Add and Display (List) comments. You may create the Views once and re-use them across multiple Forms and Applications, or create separate Views for each Application. You may also use the built-in Views called K2 Workflow Attachments View and K2 Workflow Comments View to display a list of Comments, if you prefer, but for this sample we will create Views to both Add and Display (List) Comments.
- Create the Item View used to capture new comments. Locate the Workflow Comments SmartObject and then Design or Generate an Item View. (You may need to Show System Objects as described above to see the System category).
- Design a new Item View for the Workflow Comments SmartObject
- Configure the General settings of the View with values of your choice
- Add the Comment field to the View and configure the styling to your choice
- Save and Finish the View
- Create the List View used to display comments. Locate the Workflow Comments SmartObject and Design or Generate a List View.
- Design a new List View for the Workflow Comments SmartObject
- Configure the General Settings for the List View. Ensure the Call this method when the Form loads option is not selected.
- Select the Field to display on the List View (we recommend Comment, Created By and Created Date)
- Configure the layout and styling of the new List View to your liking
- Save and Finish the View. Now that the Views are ready, we can use them on Forms used to Start workflows and complete workflow items.
- Create a Form with Views that will be used to start the workflow. Add the necessary Views, Buttons, Controls and Rules that are used to capture and submit the Data. Add the Workflow Comments Item View that you created in the previous step to the Form. (We will configure this View in a later step)
- Add a Form Parameter of type Number called ProcInstID. This parameter will be used to save the comment associated with the Process Instance after the workflow is started.
- Save and Finish the Form, and check it in.
- Create a Form with Views that will be used in the Approval steps of the workflow. Add the necessary Views, Buttons, Controls and Rules that are used to capture and submit the Data. Add the Workflow Comments Item View as well as the Workflow Comments List View that you created in the previous steps to the Form. (We will configure these Views in a later step)
- Add a Form Parameter of type Number called ProcInstID. This parameter will be used to load the comments associated with the Process Instance as well as saving the new comment entered by the approver.
- Save and Finish the Form, and check it in.
- Create a new workflow where you wish to use the Comments SmartObject, and bind the workflow to the Start Form you created earlier.
- In the Workflow Start wizard, add a number type Data Field called ProcInstId to the workflow. This data field will store the Process Instance ID of the new workflow so that it can be used later to load the Comments associated with a workflow for the Approval Forms of the workflow.
- Add a Set Data Fields step to the workflow to copy the Workflow ID to the Process Instance ID Data Field, as shown below. This is necessary so that we can pass the Process Instance ID into the Form used to approve the leave request.
- Add a User Task step to the workflow and point it to the Approval Form that you created earlier.
- On the Form settings section, drag the ProcInstId workflow data field into the ProcInstId Form parameter, as shown below:
- Deploy the Workflow so that the workflow integration Actions are added to the Start and Approval Forms.
- Check out and Edit the Start Form
- Configure the Start Workflow action, and set up the Output Mappings so that the Workflow ID is passed into the ProcInstId Form Parameter, as shown below.
- Add an action to show that the workflow was successfully started by showing a message to the user. Configure the message.
- Add an Action to execute the Add Comment method for the Workflow Comment Item View. You may want to include a condition so that the Comment is only saved if the user actually entered a comment.
- Configure the Add Comment method so that the ProcInstId Form Parameter is passed into the Process Instance ID Input property, and the Comment Text Area is passed into the Comment input property
- If a button(such as Submit) was used to start the workflow as shown in our example, it is important to disable any rules that will automatically start the workflow as this will result in duplicate workflow instances being started.
- Save and Finish the Start Form, and check it in. You have now added the necessary integration to capture a comment entered by the User when the workflow is started. Next we will add the integration into the Approval Form to load the previous comments for the workflow.
- Check out and Edit the Approval Form
- Edit and then configure the When the Form is initializing Rule for the Workflow Task state of the Form.
- Add a rule Action to execute the Get List method of the Workflow Comment List View
- Configure the Rule so that the ProcInstID Form parameter is passed into the Process Instance ID Input property, as shown below
- Finish the Rule. You have set up the Rules that will populate the Approval Form with previous comments for the workflow. Next we will set up the Rule to save the Comment entered by the approver.
- Add a Rule that executes after the Workflow action was submitted or when the user submits the Approval Form. Add an Action that executes the Add Comment method of the Workflow Comment Item View. You may want to add a condition so that the comment is only captured if the approver actually added a comment.
- Configure the Add Comment method so that the ProcInstId Form Parameter is passed into the Process Instance ID Input property, and the Comment Text Area is passed into the Comment input property, as shown below
- Finish and Check In the Form. You have now added all the necessary integration to display and capture comments for the Workflow Start Form and Approval Forms.
- Test the application by submitting a new request and then opening the approval Form.
When using K2 Mobile you can view and edit the Comments and Attachments linked to a K2 Application workflow when opening the SmartForm. The experience is the same as in any other browser.