AEM Forms Workflow. From the SmartDoc Training Cloud: Last Updated: SmartDoc Technologies

(1)

AEM Forms Workflow

From the SmartDoc Training Cloud: www.aemforms.training Last Updated: 11-3-2020

(2)

AEM Forms Workflow

Overview _________________________________________________________________________ 7

AEM Forms Workflow ... 7

Permissions ... 9 Tools ... 9 Models ... 9 Instances ... 10 Archive ... 10 Failures ... 10 Process Variables ... 11 Variables ... 11

Form Submission & Review __________________________________________________________ 13 The Assign Task workflow step ... 13

The AEM Inbox ... 13

The Form Participant Step ... 14

Exercises ... 15

Create the Adaptive Form ... 15

Create the Workflow Model ... 17

Configure the Form ... 25

Participate in the Workflow ... 27

Invoke a Form Data Model Service _____________________________________________________ 30 The Invoke Form Data Model Service ... 30

The Expression Editor ... 30

The JSON file ... 31

Exercises ... 31

Test your Form and Workflow ... 41

Process Form Submission ____________________________________________________________ 43 The OR Split Step ... 43

(3)

Exercises ... 44

Test your Form and Workflow ... 63

ECMA Script Details ... 64

Trouble-Shooting Workflows _________________________________________________________ 66 Overview ... 66

Common Errors ...67

PathNotFoundException ...67

Cannot coerce value of document variable ...67

java.lang.NullPointerException ...67

(4)

Before you Begin

This course, and all of our SmartDoc courseware, is now being taught by many trainers in many locations. Therefore, we are providing this section and this information to help you get started.

Course Overview

Prerequisites: AEM Forms Developer or similar experience Approximate Instructor-Led Classroom Duration: 2 days

www.aemforms.training

Here is the online support site for this course. https://www.aemforms.training

The support site is designed to support our students during and after a training session. Here is what you will find on the support site.

Live, and searchable courseware

You can search the AEM Forms Designer courseware and locate the specific information you need.

Known Issues

(5)

Sandbox Servers

You can find a fully-configured AEM Forms Server for your exercise work.

The AEM Forms Forum

(6)

Limited Courseware License

This Student Training Manual and related COURSEWARE is property of SmartDoc Technologies LLC (SMARTDOC). SMARTDOC retains all right, title and interest (including, without limitation, all patent, copyright, trademark, trade secret and other intellectual property rights) in and to the COURSEWARE, (excluding any ADOBE Materials as incorporated herein). SMARTDOC grants a limited and non-exclusive license to a STUDENT to use the COURSEWARE under one of

the following conditions.

− STUDENT has a valid and active license to the SmartDoc Training Cloud. Once a STUDENT’S license to the SmartDoc Training Cloud has elapsed, STUDENT is no longer licensed to use this COURSEWARE.

− STUDENT is registered in a training class taught by SmartDoc Technologies.

− STUDENT has received a trial of the SmartDoc Training Cloud. Once the trial has elapsed, STUDENT is no longer licensed to use this COURSEWARE.

Students can use the COURSEWARE for their own study but cannot use these materials to teach training courses. Any use of the COURSEWARE by STUDENT for any purposes beyond self-study must be agreed to by SMARTDOC in writing prior to the usage and will require a $400 per day group license fee for each course. Each personalized login to the SmartDoc Training Cloud and each limited COURSEWARE LICENSE must only be used by the STUDENT and is not transferrable. All rights not granted by SMARTDOC are reserved. STUDENT acknowledges that they have

(7)

Overview

Workflow has always been an important part of AEM Forms.

Previously, the best workflow tools and capabilities were on the AEM Forms on JEE platform. This platform features

the Workbench tool and many out-of-the-box AEM Forms workflow steps. You can create services by assembling

these steps to match your business workflow. You can even create custom workflow steps in Java.

For example, the workflow diagram above was created in Workbench and it has the exact same business logic and workflow steps as the workflow illustrated below. The difference is that the workflow created below was created with the workflow tools on the AEM Forms on OSGi platform.

AEM Forms Workflow

(8)

As mentioned, the workflow diagram above was created on AEM Forms on OSGi and it has the exact same business logic and workflow steps as the Workbench process.

You can create various AEM Workflows to handle and process submissions from adaptive forms. Workflows are comprised of a series of steps with each step accomplishing a specific task. Your workflow can contain logic that makes routing decisions based on runtime data.

In addition to form processing workflows, you can also create form review workflows. Since humans are involved in form review workflows, you will learn how to assign tasks and take actions based on user input. Form Reviewers can

join a form review through email, or through their AEM Forms Inbox (shown here).

(9)

Permissions

Users must be members of the following groups to edit and develop AEM workflows. − workflow-users

− workflow-editors

Tools

AEM Workflow includes the following tools.

Models

The design of your workflow is called the model. A model includes WorkflowNodes and always has a start node and an end node. A model also has WorkflowTransitions that connect the nodes and define the flow of the workflow. A runtime model is created when you click Sync in the workflow model editor. If you make updates to your model’s design and click Sync, this new runtime model will only be used by future instances and will not alter any running instances.

(10)

Instances

