Create a stepper

This page explains how to create and configure a stepper in a Semarchy xDM application. A stepper consists of a wizard-like sequence of steps that guides users step by step through an authoring process.

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 wizard, enter the following values:

    • Name: internal name of the object.

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

    • On Finish Job: this field should typically be left empty, as Semarchy xDM automatically generates a job. However, in some advanced scenarios, 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 is 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 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 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:

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

    • In 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'

    • In 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: select this checkbox to allow users to customize the sorting order.

      • 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 of 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 steps it belongs to. This is useful when all subsequent steps are optional. For more information, see Tips for configuring the stepper flow.
      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 child steps in order. If this option is not selected, 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. For more information, see Record deletion.

      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 selected 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 selected 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 selected, 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 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 involving ID- or fuzzy-matched entities. It enables users to override a consolidated value by selecting the override from master records, alongside entering 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.

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

  • Deselect the Enable Create, Enable Edit, and other options to simplify user choices on steps, but consider the following:

    • When creating a stepper specifically for editing existing records, for example, disable On Parent Edit > Enable Create.

    • If users need to create a child record while editing (e.g., to create a new Address when editing an existing Contact record), make sure to Enable Create accordingly.

  • Use the Skip to options to expedite the creation or editing process. When activated, users skip the collection view and avoid clicking Edit or Create within the collection.

    • To simplify Contact creation and ensure direct user access to the first form step, select the Skip to Child Creation on Parent Create checkbox at the root collection step of the stepper.