Create a New Account Wizard¶
Imagine you’ve provided end users with an account page that displays basic account information. Perhaps there’s a Deck at the top of the page flagging hot accounts, and each individual account record includes a drawer that displays the account’s contacts. Maybe users can even open a sliding panel to see full account details.
Sounds like a useful page, doesn’t it? This is a great place for users to manage their daily workflow, so it’s smart to allow them to stay there as much as possible.
But what happens when the user wants to add a new account to the mix? If they Add a Record to the list on the page described above, they can only capture data for the fields that are displayed in the accounts Table. And how do they add the account’s contacts and associate them with the account? Do they need to leave the accounts page to make these updates?
No. With a Wizard component, users can do it all on one page!
Assumptions¶
Note
The steps below assume that you have a page with:
Data sources such as Salesforce have built-in entities to collect and contain account and contact information. However, the “create new record” process described below can easily be adapted to create new records for other types of data source entities.
Create a New Account¶
The steps below set up a step-by-step “create new record” process on the account page, using a modal and the Wizard component, and add associated contacts to that account.
Create two new models [[]]¶
It’s assumed that the page has both an accounts and a contacts model, but we need to clone each to create a new model. Why? The models used for the Wizard will need different properties and conditions from those used on the page, properties and conditions designed specifically to create new records. Safest approach? Clone both models under a new name to use in the Wizard, and make adjustments as needed.
Duplicate the accounts model [[]]¶
Click
on the accounts model, then make the following property edits:- Model ID Give the mode a useful name to distinguish it from the accounts model used for the account list on the page; something like AccountWizard.
- Query on page load: Uncheck this so the model is empty of data when the page is loaded.
- Max # of records: 1
- Create default row if model has none: Check.
Add the fields desired for account record creation. Remember, the original model may only include a few fields to display, but when creating an account, end users may want to capture more details about the company.
Note
Be sure to add the record ID field to the model.
Duplicate the contacts model [[]]¶
Click
on the contacts model used on the page, then make the following property edits:- Model ID Give the model a useful name to distinguish it from the contacts model used for the account list on the page; something like ContactWizard.
- Query on page load: Uncheck.
- Max # of records: 1
- Create default row if model has none: Check.
Add the fields desired for contact record creation. Again, the original model may only include a few fields to display, but when creating a contact, users may want to capture more details about the contact.
Note
Be sure to add the record ID field to the model.
Click
next to Conditions to add a condition.This condition creates a connection between the new account created in the Wizard and the new contact created there. Without this, users can successfully create a new account and a new contact, but the contact will not be connected to the account.
Set up the condition:
- Field: AccountId
- Operator: =
- Value:
- Content: Field from another model.
- Source model: Select the cloned account model (not the original account model).
- Source field: Id
- If no row in **source model, then …**: Deactivate this condition.
- State: Always on.
Click Save.
Create the trigger [[]]¶
Next, users need a “call to action.” Let’s use a Button Set to build a button that will kick off the new account process.
- Drag and drop a Button Set component onto the canvas, above the accounts table.
- In the General tab in the properties pane, set the following:
- Model: Use the model for the accounts table.
- Position: Left.
- The Button Set comes onto the page with one button. Click the newly created button.
- In the General tab in the properties pane, set the following:
- Button label: Create New Account
- Button icon (optional): Select an appropriate icon.
- Button icon position: (optional) Place the icon on the right or left side of the button.
When clicked, this button will need to accomplish a several tasks, so let’s set up those actions:
- In the Actions tab in the properties pane, click
- First action: Ensures that the models to be used in the Wizard start empty each time an end user clicks the action trigger.
- Action type: Remove all rows from model
- Models to empty: The cloned account and contact models (not the originals).
- Second action: After an account and contact are added using the Wizard, Skuid requeries the models on that page that display the list of accounts and the associated contacts. If there is any unsaved data in those models—for example, if the user was in the middle of editing the account or contact and then jumped into the New Account Wizard—that unsaved data will be deleted. This action protects the unsaved data from being lost.
- Action type: Save Model Changes
- Models to Save: The name of the original account and contacts models.
- Roll back entire save on any error: Check.
- Third action: Creates a new row on the cloned account model (for the new record).
- Action type: Create New Row(s)
- Model: The name of the cloned account model.
- Place row at …: Start of Model data.
- Have associated components initially show this row in …: Edit Mode.
- Rows to use: Rows in context
- Fourth action: Opens the modal and allows the user to enter record information.
- Action type: Show Modal
- Click Configure modal.
- Drag and drop a Wizard component into the modal
Add action to create the following actions: - First action: Ensures that the models to be used in the Wizard start empty each time an end user clicks the action trigger.
- Click Save.
With that, you have a button that safeguards any unsaved data from the page, ensures that the Wizard models are empty of data, and opens a modal.
Note
We’re putting the Wizard in a modal so that it’s hidden until the user opens it using the Create New Account button. Otherwise, the Wizard would take up space (and prove distracting) at the top of the page.
Configure the Wizard’s Step 1 [[]]¶
At the end of the fourth action in the last section, we pulled a Wizard component into the modal, and now it’s time to build that Wizard.
Note
When initially added, Wizards include two steps—that’s all we need for this project. To add additional steps, click
Add new step.Add and configure a component [[]]¶
First: build the step that allows users to add a new account.
Note
Make sure you are working in the Wizard’s first step by clicking
1.Add a Form component Wizard.
Click the Form and set its properties:
- Model: The cloned Account model.
- Show save and cancel buttons: Uncheck.
- Default mode: Edit.
Add sections and fields that will capture the necessary information for a new account.
- In the Add fields dialog, click All fields, then click the checkbox next to the desired fields.
Note
If there is no checkbox next to a field, click
to access the checkbox.- Click Apply.
Click Save.
Configure the Next button [[]]¶
Configure a button that lets users navigate to the next step.
Click the Next button. In the General tab, edit:
- Button label: Next Step.
- Button icon: Choose an appropriate icon.
- Button icon position: (optional) Place the icon on the right or left side of the button.
In the Actions tab, add actions to the button
Note
There will already be a Run Wizard Action in place for the Next button, which is included in the Wizard by default. Position the first two actions indicated below before that action. (Click
Add action, then drag and drop the new action to the top of the list.)- First Action: Save all the data entered for the new account.
- Action type: Save model changes
- Models to save: The cloned account model.
- Roll back entire save on any error: check
- Second Action: Set up a new row in the contact model (prep for the next action).
- Action type: Create new rows.
- Model: The cloned contacts model.
- Place row at …: Start of model data.
- Have associated components initially show this row in …: Edit mode
- Rows to use: Rows in context
Third Action: Navigate to the next step. The Run Wizard Action will already be included with the Next button, which should include the following settings:
- Action type: Run Component Action.
- Component: This should already be set to the Form component in the first step.
- Action to run: Navigate to Step
- Step ID: step2.
- First Action: Save all the data entered for the new account.
Click Save.
Add and configure a Cancel button [[]]¶
Configure a second button that lets users cancel their work and return to the underlying page.
Click the white space at the top or bottom of the Wizard to display the
Add button option, then click it.Note
Having trouble accessing this button? Make sure you are inside the Wizard’s blue border, but not inside the component. It can be easier to access the
Add button by clicking the wizard in the bottom, next to the other step buttons.Click the newly created Step button. In the General tab, edit:
- Button label: Cancel
- Button icon: Choose an appropriate icon.
- Button icon position: (optional) Place the icon on the right or left side of the button.
In the Actions tab, add actions to the button:
- First Action: Cancel all changes made in the Wizard.
- Action type: Cancel model changes
- Models to cancel: Both the cloned account model and the cloned contact model.
- Second Action: Close the modal.
- Action type: Close all modals.
- First Action: Cancel all changes made in the Wizard.
Click Save.
Configure the Wizard’s Step 2 [[]]¶
Done with the first step, time to build the second one!
Add and configure a component [[]]¶
Next, build the step that lets users add a contact to that account.
Note
Make sure you are working in the Wizard’s second step by clicking
2.Add a Form component to the Wizard.
Click the Form and set its properties:
- Model: The cloned contact model.
- Show save and cancel buttons: Uncheck.
- Default mode: Edit.
Add sections and fields that will capture the necessary information for a new contact. For this specific wizard, we need to include the First Name and Last Name, plus any other necessary fields from the cloned contact model:
- In the Add fields dialog, click All fields, then click the checkbox next to the desired fields.
Note
If there is no checkbox next to a field, click
to access the checkbox.- Click Apply.
Click Save.
Delete default and format new buttons [[]]¶
Click the Next Step button, then click
Remove to delete it. (Since there isn’t a “next step” for this Wizard, you won’t be needing this.)Click the Back button. Make sure that its properties are:
- Button label: Previous Step.
- Button icon: Choose an appropriate icon.
Also check the Actions tab for Ink Wizard component. Those properties should be:
- Action type: Run Component Action
- Component: This should already be set to the Form component in the first step.
- Action to run: Navigate to Step
- Step ID: step1.
Click the white space at the top or bottom of the Wizard buttons to display the
Add Button option, then click it twice.
Note
Having trouble accessing this button? Make sure you are inside the Wizard’s blue border, but not inside the component. It can be easier to access the
Add button by clicking the wizard in the bottom, next to the other step buttons.Configure a Cancel button [[]]¶
Click the new button immediately to the right of the Previous Step button, then follow the instructions in Wizard Step 1: Add and configure a Cancel button to configure this button as a Cancel button.
Configure a Save button [[]]¶
Configure the button that lets users save the new account and contact, and display them in the list on the underlying page.
- Click the third new button to the right of Previous Step. In the General tab, edit:
- Button label: Save.
- Button icon: Choose an appropriate icon.
- In the Actions tab, add actions to the button:
- First Action: Save all the data entered for the new account and contacts.
- Action type: Save model changes
- Models to save: The cloned account and contact models.
- Roll back entire save on any error: Check.
- Second Action: Requery the models represented on the underlying page so that the newly-added account (and it’s contacts) are displayed.
- Action type: Query models.
- Models to query: The original account and contact models.
- Query behavior: Standard - Completely Replace Data.
- Third Action: Close the Wizard’s modal.
- Action type: Close all modals.
- First Action: Save all the data entered for the new account and contacts.
- Click Save.
Preview and test¶
Now, try it out! The Wizard is a powerful and flexible tool for creating step-by-step workflows that save users time and frustration.
- Need to add a few fields, or reorganize the Forms? Go ahead and edit the Wizard.
- Want to add a third step? Click Add new step and start building.
Use the File Upload Component in Wizards¶
When creating a new record, end users may want to attach a document to the record using the File Upload component.
However, when using the File Upload component in a Wizard that creates a new record—like the example on this page—the File Upload component cannot attach the uploaded file to a newly-created record until the record is saved.
Assumptions¶
Note
This assumes you have a Wizard with a step that involves creating a new record, followed by a step to attach a file to that record.
Build the record creation step [[]]¶
Build a step that creates a record, such as Step 2 from the above Wizard instructions. But instead of removing the Next button and completing the Wizard with a Save button, do the following:
- Click the Next button. Edit the button:
- Button label: Next Step.
- Button icon (optional): Choose an appropriate icon.
- Button icon position: (optional) Place the icon on the right or left side of the button.
- Click the Actions tab.
- Click
- First Action: Save the new record.
- Action type: Save model changes.
- Models to Save: Select the model associated with the new record created in this step.
- Roll back entire save on any error: Check.
- Second Action: Navigate to the next step.
- Action type: Navigate to Step.
- Step ID: The ID of the next step.
Add action twice and edit: - First Action: Save the new record.
Build additional steps [[]]¶
Continue building the Wizard and feel free to include a File Upload component in any of its later steps.
Now that the newly created record has been saved, the File Upload component is able to attach a file to the record.