Instances shows the running workflows. An instance may be paused while waiting for a task to complete.

Failures

(11)

Process Variables

This section covers important information you need to create the workflows in this course.

Variables

AEM Forms on OSGi now supports variables in version 6.5. These are similar to the process variables we used in AEM Forms on JEE with the Workbench program. You can create a variable to store data and reference that variable from

any workflow step. You can create simple and complex variable types like we did in Workbench. − Simple (Primitive) data types: Long, Double, Boolean, Date, and String

− Complex data types: Document, XML, JSON, and Form Data Model

Variables are case-sensitive and you should avoid special characters in your variable names.

The Set Variable step

You can add the Set Variable step to your workflow to set the value of a variable at runtime. The values you set are only in scope for a particular workflow instance. You can use these options to set the value of your variables in the

Set Variable step.

− Literal: Enter the hard-coded value.

− Absolute path: Use this option when the value is a specific location in CRX. − Relative to payload: Use this option when the value is relative to the payload. − XPath: Create an XPATH expression to retrieve a value from an XML datatype. − Expression: Create an expression with the Expression Editor.

− JSON Dot Notation: Use this option to retrieve a value from a JSON or Form Data Model datatype. Here is an example of the Set Variable step.

1. The process variable. 2. The Set Variable step.

(12)

XPath Mapping

When you use the XPath mapping tool, make sure to select the down arrow on the element you want to map.

(13)

Form Submission & Review

In this section, you will create a workflow that manages the review of a form submission.

The Assign Task workflow step

You will use the Assign Task step of the Forms Workflow category.

The AEM Inbox

A Form Reviewer will receive a Task Notification in their Inbox.

(14)

A Form Reviewer can act on the task in a variety of ways, and they can even change the form data if the form is presented in interactive mode.

The Form Participant Step

There is a similar workflow step in the Workflow category called the Form Participant Step.

This workflow step serves an adaptive form to a workflow participant. The participant does not see the form in the workflow container like they do in the Assign Task step. Instead, a full-screen version of the form is presented by itself

to the workflow participant when they click Payload in the Task Notification action bar. After the participant

(15)

Exercises

Create the Adaptive Form

1. Open Forms – Forms & Documents and navigate into to your working folder. 2. Click Create and select Adaptive Form.

3. Select the Blank template.

4. Click Next.

5. Enter <yourname> Invoke Form Review for the Title.

6. Enter This form submits to an AEM workflow that will manage a form review for the Description. 7. Select the Form Model tab.

8. Click the Select From drop-down and select Schema. 9. Expand the Select Schema panel.

10. Select Upload from Disk. 11. Click Upload Schema Definition.

12. Select the user.xsd (XML Schema Definition - XSD) file located in your Student Files. 13. Click Open.

(16)

15. Scroll down and expand the Document of Record Template Configuration panel.

16. Select Generate Document of Record on the Document of Record Template Configuration panel. 17. Click Create.

18. Click Edit.

19. Make sure you are in Edit mode.

20. Open your side panel if it is not already opened. This illustration shows the key icons in the Side Panel.

− Content shows your Form Hierarchy.

− Components shows the out-of-the-box Adobe form components. − Assets shows items in the Asset Manager.

− Data Sources shows the elements of your Form Model. − The Form Container has many important properties. 21. Select Data Sources on the left and expand the User node.

22. Drag and drop each of the data nodes to your form. AEM will create a form field based on the data type defined in the XML Schema file.

(17)

24. Select More – Add toolbar.

25. Select the Toolbar and click the + Add Toolbar Button.

26. Select the Submit button. Your form should now look like this.

Create the Workflow Model

Follow these steps to create the workflow model.

1. Select Adobe Experience Manager – Tools – Workflow – Models. 2. Click Create and select Create Model.

3. Enter <yourname>FormSubmissionReview for the Title. 4. Enter <yourname> FormSubmissionReview for the Name. 5. Click Done.

(18)

7. Click Delete.

8. Click Sync in the upper-right to update your runtime workflow.

Create the Variables

9. Click Variables on the left.

10. Click Add Variable.

11. Enter submissionData for the Name. 12. Select XML for the Type.

13. Enter This variable will store the submitted data for the Description. 14. Click Open Selection Dialog on the right of the XML Schema Path.

15. Select the user.xsd XML Schema file in Assets. If you are working off a SmartDoc Sandbox, the file will be located here.

(19)

16. Click Done. 17. Click Add Variable. 18. Enter dor for the Name. 19. Select Document for the Type.

20. Enter This variable will store the Document of Record for the Description. 21. Click Done.

22. Click Add Variable. 23. Enter email for the Name. 24. Select String for the Type. 25. Click Done.

27. Enter firstName for the Name. 28. Select String for the Type.

29. Click Done. 30. Click Add Variable.

(20)

35. Enter outputData for the Name. 36. Select XML for the Type. 37. Click Done.

38. Click Sync to update the runtime model.

Add Set Variable

39. Switch from Variables to Steps by clicking the Steps icon in the upper right.

40. Select Workflow in the drop-down filter and scroll down to Set Variable. 41. Drag and drop a Set Variable step to your workflow.

