Create a Stepper

A stepper defines the wizard-like sequence of steps that drive a user through an authoring operation.

Create a Stepper

To create a stepper:

  1. Right-click the Steppers node under an entity and select Add Stepper. The Create New Stepper wizard opens.

  2. In the Create New Stepper wizard, enter the following values:

    • Name: Internal name of the object.

    • Label: User-friendly label in this stepper form.

    • On Finish Job: Normally this should be left empty. Semarchy xDM automatically generates a job for you. But in some advanced cases, you may need the ability to specify a particular job to execute. In these cases, you may select the job to execute when the user completes the stepper and submits the data.

    • Collection: Select the collection used to display the entity records at the root level of the stepper.

  3. Click Next.
    The Create Steps step of the wizard displays the forms defined for the entity, expanded to the section level.

  4. Select the tabs or sections from which you want to create steps:

    • Each selected form tab will appear as a form step showing all its child sections and form fields.

    • Each selected form section will appear as a form step showing all its form fields.

  5. Click Finish to close the wizard.

The Stepper editor opens. A root collection step is created in the Steps tree table, with child steps for the selected tabs and sections. Now you may configure the existing steps or add new steps.

Configure Steps

Once the root level of the stepper has been defined, you can:

  • Add new collection steps to author child records.

  • Add new form step under existing form steps.

  • Configure the collection steps

  • Configure the stepper flow.

Add Collection Steps

You can create a collection step to author records referencing the record currently handled by the stepper through a reference relationship.

For example, if a collection step manages Company records, you can create a child collection step to manage Contact records, as Contact references Company through a ContactBelongToCompany relationship.

To create a collection step:

  1. Identify the relationship you are interested in. The current collection step corresponds to the parent entity. Decide which child entity you want to add to the stepper and which reference joins the parent entity to the child entity.

  2. In the Stepper editor, scroll down to the Steps tree table.

  3. Select the collection step under which you want to create a collection step.

  4. In this table’s toolbar, click the Add Collection Step Add Collection Step button.
    The Create New Collection Step wizard opens.

  5. In the Create Collection Step wizard, enter the following values:

    • Name: Internal name of the object.

    • Label: User-friendly label in this collection step.

    • Reference: Reference to follow to identify the child records to author.

    • Collection: Select the collection used to display the child records.

  6. Click Next.
    The Create Steps step of the wizard displays the forms defined for the child entity, expanded to the section level.

  7. Select the tabs or sections from which you want to create steps:

    • Each selected form tab will appear as a form step showing all its child section and form fields.

    • Each selected form section will appear as a form step showing all its form fields.

  8. Click Finish to close the wizard.
    A collection step is created, with child steps for the selected tabs and sections.

  9. Select this collection step and then use the Move Up and Move Down buttons in the toolbar to position the step.

Add Form Steps

You can create additional form steps under collection steps.

To add form steps:

  1. In the Stepper editor, scroll down to the Steps tree table.

  2. Select the collection step under which you want to create a form step.

  3. In this table’s toolbar, click the Add Form Step Add Form Step button.
    The Create New Form Step wizard opens.

  4. In the Create Form Step wizard, the tabs or sections from which you want to create steps:

  5. Click Finish to close the wizard.
    New child steps are created for the selected tabs and sections.

  6. Select these steps and then use the Move Up and Move Down buttons in the toolbar to position them.

Configure Collection Steps

The collection steps show records being authored. Its aspect and content is configurable through certain properties.

To configure a collection step:

  1. In the Stepper editor, scroll down to the Steps tree table.

  2. Select the collection you want to edit.

  3. In the Properties view, set the following properties:

    • Name and Definition

      • Customized Display Card: Select a display card used to represent the authored record in a child step of this collection step. Typically this is a Name and ID to easily identify the record.

    • Collection Data. Note that the root collection step is a specific collection step for which these properties cannot be configured.

      • Reference: Reference to follow to identify the child records to author.

      • Filter: This SemQL condition filters the records to checkout when performing an edit operation that automatically adds to the stepper data child records.
        For example, if the edit operation using this stepper should only add child records whose Status attribute is not set to Obsolete, use the following SemQL expression: Status <> 'Obsolete'

    • Display

      • Collection: Collection used to display the records in the collection step.

      • Default Display Type: Default view type used for this collection.

      • Customized Sort: Select this option to sort the records in the collection according to the Sort Expression.

      • Sort Expression: Sort expression applied to the data in the collection.

      • User-Defined Sort: Check this box to allow users to customize the sort.

      • Allow Table, Allow List and Allow Grid: Select the views available for the collection. These views must be supported by the selected collection.

        Those display properties are automatically disabled when their respective checkbox is deselected in the collection overview. Note that a disabled property whose checkbox has been previously selected in the related stepper will show as a greyed-out checkbox with a checkmark in the list of display properties of the stepper’s collection step. Regardless, the corresponding Table View/List View/Grid View action item will not be available from the action menu when browsing data in the application.
      • Custom Collection Label: Label (plural) used as the title of the collection. It defaults to the Plural Role Label of the Referencing Entity for the selected reference.

