We have often received requests for people to use Kuali Build to "send out" a form to a list of people. While this isn't available in the default options for Kuali Build, we have created a way for a this to be possible through the use of a special workflow integration.
Here's how to set it up:
Set up the Destination App
First, set up the form that you'd like to assign out to people. Set up all the questions in sections, and mark each section "Office Use Only" in the right-hand sidebar.
Next, set up a new section at the top of your form, name it "Assign To", and drag in a Data Lookup (List) gadget from the "Advanced" section of the left sidebar.
Name the new integration "Person" and use the blue Choose button in the right-hand sidebar to choose the data source Kuali Data > People:
Mark the Person gadget required, and enable Edit unique JSON key and change the unique key to "assignedUser".
Set up the Destination App's Workflow
Still in the app that you'd like to assign out, click the workflow tab, and add an Approve or Task step.
To set up an approval/task to be assigned, configure the workflow step as follows:
- Under Who needs to complete this step? choose A person specified on the form
- Under which field on the form? choose Person
- Enable Make individual form sections at this step hidden or editable
- Set your "Assign To" section to Hide, and set all the other sections that you'd like the assigned person to fill out to Edit
After the workflow is configured with any other steps you need in the workflow, go to the Publish tab and click Publish.
Last, before you leave this app, look at the URL in your browser's address bar, and copy the 24-character string of letters and numbers after the last forward slash (/) in the address. Store this somewhere, because you'll need it later.
Set up the Source App
Start a new app, and name it just like the destination app, with the word "Assign" at the front (e.g. if your destination app is "Event RSVP" you should name your source app "Assign Event RSVP"). This is an optional step, but it will help you keep track of which apps are connected.
In this new app, add a section called "Assign To" and add a Repeater gadget from the bottom of the Special section of the left sidebar. Name the Repeater "List of Assignees"
Drag a new Data Lookup (List) in and configure it for Kuali Data > People as you did on the other app. Name this Mark this gadget as required, and name it "Select A Person". There is no need to set a unique JSON key on this gadget.
Set up the source app workflow
Still on the source app, move to the Workflow tab, and drag in a Echo workflow step. Name it "Assign Each Person" and choose List of Assignees from under Choose the list-type gadget that will be used for this Echo step.
Then, drag in an Integration step and put it inside the grey drag steps here box on your echo step.
Configure the Integration step as follows:
- Name the step "Assign to Destination Form"
- Click the blue choose button and select External Data > Start A Workflow in Another Kuali App then click Continue
- Enter the following under URL Inputs
- Email: Select List of Assignees - Person - Email
- App ID: Paste in the 24-character string you saved from the URL of your destination app.
To finish, go to the Publish tab and click Publish.
Putting it all together
To actually start the process of assigning your destination form to people, do the following:
- From the publish tab of your Source app, click "Share Form" and copy the URL that comes up.
- Go to this URL in your browser. You should see the Source form with the repeater gadget and "Select a Person" in it.
- Add as many people as you'd like to this form, and then click Submit.
- This will automatically assign out your destination form to the people you selected.
How does it work?
In the background, the Start a workflow in another Kuali App integration in your Source app logs into Kuali Build, loads your Destination form, enters a person, and submits it, once for each person you selected on the Source form. Since the only required (non-Office use Only) field is "Person" the destination app submits, and then starts its workflow (once for each person).
When the workflow arrives at the task/approve step you added, it notifies the person in the "Person" field that they've been assigned a task or approval. When they load up their assigned form, they will see the sections that you originally marked as "Office use Only"
FAQ
Q: How can I tell if someone has finished their assignments yet?
A: On the Destination app, go to the Documents tab, click the Columns button near the top, scroll down to Workflow Status and Time On Current Step and click the eyeball icon next to each to display those columns in the table. This will display what step each submission is on, and whether or not it has been completed. It's also a good idea to show the Person column from the same menu so that you can see the assigned person.
Q: On the Destination app, I want to notify the submitter. How do I do that?
A: Since the form is being submitted by the Source app's workflow, the Submitter of the Destination app will always be a special user called "API User". If you want to notify the person you selected in the source app, choose the gadget "Person" instead of "Submitter". It should be available in all the same places.
Q: What if the assigned person misses the first email?
A: On any task/approval step, you can configure Kuali to send reminder emails out to assignees of pending tasks after a specified number of days.
Q: Is there an easier way of assigning people than choosing them one by one? Can I use a group, or paste in a list of email addresses?
A: Not at this time. We are actively working with Kuali to request useful features like this.
Q: How many people can I do at a time?
A: At the moment, the Repeater gadget is limited to 100 repetitions. However, if you try to do more than 10-15 people at a time, you may find that you get workflow errors, and need to retry some of the integration steps. This is not yet tested on a large scale. Please submit a ticket if you encounter any problems.