42. Select your Set Variable step and click Configure (the wrench icon). 43. Select the Mapping tab to configure your variable mappings. 44. Click Add Mapping and expand the Map Variable panel. 45. Click Select Variable and select submissionData. 46. Select Relative to Payload for the Mapping Mode. 47. Enter data.xml for the value.

48. Click Add Mapping and expand the Map Variable panel. 49. Click Select Variable and select dor.

50. Select Relative to Payload for the Mapping Mode. 51. Enter dor for the value.

52. Click Add Mapping and expand the Map Variable panel. 53. Click Select Variable and select firstName.

54. Select XPath for the Mapping Mode.

55. Select submissionData for the XML Type Variable.

(21)

57. Click Done (the checkmark outlined in red) and you will see your XPath expression set to /user/firstName. 58. Click Add Mapping and expand the Map Variable panel.

59. Click Select Variable and select lastName. 60. Select XPath for the Mapping Mode.

62. Click the checkmark to the right of the XPath field and select lastName. 63. Click Done and you will see your XPath expression set to /user/lastName. 64. Click Add Mapping and expand the Map Variable panel.

65. Click Select Variable and select email. 66. Select XPath for the Mapping Mode.

68. Click the checkmark to the right of the XPath field and select email. 69. Click Done and you will see your XPath expression set to /user/email. 70. Click Done and Sync.

Add Assign Task

71. Select Forms Workflow in the drop-down filter and locate Assign Task.

(22)

73. Select your Assign Task step and click Configure (the wrench icon). 74. Enter Form Review for the Title.

75. Enter Please review this form submission for the Description. 76. Select High for the Priority.

77. Select Days for the Due Date. 78. Enter 1 for Days.

79. Scroll up and select the Form/Document tab 80. Select Adaptive Form for the Type.

81. Select Available at an absolute path.

82. Click Open Selection Dialog to the right of the Adaptive Form Path field.

83. Navigate to your adaptive form and select it. This is the adaptive form you created previously. It is likely called <yourname>-invoke-form-review.

84. Click Select.

85. Select PDF Document for the render adaptive form property. 86. Expand the Pre-populated panel.

87. Select Variable. 88. Select submissionData.

89. Expand the Submitted information panel. 90. Select Variable for the output data file. 91. Select outputData.

92. Scroll up and select the Assignee tab.

93. Click the Assign options drop-down and select To a specific user or group.

(23)

95. Select Notify Assignee by Email. 96. Select the Actions tab.

97. Notice the Default Actions and settings. 98. Select the Advanced tab.

99. Notice the properties and settings. 100. Click Done and Sync.

Add Send Email

101. Select Forms Workflow in the drop-down filter and scroll down to Send Email.

102. Drag and drop the Send Email step to your workflow model. 103. Select the Send Email step and click Configure (the wrench icon). 104. Enter Send Approval Email for the Title.

105. Select the Email Details tab and notice the Email Subject is set to Literal. 106. Enter Your form submission is approved for the Subject.

107. Click Open Selection Dialog to the right of the HTML Email Template field. 108. Select the SmartDocEmailTemplate located here.

(24)

Note: If you are not using a SmartDoc Sandbox Server, you can use this template: /libs/fd/dashboard/templates/email/htmlEmailTemplate.txt.

109. Click Select.

If you are using the SmartDocEmailTemplate, map these variables in the Email Template Metadata panel.

110. Select Variable for the workitem_username. 111. Select firstname for the value.

112. Select Literal for the workitem_sender. 113. Enter SmartDoc Technologies for the value. 114. Scroll up and select the Sender Details tab. 115. Select Literal if it is not already selected.

116. Enter [email protected] if you are using a SmartDoc Sandbox Server. 117. Scroll up and select the Recipient Details tab.

118. Select Variable for Recipient’s Email Address. 119. Select email for the value.

120. Select the Attachments tab and click Add.

121. Select Variable for File Attachment and select dor for the value.

(25)

124. Select Variable for File Attachment and select outputData for the value. 125. Select Literal for File Name and enter outputData.xml for the value. 126. Click Done and Sync.

You will see the SUCCESS message.

Configure the Form

1. Go back to the <yourname> Invoke Form Review form and open it in Edit mode. 2. Click Content and select the Form Container (Adaptive Form Root).

3. Select Configure (the wrench icon).

4. Collapse the Basic panel and expand the Submission panel.

5. Click the Submit Action Drop-down and select Invoke an AEM workflow. 6. In the Submit Action drop-down, select your Workflow Model.

Note: You can type your model’s name into the field to facilitate finding it.

7. Enter data.xml for your Data File Path. 8. Enter dor for the Document of Record Path.

9. Click Done.

(26)

11. In the Document of Record properties panel, scroll down to the Content panel. 12. Click the Logo Image drop down and select Enter Custom.

13. Click Upload (B).

14. Browse to and select the smartDocLogo.png image file from the Student Files. 15. Click Open.

16. Click Done (the blue checkmark). 17. Select Enter Custom for the Form Title. 18. Enter Form Review as the Form Title. 19. Click Done (the blue checkmark).

20. Scroll down and select Enter Custom for the Header Text.

