Skip to content

Assistant

Assistants are a specialized form of a page that guides a user through a sequence of steps. Each step will present the user with a set of controls in a logical order to simplify the process.

In a standard assistant design, you will be able to define 'steps' and the framework will handle the navigation between these steps for you. The framework will also provide an indicator for each step. It is possible to call commands during initialization, on/before going to the next step, and when the assistant is finished or cancelled.

Assistant

Figure 1 - Assistant

Assistants are often associated with virtuals. A virtual is a new type of entity that only differs from a regular entity by not requiring a logical unit (LU). There are no business logic or restrictions attached to it. It is mainly used as a temporary data storage.

Variations

When to use

Common usages include:

  • When it is required to guide a user through an unfamiliar business process or flow
  • When a certain business flow needs to be completed in a specified sequence
  • When you have a complex business flow that can be broken down into smaller logical tasks.

How to use

Below is the basic structure of an assistant.


//Assistance block  
assistant MyAssistant for MyEntitySet {  
   label = "My Assistant";  

   //Steps block  
   steps {  
      //Step block  
      step {  
         label = "Step 1";  
         group Step1Group1;  
      }  
      final step {  
      }  
   }  
   finish command {  
      label = "Finish My Assistant";  
   }  
}  

An assistant is a top-level block similar to a page. It is made up of several code blocks. Each block supports different declarations. While some declarations are optional, the order of these declarations should be maintained. Details of the relevant property is found at the properties section.

assistant block steps block step block
1 label @DynamicComponentDependency label
2 autorestart step description
3 staticlabel final step skipattribute
4 savemode cancelled step optional
5 autocomplete enabled
6 keeponrestart valid
7 setup visible
8 init command @DynamicComponentDependency
9 @DynamicComponentDependency calendar
10 steps fileselector
11 finish command group
12 cancel command list
13 restart command selector
14 enter command markdowntext
15 next command mockimage
16 enter command
17 next command
18 skip command

Properties

Below is a list of properties that can be used to customize the assistant block.

autorestart | keeponrestart | label | savemode | staticlabel

Commands

Assistant related commands are a set of predefined commands which allow you to perform actions during different stages of an assistant's flow. While certain commands support additional properties, all commands support variable declaration and execute blocks.


command {  
   variable Variable1 Text;  
   variable Variable2 Number;  
   execute {  
      set Variable1 = "${Attribute1}";  
      call Method() into Variable2;  
   }  
}  

setup

The setup command can be used to initialize an assistant. One assistant can have multiple setups but only one can be called at a time. This command is optional.


setup Setup1 {  
   variable Variable1;  
   execute {  
      set Attribute1 = Variable1;  
   }  
}  

A defined setup can be invoked using the $action URL parameter. Values can be assigned to variables declared in a setup using the $action=SetupName{VariableName:'${AttributeName}'} notation. Multiple variable assignments should be separated by commas.


execute {  
   navigate "/assistant/MyClient/MyAssistant?$action=InitEquipment{Variable1:'${AttributeX}'}";  
}  

Supported declarations: execute and variable

init command

The init command is executed before the first step is displayed. A common use case is to retrieve default data to populate the assistant with. init command will be executed after the setup command. This command is optional.

Supported declarations: execute variable

finish command

The finish command is executed when the Finish button is clicked on the assistant. Typically used to save data (in virtuals) to the database. This command is mandatory.

Supported declarations: enabled execute icon label style variable visible

cancel command

The cancel command is executed when the user clicks the Cancel button. This command can be used to inquire the user if they want to cancel the assistant and if so, perform any clean up actions. This command is optional.

Supported declarations: enabled, execute, icon, label, message, style, variable, and visible

restart command

The restart command is executed when the user clicks on the Restart (which is named Run Again by default) button. A scenario where this can be used is to navigate away in a flow where you eventually come back to the assistant. This command is optional.

Supported declarations: enabled, execute, icon, label, message, style, variable, and visible

Steps

An assistant is made up of one or more steps (assistants that only have one step are know as Single-step Assistant). All steps should be declared within a steps block.


steps {  
   step {  
      label = "Step 1";  
   }  
   step {  
      label = "Step 2";  
   }  
}  

Properties - Steps

Below is a list of properties that can be used to customize the steps of an assistant.

dynamic

Step

A step contains one or more logically related controls. A user will navigate between these steps in order to complete a business flow in a specific order.

A step indicator is provided along with a label to describe the purpose of the Step the user is currently on.

Properties - Steps

Below is a list of properties that can be used to customize the steps of the assistant.

description | enabled | label | optional | skipattribute | valid | visible

Optional steps

