Configure Settings of miniApps and Flows

miniApps and Flows Values Configuration

OCP miniApps® help to convey information to the callers and receive an answer from them. Callers' information is passed to the following miniApps in the Dialog Application by configuring them accordingly.

Each miniApp or Flow building block in the Orchestrator has Input Fields and Output Fields for the receiving and the outgoing information accordingly.

To configure these fields, click the Settings icon in the right upper corner of the selected miniApp or another building block to open the settings window. Read more about configuration options in the Configure Settings of miniApps fields section of this guide.

Input Fields

The Input Fields section contains information that can drive the conversation. It can either be the information provided from the caller’s data (phone number, area calling from, etc.) or the information provided to the caller during the conversation and extracted as output from another miniApp.

The type of input data depends on the type of miniApp and can be set during the miniApp configuration.

To add an Input Field:

1. Click the Settings icon in the right upper corner of the selected miniApp.

2. Click the +Add Input Field button below under the Input Fields section.

By default, each Input Field has the same field name both within the miniApp and Orchestrator. However, it’s possible to set a different Orchestrator Field name for any input miniApp Field name if needed.

Click the Gear icon next to any Input Field to expand its view and configure the corresponding inputs for miniApp Field 1 and Orchestrator Field 1 variables as explained in the Configure Settings of miniApps fields section of this guide.

As you can see on the example below, the miniApp Field 1 automatically matches the name of Orchestrator Field 1 if no changes to the Orchestrator Field 1 were made.

Also, you can remove any added Input Field by clicking the red Trash can near its field name.

Output Fields

OCP miniApps® return values based on the responses of the callers and the information that miniApps are configured to extract from them. The Output Fields section contains the information extracted from the caller while they are talking to the miniApp.

The Output Fields of a miniApp or other building block depend on the type of the miniApp selected and can be used as an Input Field of any next miniApp or Flow building blocks to drive the conversation accordingly.

To add an Output Field:

1. Click the Settings icon in the right upper corner of the selected miniApp.

2. Click the +Add output Field button below under the Output Fields section.

• The miniApp Field 1 is a parameter in the Orchestrator that equals the value of the same parameter configured in the miniApp to contain another parameter with the caller’s response.

• The Orchestrator Field 1 stores the value with the actual caller’s response.

Depending on the miniApp type, the Output Fields can be preconfigured and read-only. However, when the Output Field is not predefined due to its configuration (for example, the Intent miniApp), you can add the preferred miniApp output.

It is possible to mark each added Output Field as optional or non-optional by interacting with the Optional toggle switch next to the field name. By default, each added Output Field is treated as an optional one (with the Optional toggle switch on).

Note that there should be at least one non-optional Output Field among added ones if there’s no non-optional Output Field set by default.

Also, you can remove any added Output Field by clicking the red Trash can near its field name.

By default, each added Output Field has the same field name both within the miniApp and Orchestrator. However, it’s possible to set a different Orchestrator Field name for any added output miniApp Field name if needed.

Click the Gear icon next to any added Output Field to expand its view and configure the corresponding outputs for miniApp Field 1 and Orchestrator Field 1 variables as explained in the Configure Settings of miniApps fields section of this guide.

You can’t change the Orchestrator Field names of the pre-configured Output Fields specific for each miniApp and other building blocks.

As can be seen in the example below, the Orchestrator Field 1 name coincides the miniApp Field 1 name automatically if no changes to the Orchestrator Field 1 name were made.

Underscores in field names were deprecated. Please edit your fields to remove underscores to be able to deploy the application.

If one or more of the miniApps added to the canvas contains Output Fields with underscores, you will see a red warning icon in the upper left corner of the miniApp in question.

If you click Deploy without removing underscores from the fields, the deployment will be blocked with the following error message:

Multiple Output Fields

We recommend keeping the number of added Output fields with “Automatic logging of KVPs” turned ON under 30. If there are more than 30 logging key-value pairs added, you will see a Soft Warning sign in form of an orange dot in the upper corner of the miniApp. This warning doesn’t prevent you from deploying the application and acts as a recommendation.