21. Enter Your form submission has been approved for the Header Text. 22. Enter 0066FF for the Accent Color.

23. Select Myriad Pro for the Font Family.

24. Click Done (the blue checkmark). 25. Click Generate Preview.

(27)

Note: Depending on how your browser is configured, the PDF may not display in the browser. Instead, the PDF may

be automatically downloaded by the browser.

Participate in the Workflow

1. Select Preview to test your form and workflow.

2. Enter your Email address, First Name, and Last Name. If the form is approved, the approval will be sent to this email address.

3. Click Submit.

Note: There are two ways to find out about a task. We take one approach here, and then take the second approach

in the next test.

4. Login to AEM as the reviewer. Note: This is the person you designated as the Assignee in your workflow. If you are using a SmartDoc Sandbox, it is likely you used your email address as the Assignee.

5. Select Inbox in the upper-right.

6. Select View All to see all your messages. You should see a task in your Inbox. 7. Notice the values you set in the Assign Task step.

(28)

9. Click the Workflow Details tab to see the history of the workflow. 10. Select the Form tab to see the submitted data in the adaptive form. 11. Notice the workflow options in the Action bar.

12. Also, notice that you can change the form data during the review. 13. Click Submit to advance the workflow.

(29)

15. Click Confirm. 16. Click Done.

If your workflow is working, you should receive an email. If not trouble-shoot your workflow with the Failure tool. Your form’s Document of Record should be attached as a PDF.

Test the Email Notification

17. Preview your form again to test the Email notification. 18. Enter your Email address, First Name, and Last Name.

(30)

Invoke a Form Data Model Service

When you need to access databases and other enterprise data from within a workflow, you can include the Invoke Form Data Model Service workflow step.

The Invoke Form Data Model Service

The Invoke Form Data Model Service can be added at any point in your workflow and can be configured to call a

Form Data Model service.

The Expression Editor

(31)

The JSON file

If you are NOT using a SmartDoc Sandbox Server, you need to upload the JSON schema to Assets. You can store XML schema and JSON schema files in Assets.

1. Open a working folder in Assets. Assets – Files – <your working folder> 2. Select Create – Files.

3. Navigate to your Student Files.

4. Select serviceSchema.json and click Open. 5. Click Upload.

Exercises

Create the Adaptive Form

1. Navigate into to your working folder in Forms & Documents.

Adobe Experience Manager – Navigation – Forms – Forms & Documents – < team folder > 2. Click Create and select Adaptive Form.

(32)

4. Click Next.

5. Enter <yourname> InvokeFDMInWorkflow for the Title.

6. For the Description field enter This form submits the form data to an AEM workflow that uses invokes a Form Data Model Service.

7. Click Create. 8. Click Edit.

− Data Sources shows the elements of your Form Model. − The Form Container has many important properties.

(33)

12. Drag and drop the Drop-down List component to your form.

13. Select your new Drop-down List field and click Configure (the wrench icon). 14. Enter email for the name.

15. Enter Email for the Title. 16. Click Add under Items.

17. Enter [email protected] as the first item.

18. Scroll down and enter [email protected] as the Default value. 19. Click Done.

20. Select Content – Form Container – More (the ellipse button). 21. Click Add Toolbar.

22. Select the Toolbar and click Add Toolbar Button.

23. Select the Submit button.

Create the Workflow Model

1. Select Adobe Experience Manager – Tools – Workflow – Models. 2. Click Create and select Create Model.

(34)

6. Select the workflow model and click Edit. 7. Select Step 1 and click Delete.

8. Click Delete.

Create the Variables

11. Enter serviceOutput for the Name. 12. Select JSON for the Type.

13. Enter A Document variable to hold the output of the Form Data Model Service for the Description. 14. Click Open Selection Dialog on the right of the JSON Schema Path field.

15. Navigate to this file. Note: dam is represented as Assets-dam (see illustration). /content/dam/workflow/serviceSchema.json

(35)

23. Enter emailAddress for the Name. 24. Select String for the Type.

25. Click Done. 26. Click Add Variable. 27. Enter name for the Name. 28. Select String for the Type. 29. Click Done.

31. Enter filename for the Name. 32. Select String for the Type. 33. Click Done.

Create the Workflow Steps

(36)

35. Select Workflow in the drop-down filter and scroll down to Set Variable. 36. Drag and drop a Set Variable step to your workflow.

37. Select your Set Variable step and click Configure (the wrench icon). 38. Select the Mapping tab to configure your variable mappings. 39. Click Add Mapping and expand the Map Variable panel. 40. Click Select Variable and select submissionData. 41. Select Relative to Payload for the Mapping Mode. 42. Enter data.xml for the value.

43. Click Add Mapping and expand the Map Variable panel.

44. Click Select Variable and select emailAddress. 45. Select XPath for the Mapping Mode.

46. Select submissionData for the XML Type Variable. 47. Enter /afData/afUnboundData/data/email for the XPath. 48. Click Done.

49. Click Sync.

50. Select Forms Workflow in the drop-down filter and scroll down to Invoke Form Data Model Service. 51. Drag and drop an Invoke Form Data Model Service step to your workflow.

