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 are 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 those of the views available for the collection. These must be supported by the selected Collection.

      • 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 step 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 step 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.

    • Read-Only: Makes this step read-only, preventing any data change operation.

    • 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.

  • 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 step 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 step 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.

    • Read-Only: Makes this step read-only.

    • 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 Read-Only to create review steps. 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 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.