The Stepper Flow

The stepper flow defines:

  • The visibility of steps, depending on the authoring situation (whether you are creating or editing a record).

  • Whether a step is read-only or allows authoring.

  • The availability or options in each situation.

Collection Steps Flow

The following properties of the collection steps allow designers to configure the flow of the stepper.

  • In Name and Definition

    • Enable Finish: Adds a finish button on the step to finish the sequence of steps it belongs to. This is useful when all subsequent steps are optional. See the Tips for Configuring the Stepper Flow for additional advice.
      On the root collection step, this allows the user to submit the data in the stepper.

    • Enable on Parent Create: Makes this step visible when the parent record is being created, or, for the root collection step, if the stepper was started to create a record.

    • Enable on Parent Edit: Makes this step visible when the parent record is being edited, or, for the root collection step, if the stepper was started to edit a record.

    • Linear: Forces the user to go through the child steps in their order. If this option is unchecked, users can jump to any of the child steps.

    • Delete Type: Define the type of delete to apply when a user selects to delete a record edited in the stepper. See Record Deletion for more information.

      The Form Fields Mode property applies to form steps only and is ignored for collection steps.
  • In On Parent Create

    • Skip to Child Creation on Parent Create: Skip the collection step and jump directly to the first visible child step when the parent record is being created, or, for the root collection step, if the stepper was started to create a record.

    • Enable Create, Enable Edit, etc: Activate the checked action in the stepper when the parent record is being created, or, for the root collection step, if the stepper was started to create a record. Note that Enable Remove only removes created records from this stepper, but does not delete golden data from the hub.

  • In On Parent Edit

    • Skip to Child Editing on Parent Create: Skip the collection step and jump directly to the first visible child step when the parent record is being edited, or, for the root collection step, if the stepper was started to edit a record.

    • Enable Create, Enable Edit, etc: Activate the checked action in the stepper when the parent record is being edited, or, for the root collection step, if the stepper was started to edit a record. Note that Enable Remove only removes records from this stepper, leaving them untouched in the hub. The Enable Delete option allows deleting golden data from the hub.

    • When Enable Import is checked, Import Mode defines if new records should be created and/or existing records should be updated by import.

Form Steps Flow

The following properties of the form steps allow designers to configure the flow of the stepper.

  • In Name and Definition

    • Enable Finish: Adds a finish button on the step to finish the sequence of steps it belongs to.

    • Enable on Parent Create: Makes this step visible when it is used in a record creation operation.

    • Enable on Parent Edit: Makes this step visible when it is used in a record editing operation.

    • Form Fields Mode: Allows defining how all form fields should appear in the step by overriding the Authoring Mode form field property:

      • If set to Auto, each form field will be displayed according to its Authoring Mode property.

      • If set to Force Browsing, this property forces all fields in the form to appear in Browsing mode (similar to fields in a browsing form).

      • If set to Force Read-Only, this property forces all fields in the form to appear in Read-Only mode (disabled authoring field).

    • Enable Master Value Picking: This option applies to form steps for ID- or fuzzy-matched entities. It enables users overriding a consolidated value to select the override from the master records in addition to being able to enter their own values.

Tips for Configuring the Stepper Flow

The following guidelines help configure the flow of a stepper:

  • Use Automatic to create review steps. When the Authoring Mode has been configured appropriately on fields in forms dedicated to review, users cannot do anything on these steps except move to the previous or next steps.

  • Use the Enable Finish on steps to make all subsequent steps in the sequence optional:

    • For example, if in a sequence of three form steps, the third is optional, make sure to Enable Finish on the second one.

  • Uncheck Linear on collection steps to define a free-form sequence of child steps. Non-linear steppers are usually preferred to modify records and linear steppers are preferred to create records.

  • Uncheck Enable Create, Enable Edit, etc, options to simplify the choices given to the users on steps, but remove them carefully:

    • For example, when you create a stepper specifically to edit existing records, disable On Parent Edit > Enable Create.

    • If the user needs to create a child record in the context of editing (for example, to create a new Address when editing an existing Contact), make sure to Enable Create accordingly.

  • Use the Skip to …​ options to shortcut the creation or editing experience. When this option is selected, the user will not see the collection and will not have to click on the Edit or Create action in the collection.

    • To simplify new Contact creation and have the user arrive directly on the first form step, check the Skip to Child Creation on Parent Create option on the root collection step of the stepper.