52. Select your Invoke Form Data Model Service step and click Configure (the wrench icon). 53. Select the Form Data Model tab to select your form data model and service.

(37)

55. Navigate to this form data model. /workflow/master-soap-web-service-ldap

56. Select the master-soap-web-service-ldap form data model and click Select.

57. Click Done.

58. Click Service and select the Query LDAP service. 59. Click the Input for Service tab.

60. Select Provide input data using literal, variable or workflow metadata, and a JSON file. 61. Select Variable for the strUserEmail argument.

62. Select emailAddress for the argument’s value. 63. Click the Output Of Service tab.

64. Select Save output to variable or a JSON file. 65. Select Variable for the output JSON document.

66. Select serviceOutput for the output JSON document’s value. 67. Click Done.

(38)

69. Select Workflow in the drop-down filter and scroll down to Set Variable.

70. Drag and drop a Set Variable step to your workflow.

71. Select your Set Variable step and click Configure (the wrench icon). 72. Select the Mapping tab to configure your variable mappings. 73. Click Add Mapping and expand the Map Variable panel. 74. Click Select Variable and select name.

75. Select JSON Dot Notation for the Mapping Mode. 76. Select serviceOutput for the JSON Type Variable. 77. Select strName for the JSON Variable.

78. Click Add Mapping and expand the Map Variable panel. 79. Click Select Variable and select filename.

80. Select Expression for the Mapping Mode.

Note: You may need to click twice on the Expression Editor in AEM version 6.5.6. If you get no response from the

Expression Editor, continue on step 100.

81. Select Click to Add Expression.

(39)

84. Drag and drop the name variable to the drop zone on the left.

85. Select the plus operator in the middle and enter a String of .json at the end.

SET VALUE OF filename to name +.json 86. Click Done.

87. Click Sync.

88. Select Forms Workflow in the drop-down filter and scroll down to Send Email.

89. Drag and drop a Send Email step to your workflow.

90. Select your Send Email step and click Configure (the wrench icon). 91. Enter Send Email with JSON attachment for the Title.

92. Select the Email Details tab and notice the Email Subject is set to Literal. 93. Enter The JSON from the Form Data Model Service for the Subject. 94. Click Open Selection Dialog to the right of the HTML Email Template field. 95. Navigate to the SmartDocEmailTemplate.

(40)

97. Click Select.

98. Select Variable for the workitem_username. 99. Select name for the value.

100. Scroll up and select the Sender Details tab.

101. Select Literal for Sender’s Email Address and enter [email protected]. 102. Scroll up and select the Recipient Details tab.

103. Select Literal for Recipient’s Email Address and enter your email address. You will be the recipient so you can review the JSON output of the Form Data Model service.

104. Select the Attachments tab and click Add.

105. Select Variable for File Attachment and select serviceOutput. 106. Select Variable for File Name and select filename.

(41)

107. Click Done. 108. Click Sync.

Configure the Form

1. Go back to the <yourname>InvokeFDM form and open it in Edit mode. 2. Click Content and select the Form Container (Adaptive Form Root). 3. Select Configure (the wrench icon).

4. Collapse the Basic panel and expand the Submission panel.

5. Click the Submit Action Drop-down and select Invoke an AEM workflow. 6. In the Submit Action drop-down, select your Workflow Model.

7. Enter data.xml for your Data File Path. 8. Click Done.

Test your Form and Workflow

9. Select Preview to test your form and workflow.

10. Select the [email protected] option and click Submit. Note: If you are a SmartDoc Subscriber and have a login account with us, you can also select your email address for a test.

(42)

(43)

Process Form Submission

In this section, you will create a workflow that handles the form data, the DOR, and any possible form attachments.

The OR Split Step

You will use the OR Split in this exercise. The OR Split enables you to create conditional branches in your workflow. Only one of the branches in an OR Split will be followed. Each branch can contain one or more workflow steps.

ECMA Script

(44)

Exercises

Create the Adaptive Form

1. Navigate into to your working folder. 2. Click Create and select Adaptive Form. 3. Select the Blank template.

4. Click Next.

5. Enter <yourname> Attachments for the Title.

6. Enter This form submits the form data and the attachments to an AEM workflow for the Description. 7. Select the Form Model tab.

8. Open the Select From menu and select Schema. 9. Click Select Schema to expand the Select Schema panel. 10. Select Upload from Disk and click Upload Schema Definition.

11. Select the attachments.xsd file located in your Student Files. The XSD extension stands for XML Schema Definition.

12. Click Open.

(45)

14. Scroll down and expand the Document of Record Template Configuration panel. 15. Select Generate Document of Record.

16. Click Create. 17. Click Edit.

− Data Sources shows the elements of your Form Model. − The Form Container has many important properties.

(46)

Note: The data type defined in the XML Schema will determine the form field.

22. Select your Date Submitted field and click Configure (the wrench icon).

23. Scroll down and notice that the Bind Reference is set to the dateSubmitted node. /data/dateSubmitted

24. Select Set current date as default value. 25. Click Done.

26. Select your Email Sender field and click Configure (the wrench icon). 27. Enter [email protected] as the Default Value.

28. Click Done.

29. Select Components on the left select the Adaptive Form filter.