Following are optional steps that can be used based on how the assistant should respond to the finish and cancel commands. Both steps support declarations just like any other step.

final step

The final step will always be the last step to be displayed to the user. Clicking Finish will direct the user to the final step as well.

A common usage of this step is to display a summary of the information entered through an assistant.

cancelled step

The cancelled step is displayed only when the user clicks Cancel.

Commands

Similar to assistant level commands, steps support several predefined steps as well.

enter command

The enter command is executed when the user enters a step.

This command will be executed when performing both forward and backward navigation between steps. The enter command is always executed after the next command of the previous step (if defined and available).

This command is optional and can be used to perform step level initialization.

Supported declarations: enabled, execute, and variable

next command

The next command is executed when the user clicks the Next button. The most common usage of this command is to perform extra validations or fetch data for the next step.

This command is optional.

Supported declarations: enabled, execute, icon, style, and variable

skip command

The skip command is executed when the user decides to skip a specific step by clicking on a step indicator (other than the indicator of the next step). This command is optional and can be used to handle skips by initializing any uninitialized attributes.

Supported declarations: enabled, execute, icon, style, and variable

Examples

Example 1 - Basic assistant implementation

Below is an example of a basic assistant implementation.


//Projection  
//----------  

entityset ContactSet for Contact;  

virtual Contact {  
   attribute PersonId Text;  
   attribute Name Text;  
   array Addresses(PersonId) to Address(PersonId);  
}  

virtual Address {  
   attribute PersonId Text;  
   attribute Address Text;  
}  

action Finish Text {  
   parameter ObjKey Text;  
}  

// Client - Assistant declaration:  
//--------------------------------  

assistant ContactAssistant using ContactSet {  
   label = "Enter new contact";  
   steps {  
      step {  
         label = "Contact information";  
         description = "Enter contact information.";  
         group ContactInformationGroup;  
      }  
      step {  
         label = "Addresses";  
         description = "Add address";  
         list PersonAddressList(Addresses);  
      }  
      final step {  
         description = "Contact ${Name} was created.";  
      }  
      cancelled step {  
         description = "The assistant was cancelled.";  
      }  
   }  
   finish command {  
      variable ReturnValue;  
      execute {  
         call Finish(ObjKey) into ReturnValue;  
         info("${ReturnValue}");  
      }  
   }  
}  

// UI Component definition  
//------------------------  

group ContactInformationGroup for Contact {  
   field PersonId;  
   field Name;  
}  

list PersonAddressList for Address {  
   label = "Addresses";  
   preselect = [false];  
   multiselect = [false];  
   field PersonId {  
      editable = [false];  
   }  
   field Address;  
}  

Example 1 - Basic Assistant Implementation

Example 2 - Assistant with setup and init command

Below is an example of an assistant that uses the setup and init command options.


assistant CreateProjectProcurementAssistant using ProjectDemandVirtualSet {  
   label = "New project demand";  
   setup PartProcActivitySetup {  
      variable Activity {  
         type = Number;  
      }  
      variable Project {  
         type = Text;  
      }  
      execute {  
         set ActivitySeq = Activity;  
         set ActivityProjectId = Project;  
      }  
   }  
   init command {  
      execute {  
         set DemandType = "MISCELLANEOUS_PART_DEMAND";  
      }  
   }  
   steps {  
      step {  
         label = "Project and demand type Information";  
         group ProjectDemandTypeGroup;  
         next command {  
            enabled = [ActivitySeq != null];  
         }  
      }  
      step {  
         label = "Enter demand";  
         markdowntext {  
            text = "Project Miscellaneous Demand";  
         }  
         group PartDemandGroup {  
            visible = [DemandType = "MISCELLANEOUS_PART_DEMAND"];  
         }  
         group NoPartDemandGroup {  
            visible = [DemandType = "MISC_NO_PART_DEMAND"];  
         }  
      }  
      final step {  
         description = "You have successfully added a project demand.";  
         command NavigateToActivityProjectDemand;  
      }  
      cancelled step {  
         description = "The assistant was cancelled.";  
      }  
   }  

   finish command {  
      enabled = [ActivitySeq != null and Site != null and RequiredQuantity != null and  
      ((PartNo != null and DemandType = "MISCELLANEOUS_PART_DEMAND") or(NoPartDescription != null and DemandType = "MISC_NO_PART_DEMAND"))];  
      execute {  
         call CreateProjectProcurement();  
         success("Project part procumbent created.");  
      }  
   }  
   cancel command {  
      execute {  
         confirm("Do you really want to quit the assistant?") {  
            when OK {  
               navigate back;  
            }  
         }  
      }  
   }  
}  

Example 2 - Use of setup and init command