Chapter 32. Adxstudio Portals

In September 2015, Microsoft acquired the hugely successful product Adxstudio Portals. Adxstudio Portals provides the ability for organizations running Dynamics CRM to quickly build secure self-service retail portals. Adxstudio Portals extend Microsoft Dynamics CRM to the web, bringing CRM data to life for external users. The Adxstudio Portals solution provides a seamless customer experience with a responsive solution that is optimized for mobile, desktop, and tablet.

The external websites can provide an array of functionality, such as lead gathering/management, product sales, customer support, and event registration and payment.

Adxstudio Portals works with all modern web browsers, and the code is standards compliant with HTML5 and CSS3 for polished display options and full accessibility, regardless of the end user’s device. (All code is responsive, so no additional effort is necessary for mobile development.)

Adxstudio Portals comes with preconfigured starter solutions that have a variety of product applications, such as forums, blogs, and a product catalog, as shown in Table 32.1. You organization can select the combination of these it wants.

Hosted

On-Premises

Hosted requires a monthly subscription fee, and the code lives on Adxstudio Portals servers, which prevents or limits code changes. In addition, there is limited capability to write JavaScript on web forms and entity forms during configuration.

With On-Premises, the code is available for full modification and can be deployed either on an On-Premises server or as a cloud option (that you own).

Either deployment option allows for portal design, branding, and the building of custom or dynamic templates.

The Adxstudio Portals installer allows you to manage Adxstudio Portals components and data in CRM.

When Dynamics CRM Online and hosted Adxstudio Portals are integrated, the Adxstudio Portals installer solution is automatically imported into your Dynamics CRM Online organization. When using Dynamics CRM On-Premises, you need to import the Adxstudio Portals installer solution manually.

To manually install the solution, log in to Dynamics CRM as a user who has the System Administrator security role and navigate to Settings > Solutions. Click Adxstudio Portals Installer at the top of the solutions grid to open up Adxstudio Portals installer solution’s configuration page, as shown in Figure 32.1. You can view components that have already been installed, and you can install new components as necessary.

Community Portal

Retail

Partner Pipeline Portal

Government Portal

Bilingual Company Portal

Intranet Portal

Conference Portal

You can use these portals as is or you can modify them to better you’re your needs. For example, if you are planning to build a portal for an online shopping website, you can start with the Retail portal, which provides basic features like a shopping cart, product reviews, a product catalog, and a store locator. You can then expand and customize it to meet your particular requirements.

In the following sections, you will configure Adxstudio Portals using Dynamics CRM 2016 Online and cloud-hosted Adxstudio Portals, with the Customer Portal installed as a starter portal. You will see how to manage Dynamics CRM data and forms, views, and security, as well as how to do complex multi-step wizard forms using web forms.

Entity forms use the CrmEntityFormView control, which renders the entity form on a web page. This control supports the following features:

CRM field types (except Party List)

CRM field validation rules

Multiple-column layouts

Web resources (HTML and images only)

CRM label language translations

Subgrids (configuration with metadata)

Notes

Lookup-related records filtering

Lookup default view

A common deployment scenario is the creation of a Contact Us form. Users submit their details on the form, and this leads to the creation of a lead record in CRM (either the native Lead entity or a custom entity).

The following example shows a simple example of how to create a form in Adxstudio Portals. Follow these steps to create a Contact Us form:

1. Log on to Dynamics CRM as a user who has the System Administrator security role.

2. Go to Settings > Customization > Customize the System and expand the Lead entity.

For more information about customizing the system, refer to CHAPTER 22, “Customizing Entities.”

3. Click Forms and create a new main form named Contact Us Web Form, as shown in Figure 32.2. This example shows a few out-of-the-box fields added to the form, such as First Name, Last Name, and Address Fields.

4. Save the form and publish all changes.

5. Go to Portals > Entity Forms to create a new entity form.

6. Click New and provide the following details for attributes on the new form (as shown in Figure 32.3):

Name—Contact Us

Entity Name—Lead

Form Name—Contact Us Web Form

Mode—Insert

Enable Entity Permissions—True

7. Navigate to Adxstudio Portals and click the Sign In button in the top-right corner (see Figure 32.4). Log in with the administrator username and password.

8. Once you’re logged in, select the Content menu link in the navigation bar.

9. From the floating menu in the top-right corner (see Figure 32.5), click New > Child Page.

10. In the new page that opens, enter Contact Us as the name of the page and select the Contact Us entity form from the Name drop-down (see Figure 32.6). Click Save to continue.

11. Once the form is saved, open it. Notice that there are required fields on the page (as shown in Figure 32.7). These are the same fields that are required in Dynamics CRM. Enter the data in the fields and click Submit.

12. Navigate back to Dynamics CRM and go to Sales > Leads, and you should see the newly created lead record (see Figure 32.8).

Consider the following about entity permissions:

Entity permissions can be added to any entity in CRM.

Entity permissions are respected by Search and Liquid templates in Adxstudio Portals.