It is possible to add multiple Output Fields to pass extra information from the caller. For example, if instead of “I want to make a payment” the caller says “I want to put 20$ on my credit card”, this information can be stored by adding some extra Output Fields. This information can be recognized by NLU and passed as an NLU entity by adding the entity name as an Output Field.

Adding extra Output Fields is optional, so if you decide that you don’t need additional output data, the miniApp will still receive all the necessary information to execute.

You can add extra Output Fields by clicking the + Add output Field button under the Output Fields section and use the Optional toggle switch to make it optional or non-optional. Also, you can remove the added Output Field by clicking the Trash can icon to the right of the Optional toggle switch.

This approach is valid for all the miniApp types, except for Intelli and Web Service, since these types of miniApps do not use NLU. Read more about their specifics below.

Multiple Output Fields in Intelli and Web Service miniApps

Adding multiple Output Fields in the Intelli and Web Service miniApps is also applicable. However, if any of these miniApps end while multiple fields are defined without providing any values, the Dialog Application will still run.

Properties Fields

The Properties fields store the extra information of the miniApps configuration, which overwrites some of the pre-configured or default miniApp settings directly in Orchestrator. For example, you can reconfigure the error threshold in a certain miniApp per one usage during the Dialog, whereas this threshold will still be the same (default) in any other cases this miniApp plays.

These Properties are collected in the list of the specific fields that are available for being reconfigured in a certain miniApp. Read the Fail Exit Reason article to find more information about the available specific fields.

Once Properties and their values are reconfigured in Orchestrator, the new parameters are passed to the miniApp. Each Property type can be reconfigured only once in a certain miniApp. 

This functionality is available for all the miniApp types and the Anything Else? building blocks, but not for the Flows.

To overwrite the miniApp configuration, follow the next steps:

1. Сlick the Settings icon in the right upper of the selected miniApp.

2. Switch to the Properties tab and click the + Add Property button.

3. Select the specific field you want to reconfigure in the miniApp from the Property 1 field. For example, choose the Continuous agent request field from the dropdown menu, so it will be reconfigured in the miniApp.

4. Specify the Value 1 field. For example, enter 3 to overwrite the default configurations, so the new value will be used for the selected Property 1 field when the miniApp plays at this step of the Dialog.

5. Click Save when finished. 

Configure Settings of miniApps Fields

miniApp and other building blocks have configurable settings for Input Fields and Output Fields. To successfully drive a conversation, the Output Field of the originating miniApp affects the Input Field of the next ones.

To learn how to configure the settings of a miniApp building block, see the example below:

1. When you add an Input Field (for example, Input Field 1), its field name corresponds to the miniApp field with the same name and contains its data.

2. To configure the field name of the preferred Input Field, click the Gear icon to the right of its field name. See that the expanded view of the Input Field contains miniApp Field 1 and Orchestrator Field 1, where the Orchestrator Field 1 automatically inherits the name of miniApp Field 1. You can choose any other Orchestrator Field 1 from the dropdown options to assign the value of the miniApp Field 1 to be used in Orchestrator further within the current Dialog.

You can add multiple Input Fields to drive the conversation depending on the purpose. When more building blocks are added and more miniApps are connected, more information is elicited from callers, and the dropdown list of possible Input Fields values grows with the Output Fields values of the previous building blocks.

3. Click the Save button to apply the changes.

4. When it comes to the Output Fields, there can be pre-configured read-only Output Fields depending on the miniApp used. The pre-configured Output Fields are added automatically and can’t be changed. However, you can add extra Output Fields besides pre-configured ones and adjust their settings as needed. For building blocks with no pre-configured fields, both main and extra Output Fields can be added and configured.

5. Once you add an Output Field (for example, Output Field 1), its field name corresponds to the miniApp field with the same name and contains its data. To configure the field name of the preferred Output Field, click the Gear icon to the right of its field name. See that the expanded view of the Output Field contains miniApp Field 1 and Orchestrator Field 1, where the Orchestrator Field 1 automatically inherits the name of miniApp Field 1.

