How Forms Work

Externable can expose data from Dynamics/Dataverse to the webpage, it can also collect data and save it in Dynamics. Also, you can both retrieve data from Dynamics to prepopulate the form and update it back in Dynamics when user submits a change. That enables you to build scenarios where you not ony capture data like leads or newsletter requests, but you can also allow your end users to work with a subset of data you store in Dynamics/Dataverse.

Externable Forms empower you not only to capture data and map it to Dynamics, but it also allow you to use advanced formulas (like you may know from ETL tools) to manipulate the data before submission.

Externable Forms submit the data to your Dynamics/Dataverse instance without exposing your Dynamics directly to end users, forms are captured and redirected to your Dynamics instance though Externable server.

Form layout editor

When you create your first form in 'Dynamics Forms' section, give it a name.

The first tab you see is the form layout editor:

You can drag and drop desired field types from the right panel to the main form on the left:

When you add a field to the form layout editor, it shows up with its all settings expanded. Some settings are available to all field types (like Label, Class and Name), others are typical to certain field types (like Min/Max value in Numeric field). Use those field settings to adjust form behaviour to your particular needs.

Name field is especially important as you refer to it when you create form mappings. You can't use spaces in the Name field.

Class field is a reference to CSS class name. If you added custom class to your page or content node you can refer to it here.

Prefilling form fields with data

'Expression' field is one of the most imporant parameter in field settings editor. Expression field is a place where you can add your JavaScript expression, which will overwrite field default value. That means that you can use custom JavaScript expressions to prepopulate your form with dynamic data.

Value field is used to set default value with static value. Expression is a JavaScript expression which will overwrite Value field.

As you already know from Creating Dynamics Integrated Content section, you can use references to Dynamics data in JavaScript. If you want your form to be prepoulated with data from Dynamics, you need add your query and then use app.Dynamics.{queryname}.{fieldname} variable to pass that field content to form default field value.

It is worth looking into how that has been done in default template as it heavily relies on Externable default forms.

Submission Settings

When your form layout is ready, go to Submission Settings tab and select what you want to do with the data submitted.

• Target Type - that could be Entity or Action. When end user fills in the form you can submit the form to create/update or delete record in Dynamics but you can also trigger Dynamics Action and map form values to Action parameters.
• Target Entity/Action - depending what you chose in the step before you can select what Entity you want to map your form to or what action you want to trigger. You can click refresh metadata to load the list of Dynamics Entities/Tables.

If you select Action, you need to define the Action name yourself. It will be the schema name ex. new_mytargetaction

• Target Operation - if you selected Entity, choose if you want to Create, Update, Upsert (Create or Update depending if record exists) or Delete the record in Dynamics.
• Use FetchXML Prefiltering - if you selected Update/Upsert/Delete in Target Operation, you can define FetchXML Prefiltering Query. If you tick the tickbox, a field for specifying Prefiltering Query will show up. It is highly recommended to use this feature. Prefiltering Query allows you add FetchXML, which filters your target entity for example to only return records, which are assigned to currently logged in member. Theoretically you could handle it in mappings, but specifying this condition here ensures you that this form submission will not affect any other records then selected in this view.

Only filtering part of the FetchXML will be taken from this field

• Upload File Attachments - when ticked all attachements attached though File Upload field will create a note against the target entity.

Your Entity must have Notes enabled for attachments to be uploaded correctly.

• Redirect To - this field allows you to select Content Node to which the user will be redirected when the form is submitted.

Submission Mappings

The next tab is Submission Mappings. Here you map the data submited through the form to the target Entity or Action.

If you selected Target Type as Entity, you can refresh metadata to push the list of all fields available to the dropdown list. Select target field in Dynamics and click 'Add mapping':

If you have selected Action, you will need to define your input parameters names manually

This will add a row to mappings table, where you can define (with a function or directly) what value you want to submit to target Dynamics field/property.

Lookup fields

If you selected Update/Upsert/Delete Operation Type you will see that Submission Mappings table has 'Is Lookup' column:

If you tick this flag for a row, this row will be used as lookup, so it will be used to resolve which record in Dynamics should be updated. Usually, mapping happens by the record GUID. This is where Prefiltering Querry comes handy - if you use data submitted by the user to resolve what records in Dynamics should be updated, there is security risk, that user may inject different guid than one you gave him/her. To eliminate the risk, you can use prefiltering query to always make sure that end user cannot interact with records other than his own. You could obviously do it by having multiple lookups and use the contact id field to narrow down the search, but prefiltering query eliminates the risk that it will be accidentally missed. Plus, you can use filtering on related records, which comes handy very often.

Formulas

When you added all fields you want to include in the form submission, start mapping form values to target Dynamics fields/properties. Easiest way to do it is by clicking this icon:

When you click it, the full formula editor pops-up:

In the main fomula editor textbox (1) you can see the final formula. When you click on the Form Variables in function tree (2) you can see all form fields you defined. To insert the value from the form click 'Insert to formula' (4). This will insert the form field name into the function. In most cases such single value formula is just enough.

You can insert text or numbers by just passing value streight from the form. Checkboxes and Radio Groups where you defined option values to match Dynamics optionset values can be passed directly to optionset fields. For Entity References (Dynamics Lookup fields), you need to use Dynamics Specific Functions in function tree (2).

If you want to know more about what which function does, you can highlight the function in function tree (2) and read its description in the function description panel (3). Go to section Working with Formulas to find out more about how to use custom functions in formulas.