Creating a ServiceNow incident and sending an email when a Wufoo form is submitted

Learn how you can use App Connect Designer to create an event-driven flow that creates an incident in ServiceNow when someone fills in and submits a Wufoo form, and then sends an email to the form submitter.

Note: This tutorial assumes that you have signed up for free or trial accounts for ServiceNow, Wufoo, and Gmail, or that you have business accounts.

Additional reference:

Scenario

You work for the beleaguered IT Help Desk of a large multi-national corporation that receives lots of calls a day from employees about software, hardware, and network issues. Your managers have decided to streamline your Help Desk processes to improve service levels and efficiency, and help energize the team. As part of the change, users now have to use a Wufoo online form to record and submit issues whenever possible.

Courtesy of App Connect, the data captured will be used to automatically create ServiceNow incidents that your team can then monitor and investigate. And after each incident is created, the form submitter will be sent an email to inform them that their issue is being investigated. So for users, this means no more navigating pesky telephone menus or being subjected to background muzak while waiting on hold.

First, find or create everything you need:

Obtain an App Connect on IBM Cloud®® service. You can use an App Connect service that you already have or can sign up for App Connect.
In this example, we use a new free App Connect - Lite plan service.
Obtain account details for connecting App Connect to your integrating applications:
- (If you haven't already connected App Connect to your ServiceNow account):
  - The URL of your ServiceNow instance
  - The user name and password that you use to log in to the instance
  - A client ID (auto-generated) and client secret (user specified, or auto-generated if left blank)
    For information about obtaining these values, see the How to use IBM App Connect with ServiceNow page. This page also tells you how to create a free ServiceNow account for testing if needed.
- (If you haven't already connected App Connect to your Wufoo account) The API key and subdomain of your Wufoo account
  - To find your Wufoo API key, go to the Wufoo Form Manager, open the More drop-down menu for any of your forms, then click API information. (The same 16-digit API key is used for all your forms.) You can copy and paste this API key into App Connect when prompted.
    Figure 1.
  - To find your Wufoo subdomain, go to the Wufoo Account Manager. The subdomain value is included in the URL shown. You can copy and paste this value into App Connect when prompted.
    Figure 2. Finding your Wufoo subdomain
- (If you haven't already connected App Connect to your Gmail account) the OAuth client ID, client secret, access token, and refresh token for your Gmail account. For more information about how to get the required values, see How to use IBM App Connect with Gmail.
If you haven't yet connected to your ServiceNow, Wufoo, or Gmail account, you can do so either from the App Connect Catalog page, or while creating the flow. In this tutorial, we'll connect while creating the flow if required.
It is assumed that in your fictional company, all employees have been set up as users in ServiceNow with the relevant role and group assignments. For this tutorial, let's use the ServiceNow UI to create a user for testing purposes. This user will assume the role of someone who wants to report an IT issue. (To quickly find the Users screen, you can type users in the filter navigator.)
- User ID: aaron.aardvark
- First name: Aaron
- Last name: Aardvark
- Email: (Use a valid email address.)
- Business phone: 02012345678
- Department: Sales
- Ensure the Active check box is selected.
Figure 3. ServiceNow test user

Create and save a Wufoo form for reporting IT incidents:

Create a Wufoo form with the following settings.

Tip:

In this example, we want to include a subset of Wufoo fields that can be easily mapped to the fields found in a ServiceNow incident record. So before designing the form, it's useful to check which fields are mandatory in a new ServiceNow incident record, and which fields provide a pre-populated list of values. This should help us determine which fields in the Wufoo form should be set to Required, and which fields need to offer a set of choices that are the same as those in ServiceNow. In this example, we have set all the Wufoo fields to Required either because ServiceNow requires it, or because we want to ensure that users provide all values that are required for mapping data in the flow.
In the ServiceNow UI, you'll notice that the values for Impact and Urgency are depicted as alphanumeric; for example, 1 - High. However, in our online form we are going to define Impact and Urgency with a field type of Number because these fields are depicted as numeric in App Connect (as mandated by the ServiceNow API used).

Form Name: IT Service Request Form (App Connect Tutorial)

Use the Add a Field and Field Settings tabs to add the following Required fields:

Field Label	Field Type	Field Size
`First name`	Single Line Text	Medium
`Last name`	Single Line Text	Medium
`Email`	Single Line Text	Medium
`Summary of issue`	Single Line Text	Large
`Category of issue`	Drop Down Choices = Inquiry / Help, Software, Hardware, Network, Database	Medium
`Impact (Type 1 for High, 2 for Medium, or 3 for Low)`	Number	Small
`Urgency (Type 1 for High, 2 for Medium, or 3 for Low)`	Number	Small
`Meaningful description of issue`	Paragraph Text	Large

Your form should be similar to the following screen capture:

Figure 4. Wufoo form design for the ServiceNow tutorial

Click Save Form and then go back to the Form Manager.
Click Start sharing next to the form name, if shown. Otherwise, open the Share drop-down menu for the form, then click Copy link.
Figure 5. Start sharing Wufoo form
From the Share page, take note of the permanent link that references your form. (You will need this link later when you test the flow.) Remain logged in.
Figure 6. Permanent link for the Wufoo form (ServiceNow tutorial)

Tip: App Connect supports the use of embedded Wufoo forms. So you could, if required, copy the embed code from the Share page and use it to display the form within your own web page. For example, to embed a form within a WordPress website, all you'll need to do is copy the code on the Embed on WordPress tab and then paste it into a WordPress doc. And then once you publish the doc, you can send users the link to the published doc that contains the embedded form.

Figure 7. Embed on WordPress code in Wufoo

Figure 8. Wufoo Embed on WordPress code in WordPress doc

Next, create your flow:

Using the IBM App Connect Designer authoring experience, complete the following steps to create your flow from scratch if you want to explore the steps taken to create a flow.

From the Dashboard, click New > Event-driven flow.
Complete the following steps. As you progress, App Connect automatically saves your changes. If you navigate away from the flow at any stage, the flow is saved as a draft flow that you can complete at another time.
1. Enter a name that identifies the purpose of your flow; for example: Add an IT service request as an incident.
2. Select Wufoo > New form entry as the event that is to trigger the flow.
  Figure 9. Wufoo New form entry selection
  
  If not already connected, click Connect to Wufoo and then specify the values that will allow App Connect to connect to your Wufoo account. Then click Connect.
3. Select the Wufoo form named IT Service Request Form (App Connect Tutorial) that you created earlier. This selection can be interpreted as "When someone fills in and submits the IT Service Request Form (App Connect Tutorial) form, [perform the action that I'm about to add]". (You will fill in this form later to test the flow.)
  Figure 10. Flow showing the selected Wufoo form
4. Click the (+) and then select ServiceNow > Retrieve system users as the action that App Connect should use to retrieve information about the user who completed the form. (Retrieving these details will help to ensure that the correct person is identified as the 'caller' when the incident record is created.)
  If not already connected, click Connect to ServiceNow and then specify the OAuth credentials that will allow App Connect to connect to your ServiceNow account. Then click Connect.
5. Set a condition for the data retrieval. (From ServiceNow, you want to retrieve the details for a user whose email address matches the email address entered in the Wufoo form. Since email addresses are unique, only one matching user should be found.)
  1. Click Add condition and then select Email from the drop-down list.
  2. Leave the operator as equals. Then in the adjacent field, type em and select Email from the list.
  3. We want to retrieve a single user only, so leave Maximum number of items to retrieve as 1 (the default).
  4. Select If the limit is exceeded: Process 1 item from the collection.
  5. If no user record is found, we want to exit the flow with a '404' error code, so accept the default If no items are found: Exit the flow with a '404' error code setting.
  Figure 11.
6. Click the (+) and then select ServiceNow > Create incident as the action that App Connect should use to create an incident record in ServiceNow.
7. Open the context menu (⋮) for the Create incident action, and then click Switch to advanced mode.
  
  Notice that a host of additional fields are now displayed for you to use. For more information about the advanced mode, see Using advanced mode editing?
8. Configure the following ServiceNow fields by mapping their values to those from Wufoo:
  - Caller: Click within the field and then click Insert a mapping . From the list, expand ServiceNow / Retrieve system users and select First name. Add a space and click Insert a mapping again. Then, under ServiceNow / Retrieve system users, select Last name.
    Your selected values indicate that you want the Caller field in the ServiceNow incident record to be populated with the first and last names of the person whose email address in ServiceNow matches the email address of the person who completed the Wufoo form. Note that this person must already be defined as a user in ServiceNow; otherwise, the Caller field in the resulting ServiceNow incident record will be blank.
  - Category: Click within the field and click Insert a mapping . From the list, expand Wufoo / New form entry and then select Category of issue.
  - Impact: Type im. Then from the list, select Impact (Type 1 for High, 2 for Medium, or 3 for Low) under Wufoo / New form entry.
  - Urgency: Type ur. Then from the list, select Urgency (Type 1 for High, 2 for Medium, or 3 for Low) under Wufoo / New form entry.
    Tip: You have mapped settings for both Impact and Urgency because you want ServiceNow to automatically calculate a Priority value that your team will use to determine how soon an issue needs to be resolved.
  - Short description: Type summ. Then from the list, select Summary of issue under Wufoo / New form entry.
  - Additional comments: Type Description of issue: and add a trailing space. Type mean and then select Meaningful description of issue under Wufoo / New form entry in the list.
  The following image shows what your completed fields should look like. (All other fields are omitted from this image.)
  
  Figure 12.
  
  We'd like to include a few details about the newly created incident in an email to the user who completed the form. So, we'll retrieve these details now using the incident's ID.
9. Click the (+) and then select ServiceNow > Retrieve incidents.
10. Set a condition for the data retrieval.
  1. Click Add condition and then select Incident ID from the drop-down list.
  2. Leave the operator as equals. Then in the adjacent field, type inc and select Incident ID under ServiceNow / Create incident.
  3. Leave Maximum number of items to retrieve as 1, and select If the limit is exceeded: Process 1 item from the collection.
  4. Accept the default If no items are found: Exit the flow with a '404' error code setting.
  Figure 13.
11. Click the (+) and then select Gmail > Create message as the action that App Connect should use to send an email to the user who completed the form.
  If not already connected, click Connect to Gmail and then specify the values that will allow App Connect to connect to your Gmail account. Then click Connect.
12. Complete the Gmail fields as follows:
  - To: Click within the field and then click Insert a mapping . From the list, expand Wufoo / New form entry then select Email.
  - Subject: Type New ServiceNow incident created: then add a trailing space. Click Insert a mapping then select Number under ServiceNow / Retrieve incidents in the list.
  - Body: Type A ServiceNow incident has been created for: then add a trailing space. Click Insert a mapping then select Short description under ServiceNow / Retrieve incidents. Add a period (.) and a space and then type Your incident has been prioritized and added to our queue for investigation.
From the banner, open the options menu [⋮] and click Start flow. Then click Dashboard to exit the flow. Your flow is displayed on your Dashboard as Running, and is listening for your event – a submitted form in Wufoo.
Figure 14.

Note: When creating the flow, you could have taken a shortcut by bypassing the ServiceNow Retrieve system users action and then mapping the Caller field in the Create incident action to the first and last names in the Wufoo form. When the form was submitted, the Caller field in the resulting ServiceNow incident record would have been populated provided the first and last names matched those of an existing ServiceNow user. However, if two or more people share the same first and last name (but have unique user IDs and email addresses), the Caller field in the resulting ServiceNow incident record might not get populated with the correct match. Inserting the Retrieve system users action in the flow ensures that the Caller field is populated with the correct name for the email entered in the form.

Finally, test your flow:

To test the flow, you can assume various roles: that of an IT Help Desk team member, and a user who wants to report an issue with their computer.

[User]:
1. From a new browser tab or window, paste in the permanent link of the Wufoo form that you created earlier.
2. Complete the form as follows:
  - First name: Aaron
  - Last name: Aardvark
  - Email: (Use the same valid email address that you used when you created this user in ServiceNow.)
  - Summary of issue: Application X says No
  - Category of issue: Software
  - Impact (Type 1 for High, 2 for Medium, or 3 for Low): 1
  - Urgency (Type 1 for High, 2 for Medium, or 3 for Low): 1
  - Meaningful description of issue: App X crashed after an unscheduled system update and I can't get it to work even after rebooting. I have a customer report to submit by close of business today. This is critical, so I need a resolution ASAP please. The error message I'm getting is: "Error 5678 - Uh oh! Application X says No."
3. Click Submit.
Figure 15. Completed Wufoo form
[IT Help Desk team member]:
1. Go back to the browser tab or window where you created the form.
2. Go to the Form Manager and verify you can see that an entry has been submitted.
Figure 16. Entry for completed Wufoo form
[IT Help Desk team member]:
1. Log in to ServiceNow using the account that you configured in App Connect and verify that an incident has been created for user Aaron Aardvark with the short description Application X says No. (You might have to wait a few minutes to see the record.)
  Figure 17. New incident record in list
2. Open the incident to view the details.
Figure 18. New incident record
[User]:
1. Log in to the email account of the email address that was specified in the submitted form (and for the test ServiceNow user).
2. Verify that you can see an email with the subject New ServiceNow incident created: incident_number.
Figure 19. New email created by the flow

Conclusion

Congratulations, you have created a flow that creates an incident in ServiceNow whenever someone completes a form in Wufoo, and then sends an email to the form submitter.