30. Drag and drop the File Attachment component to the bottom of your form.

31. Select your File Attachment component click Configure (the wrench icon). 32. Enter fileAttachment for the Name.

(47)

35. Select your Attachment Name field and click Configure (the wrench icon). 36. Notice that this is a Required field.

37. Type Enter filename (i.e. mydocument.pdf) as the Placeholder Text. Copy this message to your clipboard. 38. Collapse the Basic panel and expand the Help Content panel.

39. Paste the message into the Short Description and Long Description fields. 40. Click Done.

41. Click Content.

42. Select the Form Container. 43. Select More – Add toolbar.

44. Select the Toolbar and click + Add Toolbar Button. Note: This may appear at the bottom of your screen.

45. Select the Submit Button from the Adaptive Form category. 46. Click Done.

Optional Task: Layout Mode

47. Switch from Edit to Layout mode.

48. Rework the layout so 3 form fields appear on a row in the Desktop emulator. Each form field will be 4 columns in width.

(48)

50. Switch back to Edit mode when you are done.

Create the Workflow Model

1. Select Adobe Experience Manager – Tools – Workflow – Models.

2. Click Create and select Create Model.

3. Enter <yourname>Attachments for your Title. 4. Enter <yourname>Attachments for your Name. 5. Click Done.

(49)

Create Variables

12. Enter A process variable to hold the submitted form data for the Description. 13. Click Open Selection Dialog to the right of the XML Schema Path field.

14. Navigate to the attachments.xsd XML Schema file in Assets. If you are working off a SmartDoc Sandbox, the file will be located in this location.

/content/dam/forms-workflow/attachments.xsd

15. Click Select. 16. Click Done. 17. Click Add Variable.

18. Enter emailReceiver for the Name and select String for the Type. 19. Click Done.

(50)

24. Enter userName for the Name and select String for the Type. 25. Enter <yourname> as the Default Value.

28. Enter dateSubmitted for the Name and select String for the Type.

Note: This is a string datatype because we need to use it later in the email template and the email template requires

a string datatype.

29. Click Done. Your workflow should now look like this.

31. Enter attachmentName for the Name and select String for the Type. 32. Enter defaultAttachmentName.pdf for the Default Value.

(51)

35. Enter attachmentDoc for the Name and select Document for the Type.

38. Enter dor for the Name and select Document for the Type. 39. Click Done.

41. Enter attachment for the Name and select Boolean for the Type. 42. Select false for the Default Value.

43. Click Done.

44. Click Sync. This will create the runtime model.

Set Variables

Follow these steps to set your process variables.

1. Switch from Variables to Steps by clicking the Steps icon in the upper left.

2. Select the Workflow category in the Side Panel. The Goto Step is part of the Workflow category. You can also select All to view it.

(52)

4. Drag and drop the Set Variable step from the Side Panel to your model and place it below the Goto Step. 5. Select your Goto Step and click Configure (the wrench icon).

6. Enter Determine Attachments as the Title.

7. Enter This step contains an ECMA script that determines whether the submission has an attachment as the Description.

8. Click the Process tab and select Set Variable for the Target step. 9. Select ECMA Script for the Routing Expression.

10. Open the Determine Attachments.txt file from your Student Files in Notepad. 11. Copy and paste the script into your Script window.

12. Click Done.

13. Select your Set Variable step and click Configure (the wrench icon). 14. Select the Mapping tab to configure your variable mappings. 15. Click Add Mapping and expand the Map Variable panel. 16. Click Select Variable and select submissionData.

Note: You should skip the Specify XPath for the Variable property for this mapping.

17. Select Relative to Payload for the Mapping Mode.

(53)

21. Select XPath for the Mapping Mode.

22. Select submissionData as the XML Type Variable.

23. Click the checkmark to the right of the XPath field and select emailReceiver.

24. Click Done (the checkmark outlined in red) and you will see your XPath expression set to /data/emailReceiver. 25. Click Add Mapping and expand the Map Variable panel. Note: You may need to scroll down.

26. Click Select Variable and select userName. 27. Select XPath for the Mapping Mode.

29. Click the checkmark to the right of the XPath field and select userName. 30. Click Add Mapping and expand the Map Variable panel.

31. Click Select Variable and select emailSender. 32. Select XPath for the Mapping Mode.

(54)

35. Click Done.

36. Click Add Mapping and expand the Map Variable panel. 37. Click Select Variable and select dor.

38. Select Relative to Payload for the Mapping Mode. 39. Enter dor for the Value.

40. Click Add Mapping and expand the Map Variable panel.

41. Click Select Variable and select dateSubmitted. 42. Select XPath for the Mapping Mode.

44. Click the checkmark to the right of the XPath field and select dateSubmitted. 45. Click Done and you will see your XPath expression set to /data/dateSubmitted. 46. Click Add Mapping and expand the Map Variable panel.

47. Click Select Variable and select attachmentName. 48. Select XPath for the Mapping Mode.

50. Click the checkmark to the right of the XPath field and select attachmentName. 51. Click Done and you will see your XPath expression set to /data/attachmentName. 52. Click Done to save your variable mappings.

53. Click Sync.