You can add entity permissions to web roles, which allows you to define roles in your organization that correspond to privileges and record access defined in entity permissions.

You can add one or more entity permissions to a web role, and a contact can have one or more web roles.

Table 32.2 lists the entity permission attributes.

The next example shows how the user can update his or her contact records. To allow this to happen, the entity permissions need to be adjusted, using these steps:

1. Go to Portal > Entity Permissions in Dynamics CRM and click New.

2. Provide the following details (as shown in Figure 32.9).

Name—Contact Permissions

Entity Name—Contact

Scope—Contact

Contact Relationship—contact_customer_contacts

Privileges—Read, Write, Create, Delete, Append, and Append To.

Click Save.

3. Scroll down and click the + sign on the Web Roles subgrid. Select the Authenticated Users (as shown in Figure 32.10).

The permissions for the Contact entity have been created and assigned to the Authenticated Users web role. All the contact records that have this role will be able to perform assigned privileges on their related contact records.

To view these permissions, you will create an entity list of contact records. However, prior to doing this, let’s dig a little deeper into entity lists.

In the next example, you will work with an entity list that shows the child contact records of the parent record. The user will be able to create, view, update, activate, and deactivate child contacts from the portal. To do this, three forms are necessary—to allow for the creation, viewing, and update operations.

Create the following three entity forms, following the steps shown earlier in this chapter for creating entity forms, only this time use the following configurations:

Contact Create form:

Name—Contact Create

Entity Name—Contact

Form Name—Profile Web Form

Mode—Insert

Enable Entity Permissions—True

Figure 32.11 shows the completed form.

Contact Edit form:

Name—Contact Edit

Entity Name—Contact

Form Name—Profile Web Form

Mode—Edit

Record Source Type—Query String

Record ID Query String Parameter Name—id

Enable Entity Permissions—True

Figure 32.12 shows the completed form.

Contact Read Only form:

Name—Contact Read Only

Entity Name—Contact

Form Name—Profile Web Form

Mode—ReadOnly

Record Source Type—Query String

Record ID Query String Parameter Name—id

Enable Entity Permissions—True

Figure 32.13 shows the completed form.

Follow these steps to create an entity list and use the entity forms you just created:

1. Go to Portal > Entity Lists to create a new entity list.

2. Click the New button and provide the following details on the new form:

Name—Contacts

Entity Name—contact

3. Click Save, and the View Configuration section is enabled. (If you’re unable to save, select a view first.) Click the +View link to add a drop-down that contains the names of all the available system views in the system. Select the view you want to display to Adxstudio Portals users—and note that you can add more than one view. For this example, add the two views Active Contacts and Inactive Contacts.

4. Keep Page Size 10 as the default, but note that you can modify this as necessary.

5. Keep the default value id in the ID Query String Parameter Name field, as shown in Figure 32.14.

6. Select the check box Enable Entity Permissions.

7. Select the check box Enabled under Search. You can provide Placeholder Text like Search Contacts.

8. Save the record and then go to the Options tab. When entity permissions are enabled, the Configuration section is enabled; however, if entity permissions are not enabled, the configuration section is disabled.

9. In the Configuration section, click the +Download link under Views to enable the Download button to download records from Adxstudio Portals.

10. Click the +Create link to add a drop-down for the entity form that lists all the entity forms for the Contact entity. Select Contact Create from the drop-down list.

11. Click the +Details link in Items and then select Contact Read Only form for entity form from the drop down list, as shown in Figure 32.15.

12. Click the +Edit link in Items and then select the Contact Edit form for the entity form from the drop-down list.

13. Click the +Delete link in Items to add a Delete link under the Actions menu to delete the respective contact record.

14. Click the +Activate and +Deactivate links and select Yes for Confirmation Required? for both. This allows portal users to activate and deactivate contact records.

15. Click the +Column link under Override Column Attributes. This feature allows you to override the column name and width in views. Select the Full Name field from the drop-down, set Display Name to Employee Name, and set Width to 150, as shown in Figure 32.16.

16. Save the entity list record.

Now that the entity list record is configured, navigate to the Adxstudio Portals and select Content Page. Select New Child Page and set Name to Contacts, set Page Template to Full Page, and select Contact from the Entity List drop-down, as shown in Figure 32.17. Click Save.

If you view the page, you can see all child contacts that the logged-on user has in Dynamics CRM. If you select the last column icon, you see all actions available, such as Edit, Delete, Activate, and Deactivate, as previously configured in the entity list. In addition, there are options for Create and Download in the top grid, next to the Search text box (see Figure 32.18).

Selecting View Details in the contacts form opens a modal pop-up with a read-only view of data, as shown in Figure 32.19.

Selecting Edit in the contacts form opens an editable modal pop-up form, as shown in Figure 32.20.

Entity lists are fairly versatile and can be used to show records in a variety of views, including maps. When using the map view, you need to enable map view and then provide latitude and longitude field mapping from the selected entity. The map view uses Bing Maps to render records as pinpoints on a map, and records that do not have any latitude or longitude values don’t show up on the map.

