Modal Assistant¶

The modal assistant is a type of assistant that opens over another page or a general assistant. There maybe use cases where an assistant needs to be invoked while a user is already in the middle of a business flow.

This is similar to invoking a wizard dialog while executing a business flow and returning back to the said business flow after completing the wizard. Such wizard should support accepting data in and passing data out without disrupting the business flow.

This can be simulated by running a regular assistant as a modal (dialog) assistant. Most of the functionality remains more or less the same as any other assistant but there are few differences and limitations since a modal assistant will always be displayed on top a page.

Variations¶

When to use¶

When an assistant is required to be displayed over a page.

How to use¶

1. Define the assistant¶

Refer assistant for the general implementation of an assistant and a detailed explanation of the properties. This document will outline only the special considerations that affect modal assistants.

The declarations below are applicable for modal assistants and should follow the defined order in your code.

	`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	`input` - Applicable for modal assistant only		`valid`
7	`output` - Applicable for modal assistant only		`visible`
8	`keeponrestart`		`@DynamicComponentDependency`
9	`init command`		`calendar`
10	`@DynamicComponentDependency`		`fileselector`
11	`steps`		`group`
12	`finish command`		`list`
13	`restart command`		`selector`
14	`enter command`		`markdowntext`
15	`next command`		`mockimage`
16			`enter command`
17			`next command`
18			`skip command`


//Example Code  
//------------  

assistant ContactAssistant using Contacts {  
   label = "Contact assistant";  
   input(FirstName, LastName); //Specifies which attributes are received by the assistant from where it is declared.  
   output(ContactId); //Specifies which attributes are returned by the assistant to where it is declared.  
   steps {  
      ...  
      }  
}

2. Invoke the assistant¶

Modal assistants are invoked from commands by using the assistant keyword, see example code below.


//Example Code  
//------------  

command AddContact for MyEntity {  
   execute {  
      assistant ContactAssistant(FistName, LastName) into (ContactId);  
      }  
   }  
}

Limitations¶

Invoking multiple modal assistants can cause unexpected client behavior
setup commands cannot be invoked, as they are accessed through the URL
There can be only one input definition (as opposed to multiple setup commands)
If the output property is declared, the outputs must be accepted into variables from the point of invocation.

Properties¶

See the properties section of the assistant.

Steps¶

cancelled step¶

In a modal assistant clicking the cancel command does not direct the user to the cancelled step. Instead clicking cancel will close the assistant with the result CANCEL. This step is optional.

final step¶

Clicking the finish command will direct the user to the final step (if it has any content), if the final step is empty, the assistant is closed with the result OK.

You can add a custom command to the final step and it can return custom results. If a command returns a value, then the assistant will close. If it returns no value, it will stay open.

This step is optional.

Examples¶

Below is an example of an implementation of a basic modal assistant.


// Example code  
//-------------  

//Declaration  
assistant ContactAssistant using Contacts {  
   label = "Contact assistant";  
   input(FirstName, LastName);  
   output(ContactId);  
   steps {  
      step {  
         label = "Contact information";  
         description = "Enter contact information";  
         group ContactInformation;  
      }  
      step {  
         label = "Addresses";  
         description = "Add addresses";  
         list PersonAddressList(Addresses);  
      }  
      final step {  
      }  
   }  
   finish command {  
      execute {  
         call SaveContact();  
      }  
   }  
}  

//Invoking the assistant as a modal assistant  

command AddContact for MyEntity {  
   execute {  
      assistant ContactAssistant(FistName, LastName) into (ContactId) {  
         when OK {  
            info("Contact added successfully")  
         }  
         when CANCEL {  
            alert("Contact assistant cancelled")  
         }  
      }  
   }  
}

Example - Basic implementation of a Modal Assistant