Manual XPath Expressions

(55)

In many cases, it will be easier to create the XPath Expressions manually for the following reasons. The Adaptive Form Wrappers

AEM adds an <afData> adaptive form wrapper to your form submission. This wrapper includes two child wrappers of <afUnboundData> for form fields with no binding and <afBoundData> for form fields that are bound to the Form Model. Since these wrappers are not part of your XML Schema, the expressions that the XPath Builder produces will not include them so they will not work.

You also need to consider the XDP wrappers when working with an adaptive form that uses an XDP template as its form model. In this example, we start with an adaptive form bound to an XDP (XML Data Packet) template. The XDP

file is bound to an XML Schema with a root node of /expenseReport (highlighted in blue). When the adaptive form is

submitted, the submitted data is wrapped in /afData/afBoundData/xdp/datasets/data/ (see illustration).

The XDP Wrappers

There is also something important to note about adaptive forms that use the Verify component. Before the Verify component is instantiated on a form, the data is wrapped in these nodes: /afData/afBoundData/xdp/datasets/data/

(see illustration above). However, once the Verify component is instantiated on a form, the data is wrapped in these

nodes: /xdp/datasets/data/ (see illustration below).

(56)

/afData/afBoundData/xdp/datasets/data/expenseReport When the Verify Component is substantiated, the structure is: /xdp/datasets/data/expenseReport

The OR Split

1. Select All or Workflow in the Workflow Steps drop-down. 2. Drag and drop an OR Split onto your workflow model.

3. Select the OR Split and click Configure (the wrench icon). 4. Enter A Split that uses an Expression for the Split Name. 5. Select the Branches tab and expand Branch 1.

6. Click Rename Branch and enter Attachment for the name. 7. Select Default Route.

8. Select Rule Definition for the Routing Expression. 9. Select Click to Add Expression.

10. Select Workflow Variables to show your workflow variables on the left.

(57)

Your expression should now look like this.

13. Click Done.

14. Scroll down and expand Branch 2.

15. Click Rename Branch and enter No Attachment for the name. 16. Select Rule Definition for the Routing Expression.

17. Select Click to Add Expression.

18. Drag and drop the attachment variable to the drop zone on the left. 19. Select IS FALSE.

20. Click Done. 21. Click Done.

22. Click Sync to synchronize your changes with the Runtime Model. You will notice this error. You need to have a valid step in each branch of the the Or Split.

Note: Logically, we don’t need to double our expressions. The first one will work for both cases. If the boolean is true, attachment will be followed. Otherwise, No Attachment will be followed. The doubling of the expressions here is simply for exercise purposes.

(58)

24. Scroll down to the Send Email step.

The Attachment branch

25. Drag and drop the Send Email step to each of your branches.

26. You can now click Sync to synchronize your changes with the Runtime Model.

27. Select the Send Email step on the Attachment branch and click Configure (the wrench icon). 28. Enter Send Email with attachment, dor, and form data for the Title.

29. Select the Email Details tab and notice the Email Subject is set to Literal. 30. Enter Send Email with attachment, dor, and form data for the Subject. 31. Click Open Selection Dialog to the right of the HTML Email Template field. 32. Select the SmartDocEmailTemplate located here.

/apps/forms-workflow/SmartDocEmailTemplate.txt

33. Click Select.

(59)

workitem_username time workitem_sender

Type Variable Variable Variable

Value userName dateSubmitted emailSender

35. Scroll up and select the Sender Details tab. 36. Select Literal if it is not already selected.

39. Select Variable for Recipient’s Email Address and select emailReceiver. 40. Select the Attachments tab and click Add.

41. Select Variable for File Attachment and select attachmentDoc.

42. Select Variable for File Name and select attachmentName. 43. Click Add to add a second attachment.

44. Select Variable for File Attachment and select dor. 45. Select Literal for File Name and enter dor.pdf. 46. Click Add to add a third attachment.

47. Select Variable for File Attachment and select submissionData. 48. Select Literal for File Name and enter submittedData.xml. 49. Click Done and Sync.

(60)

The No Attachment branch

50. Select the Send Email step on the No Attachment branch and click Configure (the wrench icon). 51. Enter Send Email with dor and form data for the Title.

52. Select the Email Details tab and enter The DOR and Form Data are attached for the Subject. 53. Click Open Selection Dialog to the right of the HTML Email Template field.

54. Select the SmartDocEmailTemplate located here. /apps/forms-workflow/SmartDocEmailTemplate.txt

55. Click Select.

56. Map the Email Template Metadata with the values in this table.

workitem_username time workitem_sender

Type Variable Variable Variable

Value userName dateSubmitted emailSender

57. Scroll up and select the Sender Details tab. 58. Select Literal if it is not already selected.

61. Select Variable for Recipient’s Email Address and select emailReceiver. 62. Select the Attachments tab and click Add.

(61)

66. Select Variable for File Attachment and select submissionData. 67. Select Literal for File Name and enter submissionData.xml. 68. Click Done and Sync.

Configure the Form

11. Go back to the <yourname> Attachments form and open it in Edit mode. 12. Click Content and select the Form Container (Adaptive Form Root). 13. Select Configure (the wrench icon).