Another popular control is the entity list calendar, which allows rendering of a record as a single event on a calendar. The records that have date fields populated on them are displayed on the calendar. You need to enable calendar view on the entity list record for that entity and provide field mapping for the Start Date field name and End Date field name.

A web form has one or more steps where you can have entity forms or custom web pages.

You can use web forms in user registrations, surveys, and complex data entry processes.

Web forms that include the CrmEntityFormView ASP.NET control render the CRM form in Adxstudio Portals.

Additional configuration options are available in CRM that provide more flexibility in designing forms and changing attributes, styles, and so on.

When a user interacts with the multistep wizard built using web forms, he or she can move from one form to another by using the Next and Previous buttons. The activity is tracked using web sessions. To enable this, you need to set the Start New Session option to Yes on the Load property on the web form record. Opening the web form record in CRM and going to the related web sessions through the navigation shows those records. If there is any change in web form steps later on, it is recommended that you delete all old web session records.

Each multistep web form has more than one step defined, and each web form step has two main properties—Type and Next Step. In Next Step, you select what would be next web form step record. If your web form step is the last step in the multistep wizard, this field is blank.

For the Type attribute, you have the following options:

Condition—This type allows you to evaluate a condition expression. The user inputs some data on web form, and then a condition expression specified in CRM is evaluated. The next web form step to be shown is based on evaluation of the condition expression. For example, in a multistep survey form, you might ask a different set of questions based on the gender of the user. To do this, the Condition type of the web form would have gender=Male as the Condition attribute. Thereafter, you would set the Next Step web form as well as the Next Step if Condition Fails web form. The Next Step web form step is displayed if the condition is true; otherwise, the web form step from the Next Step if Condition Fails attribute is shown.

Load Form—This is the option to set which CRM form you want to show on a web form step.

Load Tab—You can specify what tab from what form in CRM you want to display.

Load User Control—You can create your own custom user controls in .NET and specify the path of the control in your .NET project here.

Redirect—You can specify some other page in Adxstudio Portals or some external web application or website URL here.

Follow these steps to create a simple three-step survey using web forms:

1. Create an entity named Survey and add three tabs in the form. Add some fields on the form with data types like Multiple Lines of Text, Option Set, and Single Line of Text, as shown in Figure 32.21.

The first four fields in Figure 32.21 use the same global option set. By using them and the web form metadata, you can create a multiple choice matrix.

2. Go to Portals > Web Forms and click the New button to create a new web form. Provide the following details on the form and save it (as shown in Figure 32.22):

Name—Web Survey

Authentication Required—Yes

Start New Session on Load—No

Multiple Records Per User Permitted—Yes

3. Set Start Step to Lookup and click the +New button to open a new web step form. Provide the following details on the form and save it (as shown in Figure 32.23).

Name—Step 1

Web Form—Web Survey

Type—Load Tab

Target Entity Logical Name—wf_Survey

Mode—Insert

Form Name—Survey Web Form

Tab Name—tab_1

4. When Step 1 is saved, go to Metadata and create the associated attribute metadata records.

5. Click the +New button for Web Form Metadata and provide the following details (as shown in Figure 32.24):

Web Form Step—Step 1

Type—Attribute

Attribute Logical Name—wf_cost

Style—Multiple Choice Matrix

Group Name—Rating

Provide similar details for the other three attributes that have the same global option set. Make sure the group name is same for rest of the three attribute metadata records.

6. Create attribute metadata for the Location attribute and set the Control Style to Option Set as a Vertical Radio Button List. This changes the options set to radio button vertical list in Adxstudio Portals.

7. Go back to the Step 1 form and select Lookup Next Step and click the +New button to create a new web form step with the following details (as shown in Figure 32.25):

Name—Step 2

Web Form—Web Survey

Type—Load Tab

Target Entity Logical Name—wf_survey

Move Previous Permitted—Yes

Mode—Edit

Form Name—Survey Web Form

Tab Name—tab_2

Source Type—Result from previous step.

8. Similarly, create another web form step named Step 3 for the third tab on the form. The Next Step lookup field should be blank here.

9. Log in to Adxstudio Portals with administrator credentials and add a new page. Set Name to Survey, set Page Template to Full Page, and select Web Survey from the Web Forms drop-down, as shown in Figure 32.26. Click the Save button at the bottom.

When you view the page, you see that the first four attributes have the same option set as a multiple-choice matrix and the Location attribute is shown as a vertical radio button list (see Figure 32.27).

Test the page by entering some data and clicking the Next button. A new record is created in Dynamics CRM, as the Step 1 mode was configured for Insert. The data submitted in the next two steps is updated (not inserted) on the same record.

At press time, Adxstudio Portals had data centers in North America, Europe, and Asia Pacific. It is expected to eventually be available in other data centers where Dynamics CRM Online is hosted.