--- alias: create-experiment description: "Creating a new experiment involves selecting an existing material and experiment definition, ensuring specified preconditions are met" --- # Create Experiment :lock: Experiment.**Create** ## Overview This operation is used to create a new **Experiment**. There are two ways of creating a new **Experiment**: * By choosing an existing **Experiment Definition**, selecting the **Material** and then selecting **Create Experiment**. * By choosing an existing **Material**, selecting **Create Experiment** and then selecting an **Experiment Definition**. ## Setup No special setup is required other than to meet the preconditions of the transaction. ## Preconditions * The Experiment Management module must be properly licensed in the system. * The **Experiment Definition** exists in the system and there is an effective version for it. * The **Material** exists, is Active in the system and is TopMost. * The **Material** state is Queued if it is currently in the first **Step** of the **Experiment Definition**. If not, there is no precondition for the **Material** state. * The **Material** must not be referenced by any active **Experiment**. * The **Material** must have the same **Flow** as the **Experiment Definition**. * If the **Experiment Definition** defines a **Product** or a **Product Group**, the **Material** must have that **Product** or **Product Group** (via the Product). * If the **Experiment Definition** defines a Required Type, the **Material** must have that Type. * If the **Experiment Definition** defines a Required Form, the **Material** must have that Form. * If the mode is **Sub-Materials**: * There must be a **Material** for every Sub-Materials from position 1 to Required Sub-Material Count that is not an Empty Sub-Material nor is it an Optional Sub-Material. * There can be a **Material** for every Sub-Materials from position 1 to Required Sub-Material Count that is an Optional Sub-Material. * Every **Material** Sub-Material must be assigned to an **Experiment** position – either to a Mandatory or an Optional slot. * Every Sub-Material assigned to the **Experiment** must not be assigned to any other active **Experiment**. * If the **Experiment Definition** defines a Required Sub-Materials Form, the Sub-Materials must have that Form. * If the **Experiment Definition** defines a Max Number Of Materials, then the current number of Experiments' records for the **Experiment Definition** of the **Experiment**, must not be exceeded after this use case is performed. * In case the **Experiment** mode is Sub-Materials, all Sub-Materials to be attached to the experiment must have the following properties cleared (that is not set): **Experiment** and Experiment Sub-Material Number. * If not called from Special Create Experiment - the **Material** either did not reach the First Flow Path as defined in the **Experiment Definition** (and can be in any System State) or is at the First Flow Path as defined in the **Experiment Definition** (and must be Queued). * If called from Special Create Experiment - the **Material** is either at or hasn't yet reached the **Experiment Definition** Flow Path. ## Sequence of Steps As mentioned above, there are two ways of creating an **Experiment**. In this example, we will go through the process of creating a new **Experiment** by choosing an existing **Experiment Definition** and then selecting the **Materials** and the button **Create Experiment**. Start by selecting one of the **Experiment** active instances and select the button **Create Experiment**. ### Step 1: Material 1. Select the **Material** and then select **Next**: ![Screenshot showing a UI for selecting an experiment material.](../images/create_experiment_material_selection.png) 2. If the selected mode is Full Material, only **Materials** without Sub-Materials can be used. If the Experiment Definition Mode is Sub-Materials, you must assign them to Experiment Definition Sub-Material Numbers. ### Step 2: Sub-Materials 1. When the Experiment Definition Mode is set to Sub-Materials, you will need to assign it to the **Material** group and number. You can assign the Sub-Materials manually or select the :mes-static-assign-sm: icon to define the criteria by which you will assign the Sub-Materials: * **Assign by Sub-Material Name** - the first experiment number is assigned with the first Sub-Material sorted by name (ASC). * **Assign by Container and Position** - the first experiment number is assigned with the first Sub-Material sorted by **Container, Position** (ASC). * **Assign Remaining Randomly** - positions are assigned randomly. * **Clear** - remove current assignments. ![Screenshot showing the Create Experiment wizard where the user can select the Sub-Materials to associate with the Experiment.](../images/create_experiment_submaterials.png) When assigning **Materials** to the **Experiment**, if the number of Available Sub-Materials is less than the total number of Sub-Materials specified in the **Experiment Definition** (which includes Mandatory plus Optional Sub-Materials), the Mandatory positions must be assigned first in a sequential order. Otherwise, the system will show the error in the image below. ![Screenshot showing a list of sub-materials with error messages indicating mandatory fields.](../images/create_experiment_submaterials_mandatory_errors.png) Only the Optional Sub-Materials may be left unassigned. ![Screenshot showing the Create Experiment wizard where the user can only leave the optional Sub-Materials unassigned.](../images/create_experiment_submaterials_assignment.png) !!! note It is important to present the container and position information for the Sub-Materials. 2. Optionally, enter a comment. 3. The system will report that the **Experiment** was created successfully. Alternatively, create the **Experiment** by selecting an existing **Material**, selecting the button **Create Experiment** and then choosing an **Experiment Definition**. !!! note After the assignment operation, the Experiment is in state Created.