How to: Use a many-to-many SmartObject relationship in a check box list

This how-to illustrates how to use a many-to-many SmartObject association in a check box list on a view. Suppose that you have two SmartObjects: Users and Committees. There is a relationship between these two SmartObjects because a user can belong to many committees, and a committee can have many users. Now you want to create a view so you can use a check box list to add or remove committees for specific users.

The form and views you build in this how-to
Many-to-Many Relationship

Try it yourself!

Scenario

You work in Human Resources, where you maintain a list of users along with the committees they belong to. Some users belong to more than one committee. You have a SmartObject for storing user names and another SmartObject for storing committee names. You create a many-to-many association between the two data sources, and use the resulting composite SmartObject generated by the association in a view to maintain the list of users and their committees using one form.

Steps

For this scenario, you build the following artifacts:

Users SmartBox SmartObject - stores user names
Committees SmartBox SmartObject - stores committee names
UserCommittees composite SmartObject - created from the many-to-many association between the Users and Committees SmartObjects
Users Item view - used to add, edit, or delete users
Users List view - displays a list of users that you can click to view their details
Committees Item view - used to add, edit, or delete committees
Users Form - contains the Users List View and Users Item View

You add a many-to-many association to the Users and Committees SmartObjects, generating a composite SmartObject (UserCommittees) as part of the association. You add a Check Box List control to the Users Item view that you populate with a list of committees from the Committees SmartObject. You can add or remove committees for each user from this list control. Finally, you add a form that contains the Users Itemview and the Users List view, allowing you to manage users and their committees from one location.

Setup Steps

The following steps set up the scenario from start to finish. If you want to skip the setup steps and view the topic step, go to Add a Check Box List control and configure it to use a composite SmartObject for data management.

From the Designer, create categories to keep your work organized. Create a new SmartObject called Committees. Add the following property: Committee Name (Text).
In this step, you create the first SmartObject that stores committee names.
1. Launch the Designer.
  If you do not know how to access the Designer, see Accessing Sites.
2. Create categories to keep your work organized. Use the image below as a guide if necessary.
3. Right-click your category and select New SmartObject. Name the SmartObject
  Committees
  and confirm the SmartBox option is selected. Click Create.
4. Click Add. Add a property called
  Committee Name
  and confirm the Type is Text. Click OK. Click Finish to save and exit the SmartObject.
Create a second SmartBox SmartObject called Users. Add one property called User Name (Text). Add a many-to-many association with the Committees SmartObject. Generate a composite SmartObject and name it UserCommittees.
Next, you create the second SmartObject that stores user records. You associate this SmartObject with the Committees SmartObject and generate a composite SmartObject from the two data sources.
1. Right-click your category and select New SmartObject. Name the SmartObject
  Users
  and confirm the SmartBox option is selected. Click Create.
2. Add one property called
  User Name
  and confirm the Type is Text. Click OK.
3. In the Associations tab, click Add. Navigate to and select the Committees SmartObject. Click Next.
4. On the Add Association screen, define the association as follows:
  Users can have many Committees SmartObjects and
  Committees can have many Users SmartObjects.
  After selecting the many-to-many option, you see a new section, Define the composite SmartObject. For the Composite SmartObject value, enter
  UserCommittees
  and click Finish. A third (composite) SmartObject (UserCommittees) is generated that joins data from the Users SmartObject with the Committees SmartObject.
