Guided Procedures: Passing email address for Interactive Form step
Here is the scenario: you have an Interactive Form by Adobe that you are using in a Guided Procedure. You want to route the form to a specific email address. This email address should be passed in at runtime. I recently had to do this and didn’t realize just how simple it was. I was trying to get fancy with the roles, but I just needed to keep it simple. So, let’s look at this simple example on passing an email address for a form.
For the first test we will use the process roles to determine who gets the form.
Here is the process I created:
You can see there there is just one block (TestOne), one action (SendEmailForm), and one callable object (EmailForm). The callable object links to an interactive form and sends the form via an email.
The form step is configured to just email out the form, as you can see in the following graphic:
When we discuss Guided Procedures, we say that the role determines who will get each step. So, in this process, to know who would get the form, we look at the Roles tab, and we see the role for SendEmailForm step is set to Initiation Defined. This means when the process starts we will provide who should perform this step.
If you look at the Default Roles tab, you can see this step defaults to my user id, GATLING. GATLING has the email account email@example.com – so the form will come to my work email account.
At runtime, the form appears in my work Outlook account:
OK, so far this is nothing new. Up to this point we have explained how it works by default. You set up a guided procedure, a role is created for each step, and you determine who should do that step.
However, what if I want to pass in an email address to send the form? How can I do that, and how does it effect the Roles tab entries?
For the second test we will send the form to an email address.
This next test is pretty easy. Whenever you create a callable object type of Interactive Form, one of the input parameters you get is email address. Notice the Parameters in the following graphic. To get to this graphic I selected the block, TestOne. Then I clicked on the Parameters tab and selected Input Parameters.
In the graphic the fields FirstName, LastName, SearchTerm1 are fields defined in the form itself, in the .xdp file.
The FormInputData structure and the EmailAddress string are provided by the Guided Procedures framework. Simply by passing an email to this field, the form will be sent to that email address. In the next graphic I have passed an email address to the input field.
Now when I test the process, I enter the various input fields, and I see the email address as one of the fields. I have passed in firstname.lastname@example.org as the email address.
The form now shows up in my hotmail account.
Notice that I did not change anything with my roles. This step is still predetermined to route to my user ID, which is tied to email@example.com. But since I have passed an email account, the form will route to that email address.
As a final test we will add one more step to the process. In this step we will get the email address as an input field and bind it to the send email step. To do this I just added one step to my process. This step is based on the callable object type input form. The step I inserted is called GetEmail.
The GetMail step is an input form with just one field, email. I then do a parameter mapping of my input field email to the EmailAddress of the form step.
Notice that I have selected FormInputData – EmailAddress from the SendEmailForm step and I have selected the email input field from the GetMail step. I have mapped them to a new field called EMAIL_ADDRESS. This will manage the passing of the email address input in the first step to the sending of the form in the second step.
The result is a new group parameter that looks like the following:
For the final test I removed the hard-coded firstname.lastname@example.org in the input parameters. I then start the process again. This time when I start the process I pass in the fields on the form, but I be sure to leave the email blank. Once again, I have not made any changes to the roles. So, the role for the send email step still points to my user ID which is tied to my work email address.
In the following graphic, notice that the role for the SendMailForm step is tied to my portal user ID that links to my work email account. The trick in this whole process is to realize that you don’t do anything to the roles. The processor for this step will get the form if no email is passed in parameter binding.
My process starts, and as the first step I receive an input form where I provide an email address.
The email is bound to the send form step in the parameter mapping, so that I get the email in my hotmail.
So, give it a try! Just remember that the role for the step send email acts as a ‘default’ processor. If no email is passed, we will use the email tied to the role. However, if an email address is passed, the form will be sent to that processor.