6. You can change the default Orchestrator Field 1 name as needed. Thus, the miniApp Field 1 will correspond to the miniApp field, while its value will be assigned to the defined Orchestrator Field 1 variable with a different field name that will be used further in Orchestrator to build the current Dialog.

7. Click the Save button to apply the changes.

7. To configure the Input Field of the next miniApp based on the Output Field of the previous miniApp that contains the caller’s response, select another miniApp, click the Settings icon in its right upper corner and find the corresponding Input Field from the dropdown options. Click Save when finished.

Once all the miniApps and other building blocks are configured, they can pass information to the callers, receive and read their answer, process them to be further used in the next building blocks, and create a conversation that you can test in an Orchestrator Chat.

Configure Global Fields

It is possible to set defined fields as global. Global fields are reusable in all miniApps and Flows within the Application and can be used without explicitly setting them as inputs or outputs over and over again in each building block. Using global fields can help to optimize interaction between Orchestrator and other services.

The built-in fields (for example, ANI, DNIS and so on) can not be set as global fields.

To set the global fields, proceed as follows:

1. Navigate to the Options menu icon on the Application tab and click it to select Global Fields.

2. When clicked, create the global field. It is possible to create more than one global field. Click Save to finish.

3. Select a miniApp, click on its Settings and choose the global field from the list of the Input Fields.

Since Flows are reusable within multiple Applications, the defined global fields can be fetched in any Application that the Flow is used in.

Over-Specification

During the dialog, miniApps obtain values from the conversation with a user and pass values one by one as inputs to next miniApps in the logical order. However, it is also possible to optionally pass more than one value at the same time.

For example, the user wants to pay $100 from his checking account and starts a dialog with the system. Normally, the system should first pull out the value from the user’s response and then proceed to ask the clarifying information using it for upcoming miniApps:

System: How can I help you?
User: I would like to make a payment.
System: So you want to make a payment, correct?
User: Yes, correct.
System: Great! How much would you like to pay?
User: I’d like to pay $100.
System: What account do you want to make a payment from?
User: From my checking account.
System: Ok, when do you want to make a payment?
User: Today please.
System: So, you would like to pay $100 from you checking account ending in 1234 effective today. Is that correct?

To optimize the conversation, the over-specification feature can be used.

Over-specification is a built-in feature of the system that allows understanding and handling of information that is provided by the caller before being explicitly asked. This information can be passed as fields' values after successful validation and confirmation processes configured within the miniApp. Thus, the system doesn’t ask multiple times for the additional data, but receives it all from a single request and fills it in the fields of the upcoming miniApps automatically.

If the first in line miniApp has optional fields that are mandatory for the next in turn miniApp, these fields will be validated and confirmed without re-asking their values.
Note that the optional fields from the first miniApp should have exactly the same names as in the later miniApps they are used in.

Once the over-specification is used, and the validation and confirmation of the miniApp are passed, the dialog would look as following:

System: How can I help you?

User: I would like to pay $100 from my checking account today.

System: So, you would like to pay $100 from you checking account ending in 1234 effective today. Is that correct?

In this example, the user passed not only the intent, but also the amount to be paid, when and from which account. Thus, the system shouldn't re-ask the user for the same information but, instead, it should go directly to confirmation and validation.

To apply correctly the over-specification, do the following:

1. Configure validation and confirmation logic in the miniApps board.

2. Set up the dialog flow to receive these fields as optional entities.

miniApp	Input and Output Fields Configurations

Automated Logging of KVPs

If you want any pair of Input Fields or Output Fields to appear in logs, click on the Logging icon next to the field name in question to turn on the automated logging of KVPs (Key Value Pairs). By default, the automated logging if off (grey icon). Turning this setting on turns the Logging icon blue.

When turned on, automated logging will be triggered when a miniApp or Flow starts or ends execution respectively.