5. Click Finish to save and exit the SmartObject.
In this step, you add records to the Committees SmartObject that populate the check box list control. Generate an Item view from the Committees SmartObject. Keep the default name, Committees Item. Run the view and add at least three records.
1. Right-click the Committees SmartObject and select Generate Views.
2. Select the Item view option and keep the default name, Committees Item. Click OK.
3. Right-click the Committees Item view and select Run.
4. Enter a committee name and click Create. (The ID in the SmartObject is auto-generated, so you do not need to enter a value in this text box.) Because you generate the view from the SmartObject, rules are automatically created to add, edit, delete, and load records. To create another record, type over the first committee name and click Create. Repeat this one more time so you have at least three committee records.
5. Launch the Management site in a new browser window.
6. Expand the Categories node and navigate to the Committees SmartObject. (Your tree structure may not match the image below depending on your naming conventions and categories.) Select the Committees SmartObject. In the central pane, locate and select the Get List method (under the Methods heading) and click Execute.
7. On the Execute SmartObject Method screen, click Execute once again. (You do not need to filter the data.) You should see your committees. Click Done to close the dialog, then return to the Designer.
Generate a List view from the Users SmartObject. Keep the default name, Users List. This view displays a list of users. You will use this view on a form in a later step.
1. Right-click the Users SmartObject and select Generate Views.
2. Select the List option and click OK. (You can keep the default list name, Users List.)
Generate an Item view from the Users SmartObject. Keep the default name, Users Item.
In this step, you generate an Item view from the Users SmartObject. This view serves two purposes: first, you use it to add, edit, or delete users in your Users SmartObject and second, after you click an existing user in the list view, their details load into this item view. You can then edit the user details and committees, and save them back to the data sources.
1. Right-click the Users SmartObject and select Generate Views. Select the Item view option and keep the default name, Users Item. Click OK.

Add a Check Box List control and configure it to use a composite SmartObject for data management

In the following steps, you add a Check Box List control to the Users Item view, then configure the control to use the composite UserCommittees SmartObject generated earlier. You also work with rules to complete the integration for creating and saving records.

Add and configure a Check Box List control on the Users Item view. Edit the Users Item view. Add a new row just above the buttons. Add a Check Box List control to the new row. Edit the Data settings. Check the Display and save a composite SmartObject value option, then select the Committees SmartObject as the value to save back to the composite SmartObject.

Confirm the data source settings match the image below (they should by default). If necessary, change a setting so that it match the image.
1. Right-click the Users Item view and select Edit.
2. Add a new row above the create button row. Select the table cell that contains the Create button. Click the Insert Row Above icon in the toolbar.
3. Click the Toolbox tab on the left side of your screen. Locate and drag a Check Box List control into the first cell of the new row.
4. With the list control selected, locate the Data Source options in the Properties pane. Click the ellipses to open the data Type editor.
5. On the Configure Data Source screen, locate the Use a SmartObject as data source setting (it should be selected by default). Under this setting, check the option to Display and save a composite SmartObject value. (In other words, do you want to associate a value from this list with the composite SmartObject?) Click the ellipses for the Composite SmartObject setting. Select Committees and click OK. This associates a value from the Committees SmartObject with the UserCommittees composite SmartObject. The UserCommittees SmartObject is the junction between the Users and Committees SmartObjects.
6. Your data source settings should look like the image below. If it's not the same, change the setting to match the image. Click OK to save the data source configuration.

In the next two steps, you set up rules to add, edit, and delete records in the Users SmartObject and the UserCommittees composite SmartObject. (You have already added records to the Committees SmartObject.)

Edit the When Save Button is Clicked rule. Use the table below as a guide for editing and adding actions.