14. Collapse the Basic panel and expand the Submission panel. 15. In the Submit Action drop-down, select Invoke an AEM workflow. 16. Select your Workflow Model.

17. Enter data.xml for your Data File Path. 18. Enter attachment for the Attachment Path. 19. Enter dor for the Document of Record Path. Your submission setting should look like this.

20. Click Done.

(62)

22. Drag and drop a Check Box to your adaptive form. 23. Select the Check Box and click Configure (the wrench icon). 24. Enter checkbox for the name.

25. Select Hide Title.

26. Enter 0=Include Attachment under Items. 27. Click Done.

28. Select the File Attachment button and click Edit Rules (the gavel icon). 29. Click Create.

30. If the Form Objects and Functions panel is not already open, click Form Objects and Functions. 31. Change the condition menu from WHEN to Show.

32. Click Add Condition.

33. Drag and drop the Check Box form object to the WHEN condition. 34. Select is equal to.

(63)

36. Your rule should now look like this. 37. Click Done and Close.

38. Select the Attachment Name field and click Edit Rules (the gavel icon). 39. Repeat the steps above to create the same rule for the Attachment Name field.

Test your Form and Workflow

40. Select Preview to test your form and workflow. 41. Enter your name in the User Name field.

42. Enter your email address in the Email Receiver field.

43. Click Include Attachment. Notice how the attachment fields become visible.

44. Enter hilton.pdf for the Attachment Name.

45. Click the Attach button under the File Attachment label. 46. Locate hilton.pdf in your Student Files and click Open. 47. Click Submit.

(64)

48. Test your form submission again but this time do NOT select Include Attachment.

This test will test your No Attachment branch.

ECMA Script Details

When you choose ECMA Script as a Routing Expression, you will see this sample script. function check() {

var p = workflowData.getPayload().toString(); var n = workflowSession.getSession().getItem(p); return n.hasNodes();

}

This sample script introduces two important objects; workflowData, and workflowSession. The first line gets the workflow payload path by calling a method of the workflowData object. The second line passes the payload path to the getItem method of the current workflow session. The final line will return true if the payload has nodes and false if it does not.

(65)

Earlier, you created an attachment process variable and set it to false. This script has a similar script variable named haveatt that is also initially set to false (line 7). If fileAttachment is not null and it has nodes (line 10), the script within the if block will executed. Otherwise, the attachment process variable is set to false (line 20).

If the if block does execute, haveatt is set to true and the attachmentDoc and attachmentName variables are set with their values from the workflow. In this case, the attachment process variable is set to true.

(66)

Trouble-Shooting Workflows

This section shows how to trouble-shoot your AEM Forms workflows.

Overview

The Failures section shows the workflows you need to check and trouble-shoot.

(67)

Common Errors

This section details some common errors.

PathNotFoundException

Failure Message

com.adobe.granite.workflow.WorkflowException: org.apache.sling.api.scripting.ScriptEvaluationException: Failure running script /libs/workflow/scripts/dynamic.ecma: Wrapped javax.jcr.PathNotFoundException: attachment (NO_SCRIPT_NAME#5) Step Set Variable Failure Stack Not available Try

Change name from attachment.pdf to attachment.

Cannot coerce value of document variable

Failure Message

Error in converting variable: attachment to type: com.adobe.aemfd.docmanager.Document Step

Send Email with attachment and dor Failure Stack

Caused by: com.adobe.granite.workflow.WorkflowException: [Document Data Type Handler] Cannot coerce value of document variable: attachment to jcr value at

com.adobe.fd.workflow.datatype.DocumentDataTypeHandler.coerceTo(DocumentDataTypeHandler.java:93) at com.adobe.granite.workflow.core.metadata.MetaDataUtilImpl.convertToValue(MetaDataUtilImpl.java:141) Try

You might have an empty attachment value in your payload. If so, you will get this error when you try to map the empty payload to a document variable.

java.lang.NullPointerException

Failure Message

Process execution resulted in an error Step

(68)

Failure Stack

Caused by: com.adobe.granite.workflow.WorkflowException: java.lang.NullPointerException Try

Review the Set Variable step. You might have an empty mapping as shown here.

NO_SCRIPT_NAME#8

Failure Message

com.adobe.granite.workflow.WorkflowException: org.apache.sling.api.scripting.ScriptEvaluationException: Failure running script /libs/workflow/scripts/dynamic.ecma: Wrapped javax.jcr.PathNotFoundException: fileAttachment (NO_SCRIPT_NAME#8)

Step Set Variable Failure Stack

Caused by: com.adobe.granite.workflow.WorkflowException: org.apache.sling.api.scripting.ScriptEvaluationException: Failure running script /libs/workflow/scripts/dynamic.ecma: Wrapped javax.jcr.PathNotFoundException:

fileAttachment (NO_SCRIPT_NAME#8) Try

(69)

About this Courseware

SmartDoc Technologies has supplied the official Adobe-Certified AEM Forms Training courseware to Adobe and Adobe’s clients since 2016. All of the AEM Forms courses listed on Adobe’s website, were created, and are supported by SmartDoc Technologies.

https://learning.adobe.com/