Action	Setting	Configuration
Existing then execute the Save method		(configure) Output Mappings: Map the Return Properties > ID to the Mapping Destinations > Users (SmartObject) > ID text box. You want to save the ID of the current record for future reference.
New Execute a method on a control for values that are in a specific state	select method:Save select item state: Checked	(configure) Input Mappings: Map the Users Item (view) > Controls > Check Box List > UserCommittees (SmartObject) > Committees ID to the Input Properties > Committees ID text box. Input Mappings: Map the Users Item (view) > Users (SmartObject > ID to the Input Properties > Users ID text box. You are saving records in the composite SmartObject (UserCommittees) where the two properties (Committees ID and Users ID) match the current record.
New Execute a method on a control for values that are in a specific state	select method: Delete select item state: Unchecked	(configure) Input Mappings: Map the Users Item (view) > Controls > Check Box List > UserCommittees (SmartObject) > Committees ID to the Input Properties > Committees ID text box. Input Mappings: Map the Users Item (view) > Users (SmartObject > ID to the Input Properties > Users ID text box. You are deleting records from the composite SmartObject (UserCommittees) where the Committees ID and Users ID match the current record.
Execution type	All three rule actions	Change the execution type to run as a batch.

Click the Rules tab. Edit the When Save Button is Clicked rule.
In this how-to, you just edit rules for the Save and Create buttons. For a complete solution, be sure to edit the Delete button rule and add actions to delete the record from the Users SmartObject, as well as any linked records in the UserCommittees SmartObject.
Locate the then execute the Save method action. This action saves the record in the Users SmartObject. For example, if you change a user's name, this action updates the record. You need the ID of this record for any records you save to the composite SmartObject. (Remember, the composite SmartObject has only two properties: Users ID and Committees ID. These are the common links between user records and their corresponding committee records.) Click configure.
Click the Output Mappings tab. You want to save the record's ID back to the SmartObject so you can reference it later in other rule actions. On the left side of your screen, expand the Users SmartObject. From the Context Browser on the right side of your screen, drag the Return Properties > ID (from the Context Browser) into the Users > ID text box. Click Finish to save the configuration.

Next, you set up the actions that either create or delete records in the UserCommittees composite SmartObject. If a check box list item is checked, you create a record for it in the composite SmartObject. If a check box list item is not checked, you delete any existing records in the composite SmartObject.

With the Actions tab active, click Execute a method on a control for values that are in a specific state to add it to the rule definition pane. Click the select method link and select Save. Click the select item state and select Checked. Click configure.

The UserCommittees SmartObject has two properties: Users ID and Committees ID. You get the Committees ID from the check box list control (the value of the item checked) and the Users ID from the Users SmartObject. (Remember, you just saved the Users ID back to the SmartObject in the previous step.)

From the Context Browser, expand the Users Item (view) > Controls > Check Box List > UserCommittees (SmartObject). Drag the Committees ID into the Input Properties > Committees ID text box.
Next, map the Users ID. From the Context Browser, expand the Users Item (view) > Users (SmartObject). Drag the ID into the Input Properties > Users ID text box. Click Finish to save the configuration.
In this step, you configure the same action for all items that are unchecked. In this case, you delete the records from the UserCommittees SmartObject. With the Actions tab active, click Execute a method on a control for values that are in a specific state. Select Delete and Unchecked. Click configure.
Map the Context Browser > Users Item (view) > Controls > Check Box List > UserCommittees (SmartObject) > Committees ID to the Input Properties > Committees ID text box.
From the Context Browser, expand the Users Item (view) > Users (SmartObject). Drag the ID into the Input Properties > Users ID text box. Click Finish to save the configuration.
The last step in this rule configuration is to change the action execution types to run as a batch. In this way, all the actions run as a block and must complete before any other rules, conditions, or actions can execute. Locate the then execute the Save method action. Click then. Change it to also. Repeat this for the Create and Delete actions as well.
Your rule should look like the image below. Click OK to save and exit the rule.

In this step, you edit the rule that executes when you click the create button. The rule actions are similar to the save button rule actions. Edit the When Create Button is Clicked rule. Use the table below as a guide for editing and adding actions.

Action	Setting	Configuration
Existing then execute the Create method		(configure) Output Mappings: Map the Return Properties > ID to the Mapping Destinations > Users (SmartObject) > ID text box. You want to save the ID of the current record for future reference.
New Execute a method on a control for values that are in a specific state	select method: Create select item state: Checked	(configure) Input Mappings: Map the Users Item (view) > Controls > Check Box List > UserCommittees (SmartObject) > Committees ID to the Input Properties > Committees ID text box. Input Mappings: Map the Users Item (view) > Users (SmartObject > ID to the Input Properties > Users ID text box. You are creating a record in the composite SmartObject (UserCommittees) that has two properties: Committees ID and Users ID.
Execution type	Both rule actions	Change the execution type to run as a batch.

From the Rules screen, select the When Create Button is Clicked rule and click Edit Rule.
Locate the then execute the Create method action. Click configure.
Click the Output Mappings tab. Once again, you want to save the record's ID back to the SmartObject so you can reference it later in other rule actions. On the left side of your screen, expand the Users SmartObject. From the Context Browser on the right side of your screen, drag the Return Properties > ID into the Users > ID text box. Click Finish to save the configuration.
With the Actions tab active, click Execute a method on a control for values that are in a specific state. Select Create and Checked. Click configure.
From the Context Browser, expand the Users Item (view) > Controls > Check Box List > UserCommittees (SmartObject). Drag the Committees ID into the Input Properties > Committees ID text box.
Next, map the Users ID. From the Context Browser, expand the Users Item (view) > Users (SmartObject. Drag the ID into the Input Properties > Users ID text box. Click Finish to save the configuration.
Change the execution type to run as a batch. Click OK to save the rule.
Click Finish to save and exit the view.

Generate a form with the Users Item and Users List views from the Category Grid. Name the form Users. To use the category grid, select your category title from the All Items menu. The category grid opens in the central pane and displays your artifacts (views, forms, SmartObjects, and workflows). Select the two views, then select Generate Forms from the drop-down menu.
Generate the form with both views using the category grid. In this way, the necessary rules are injected to load the list view when the form opens and link the two views together so that you can click an item in the list view and view the details of that record in the item view. If you prefer, you can create the form, add the views, then manually add the rules for view integration. Using the category grid saves you time since the rules are injected for you.
In this step, you create a form that contains the Users List and Users Item views. You use the category grid to select both views at the same time, then generate the form.
1. Select your category title from the All Items menu. In the image below, the category title is User Committees. You see a list of your artifacts (views, forms, SmartObjects, and workflow) in the central pane, or category grid.
2. Use <CTRL+Click> to select the Users Item view in the category grid. Use <CTRL+Click> to select the Users List view. Both views are now selected. Click the menu icon (it looks like a black down arrow on the right side of your screen) and select Generate Forms.
3. For the Form Name, enter
  Users
  then click OK. (Notice the Form Behavior options. These are the rules that are created on your behalf for loading the list view and integrating the list view with the item view.)
Edit the Users form. Edit the On Users Item, when Create button is Clicked rule. Add an action that clears the item view. Edit the On Users Item, when Save button is Clicked rule. Add an action that clears the item view. This step is not necessary for the composite SmartObject use, but makes it easier for creating multiple items.
1. Right-click the Users form and select Edit.
2. Click the Rules tab. Edit the Users Item (view) > On Users Item, when Create Button is Clicked rule.
3. With the Actions tab active, click Execute a View method. Select Users Item and Clear. Click OK to save the rule.
4. Edit the Users Item > On Users Item, when Save Button is Clicked rule. Add an Execute a View method action. Configure it so that it clears the Users Item view. Click OK to save the rule. Click Finish to save and exit the form.
Test the composite SmartObject by running the Users form. Add users and select committees. Select a user from the list view and confirm their details appear in the item view.
1. Right-click the Users form and select Run.
2. Use the item view to add a new user. Enter a user name and select at least one committee. Click Create.
3. The item view clears and you should see your user displayed in the list view. Create at least one more user. The list view loads all users each time you create a new record.
4. Click a user row. You should see their details load in the item view. If you change the user name or committees, click Save to update the records in the Users and the UserCommittees SmartObjects.

Review

This how-to demonstrated how to create a many-to-many association between two SmartObjects (Users and Committees) that generates a composite SmartObject as part of the configuration. You then used the composite SmartObject on a view with a check box list to maintain data that associates users with committees.